@powerhousedao/reactor 6.1.0-dev.1 → 6.1.0-dev.11

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import { ILogger } from "document-model";
 import * as kysely from "kysely";
 import { Generated, Insertable, Kysely, Transaction } from "kysely";
 import { IProcessor, IProcessorHostModule, IProcessorManager, IProcessorManager as IProcessorManager$1, IRelationalDb, ProcessorApp, ProcessorFactory, ProcessorFactory as ProcessorFactory$1, ProcessorFactoryBuilder, ProcessorFilter, ProcessorRecord, ProcessorStatus, RelationalDbProcessor, TrackedProcessor, TrackedProcessor as TrackedProcessor$1, createRelationalDb } from "@powerhousedao/shared/processors";
+import { Pool } from "pg";
 
 //#region src/attachments/types.d.ts
 /**
@@ -76,7 +77,7 @@ interface IJobExecutionHandle {
   readonly state: JobQueueState;
   start(): void;
   complete(): void;
-  fail(error: ErrorInfo): void;
+  fail(error: ErrorInfo$1): void;
   defer(): void;
 }
 /**
@@ -94,8 +95,8 @@ type Job = {
   queueHint: string[]; /** Number of retry attempts */
   retryCount?: number; /** Maximum number of retries allowed */
   maxRetries?: number; /** Last error if job failed */
-  lastError?: ErrorInfo; /** History of all errors from each attempt (ordered) */
-  errorHistory: ErrorInfo[]; /** Metadata that flows through the job lifecycle */
+  lastError?: ErrorInfo$1; /** History of all errors from each attempt (ordered) */
+  errorHistory: ErrorInfo$1[]; /** Metadata that flows through the job lifecycle */
   meta: JobMeta;
 };
 /**
@@ -104,6 +105,16 @@ type Job = {
 declare const QueueEventTypes: {
   readonly JOB_AVAILABLE: 10000;
 };
+/**
+ * Minimal projection of a Job used by IQueue.dequeueNextMatching predicates.
+ * Exposes only the routing-relevant fields so routing logic (e.g. hash(documentId) % numWorkers)
+ * can live outside the queue without leaking the full Job.
+ */
+type JobRoutingMeta = {
+  documentId: string;
+  scope: string;
+  branch: string;
+};
 /**
  * Event data for job available events
  */
@@ -118,7 +129,7 @@ type JobAvailableEvent = {
 /**
  * Information about an error including message and stack trace.
  */
-type ErrorInfo = {
+type ErrorInfo$1 = {
   message: string;
   stack: string;
 };
@@ -179,8 +190,8 @@ type JobInfo = {
   status: JobStatus;
   createdAtUtcIso: string;
   completedAtUtcIso?: string;
-  error?: ErrorInfo;
-  errorHistory?: ErrorInfo[];
+  error?: ErrorInfo$1;
+  errorHistory?: ErrorInfo$1[];
   result?: any;
   /**
    * A token for coordinating reads, only valid once a job reaches COMPLETED.
@@ -305,6 +316,16 @@ interface IReadModelCoordinator {
    * Stop listening and clean up subscriptions.
    */
   stop(): void;
+  /**
+   * Resolves when every per-queueKey projection chain has flushed.
+   * Intended for test fixtures and explicit shutdown.
+   */
+  drain(): Promise<void>;
+  /**
+   * Current number of in-flight per-queueKey projection chains.
+   * Used as a backpressure signal by observability gauges.
+   */
+  getChainDepth(): number;
 }
 //#endregion
 //#region src/sync/types.d.ts
@@ -538,6 +559,14 @@ interface IOperationStore {
    * The provided revision must match the current head; otherwise a
    * {@link RevisionMismatchError} is thrown.
    *
+   * Returns the stored {@link Operation} rows for the operations that were
+   * appended. On an idempotent replay — detected when a
+   * {@link RevisionMismatchError} or {@link DuplicateOperationError} occurs and
+   * a stored row at the same `(documentId, scope, branch, index)` already has
+   * a matching `opId`, `index`, and `skip` — the previously-stored rows are
+   * returned instead of throwing. If no matching stored row is found, the
+   * original error is propagated unchanged.
+   *
    * @param documentId - The document id
    * @param documentType - The document type identifier
    * @param scope - The operation scope (e.g. "global", "local")
@@ -545,8 +574,9 @@ interface IOperationStore {
    * @param revision - Expected current revision (optimistic lock)
    * @param fn - Callback that stages operations via {@link AtomicTxn}
    * @param signal - Optional abort signal to cancel the request
+   * @returns The stored operations; empty array when no operations were staged
    */
-  apply(documentId: string, documentType: string, scope: string, branch: string, revision: number, fn: (txn: AtomicTxn) => void | Promise<void>, signal?: AbortSignal): Promise<void>;
+  apply(documentId: string, documentType: string, scope: string, branch: string, revision: number, fn: (txn: AtomicTxn) => void | Promise<void>, signal?: AbortSignal): Promise<Operation[]>;
   /**
    * Returns operations for a document/scope/branch whose index is greater
    * than the given revision.
@@ -1211,7 +1241,19 @@ declare const ReactorEventTypes: {
   readonly JOB_WRITE_READY: 10003;
   readonly JOB_READ_READY: 10004;
   readonly JOB_FAILED: 10005;
+  readonly READMODEL_BATCH_COMPLETED: 10006;
+  readonly READMODEL_INDEXED: 10007;
 };
+/**
+ * Stage within ReadModelCoordinator.runChain. Used as a dimension on
+ * stage-attribution events and histograms.
+ */
+type ReadModelStage = "pre_ready" | "emit" | "post_ready";
+/**
+ * Stage in which an individual read model ran. The emit stage does not
+ * involve a read model so it is excluded from this discriminant.
+ */
+type ReadModelIndexingStage = "pre_ready" | "post_ready";
 /**
  * Event emitted when a job is registered and waiting to be executed.
  */
@@ -1267,6 +1309,33 @@ type JobFailedEvent$1 = {
   error: Error;
   job?: Job;
 };
+/**
+ * Event emitted once per batch processed by ReadModelCoordinator.runChain,
+ * after all three projection stages complete. Carries per-stage wall times,
+ * the chain wait time, and the batch size so projection cost can be
+ * attributed by an observer.
+ */
+type ReadModelBatchCompletedEvent = {
+  jobId: string;
+  batchSize: number;
+  chainWaitDurationMs: number;
+  preReadyDurationMs: number;
+  emitDurationMs: number;
+  postReadyDurationMs: number;
+};
+/**
+ * Event emitted once per individual read model per batch and stage, after
+ * that read model's indexOperations call resolves (or rejects). Lets
+ * observers attribute projection cost to a specific read model.
+ */
+type ReadModelIndexedEvent = {
+  jobId: string;
+  readModelName: string;
+  stage: ReadModelIndexingStage;
+  durationMs: number;
+  operationCount: number;
+  success: boolean;
+};
 //#endregion
 //#region src/events/interfaces.d.ts
 /**
@@ -1917,16 +1986,25 @@ declare const JobExecutorEventTypes: {
 type JobStartedEvent = {
   job: Job;
   startedAt: string;
+  /**
+   * Identifier of the executor that took the job. For the worker pool this is
+   * the thread-worker id (e.g. "reactor-worker-3"); for the in-process simple
+   * manager it is "in-process-<index>". Optional for backwards compatibility
+   * with consumers built before the field was added.
+   */
+  workerId?: string;
 };
 type JobCompletedEvent = {
   job: Job;
-  result: JobResult;
+  result: JobResult; /** See {@link JobStartedEvent.workerId}. */
+  workerId?: string;
 };
 type JobFailedEvent = {
   job: Job;
   error: string;
   willRetry: boolean;
-  retryCount: number;
+  retryCount: number; /** See {@link JobStartedEvent.workerId}. */
+  workerId?: string;
 };
 type ExecutorStartedEvent = {
   config: JobExecutorConfig;
@@ -1946,7 +2024,422 @@ type ExecutorManagerStatus = {
   totalJobsProcessed: number;
 };
 //#endregion
+//#region src/executor/worker/protocol.d.ts
+/**
+ * A JSON-clonable value safe to send across the worker IPC boundary.
+ *
+ * The shape mirrors the structured-clone subset used by the parent's
+ * sanitizer: primitives, arrays, plain objects, plus the explicit
+ * {@link ErrorInfo} shape for marshalled Errors.
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type SanitizedArg = null | boolean | number | string | ErrorInfo | SanitizedArg[] | {
+  [key: string]: SanitizedArg;
+};
+/**
+ * Structured representation of an Error for IPC transport.
+ *
+ * Class instances cannot be structured-cloned across worker boundaries,
+ * so Errors are flattened into this shape on the worker side and
+ * reconstructed on the parent side.
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type ErrorInfo = {
+  name: string;
+  message: string;
+  stack?: string;
+  cause?: ErrorInfo;
+};
+/**
+ * Reference to a module that the worker should `import()` at runtime,
+ * along with the named export to pluck out as the factory.
+ *
+ * Exactly one of `packageName` or `filePath` is provided.
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type ModuleRef = {
+  /** Bare-specifier package name (resolved by the worker's module loader). */packageName: string; /** Named export within the module to invoke as the factory. */
+  exportName: string;
+} | {
+  /** Absolute or worker-resolvable file path to import. */filePath: string; /** Named export within the module to invoke as the factory. */
+  exportName: string;
+};
+/**
+ * Factory specification shared by the signature verifier and document
+ * model spec channels. The worker imports `module.exportName` and invokes
+ * it with `initArgs` to obtain the actual instance.
+ *
+ * `initArgs` must be JSON-clonable.
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type FactorySpec = {
+  module: ModuleRef;
+  initArgs?: SanitizedArg;
+};
+/**
+ * Factory spec for the signature verifier the worker should instantiate.
+ *
+ * Structurally identical to {@link FactorySpec}; the alias exists so call
+ * sites read intent-fully.
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type SignatureVerifierSpec = FactorySpec;
+/**
+ * Factory spec for a document model module the worker should instantiate.
+ *
+ * Structurally identical to {@link FactorySpec}; the alias exists so call
+ * sites read intent-fully.
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type DocumentModelSpec = FactorySpec;
+/**
+ * One entry in the document model manifest the worker materializes on
+ * startup (or extends lazily via `load-model`).
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type ModelManifestEntry = {
+  /** Document type identifier (e.g. "ph/account"). */documentType: string; /** Document model version this entry registers. */
+  version: string; /** Factory spec the worker imports and invokes to obtain the model. */
+  spec: DocumentModelSpec;
+};
+/**
+ * JSON-clonable Postgres connection info passed to the worker so it can
+ * open its own pool. Storage-specific wiring may extend this shape in
+ * later phases.
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type DbConfig = {
+  host: string;
+  port: number;
+  database: string;
+  user: string;
+  password: string;
+  ssl?: boolean;
+  applicationName?: string;
+  poolSize?: number;
+  /**
+   * Maximum time (ms) a caller will wait to acquire a connection from the
+   * pool before pg.Pool throws. When omitted, pg defaults to 0 (unlimited
+   * wait), which hides acquire-starvation as silent latency.
+   */
+  connectionTimeoutMillis?: number;
+  /**
+   * How long (ms) an idle connection stays open before pg closes it. When
+   * omitted, pg defaults to 10000.
+   */
+  idleTimeoutMillis?: number;
+};
+/**
+ * Configuration for the executor worker pool.
+ *
+ * Mirrors the `workerPool` sub-config on {@link JobExecutorConfig};
+ * a later card wires this into the executor config.
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type WorkerPoolConfig = {
+  /** Whether the worker pool is active; when false the executor runs in-process. */enabled: boolean; /** Number of worker instances to spawn. */
+  numWorkers: number; /** Worker isolation mode. */
+  workerType: "thread" | "process"; /** Optional heartbeat interval in milliseconds. */
+  heartbeatMs?: number; /** Optional per-worker Postgres pool size override. */
+  workerPgPoolSize?: number;
+};
+/**
+ * Payload the worker reports back when a job's write phase is complete.
+ *
+ * Parent fills `collectionMemberships` at emission time, so it is
+ * intentionally absent from the worker -> parent message.
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type JobWriteReadyPayload = {
+  operations: OperationWithContext$1[];
+  jobMeta: JobMeta;
+};
+/**
+ * Initializes a freshly spawned worker with the configuration and
+ * factories it needs to start executing jobs.
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type InitMessage = {
+  type: "init";
+  correlationId: string;
+  workerId: string;
+  poolConfig: WorkerPoolConfig;
+  db: DbConfig;
+  signatureVerifier: SignatureVerifierSpec;
+  models: ModelManifestEntry[];
+};
+/**
+ * Dispatches a job to the worker for execution.
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type ExecuteMessage = {
+  type: "execute";
+  correlationId: string;
+  job: Job;
+};
+/**
+ * Requests cancellation of an in-flight job.
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type AbortMessage = {
+  type: "abort";
+  correlationId: string; /** correlationId of the `execute` message being aborted. */
+  targetCorrelationId: string;
+  reason?: string;
+};
+/**
+ * Asks the worker to drain in-flight work and exit.
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type ShutdownMessage = {
+  type: "shutdown";
+  correlationId: string; /** Optional grace period before the parent force-terminates the worker. */
+  graceMs?: number;
+};
+/**
+ * Lazily registers an additional document model on a running worker.
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type LoadModelMessage = {
+  type: "load-model";
+  correlationId: string;
+  model: ModelManifestEntry;
+};
+/**
+ * Union of all messages the parent may send to a worker.
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type ParentMessage = InitMessage | ExecuteMessage | AbortMessage | ShutdownMessage | LoadModelMessage;
+/**
+ * Announces that the worker has finished `init` and is ready to accept
+ * `execute` messages.
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type ReadyMessage = {
+  type: "ready"; /** correlationId of the originating `init` message. */
+  correlationId: string;
+  workerId: string;
+};
+/**
+ * Final result for an `execute` job.
+ *
+ * On success, `writeReady` carries the operations and job meta the
+ * parent needs to emit `JOB_WRITE_READY`. On failure, `error` is set
+ * and `result.success` is false.
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type ResultMessage = {
+  type: "result"; /** correlationId of the originating `execute` message. */
+  correlationId: string;
+  result: JobResult;
+  writeReady?: JobWriteReadyPayload;
+  error?: ErrorInfo;
+};
+/**
+ * Acknowledges that a `load-model` request succeeded.
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type ModelLoadedMessage = {
+  type: "model-loaded"; /** correlationId of the originating `load-model` message. */
+  correlationId: string;
+  documentType: string;
+  version: string;
+};
+/**
+ * Reports that a `load-model` request failed.
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type ModelLoadFailedMessage = {
+  type: "model-load-failed"; /** correlationId of the originating `load-model` message. */
+  correlationId: string;
+  documentType: string;
+  version: string;
+  error: ErrorInfo;
+};
+/**
+ * Forwarded log line from the worker. `args` is constrained to
+ * {@link SanitizedArg} so callers cannot accidentally ship non-clonable
+ * values across the boundary.
+ *
+ * The sanitizer in `./sanitize.ts` enforces the {@link SanitizedArg}
+ * invariant on the producer side before each message is posted.
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type LogMessage = {
+  type: "log";
+  level: "debug" | "info" | "warn" | "error";
+  message: string;
+  args: SanitizedArg[]; /** Epoch milliseconds at which the worker generated the log line. */
+  timestamp: number;
+};
+/**
+ * Periodic liveness signal. Included now to unblock Phase-3 scaffolding;
+ * the wiki marks heartbeats as a Phase-5 future extension.
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type HeartbeatMessage = {
+  type: "heartbeat";
+  workerId: string; /** Epoch milliseconds the worker generated the heartbeat. */
+  timestamp: number; /** Optional snapshot of in-flight job correlation ids. */
+  inFlightCorrelationIds?: string[];
+};
+/**
+ * Periodic counters / gauges the worker reports for observability.
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type MetricsMessage = {
+  type: "metrics";
+  workerId: string; /** Epoch milliseconds the worker generated the metrics snapshot. */
+  timestamp: number;
+  counters: {
+    [name: string]: number;
+  };
+  gauges: {
+    [name: string]: number;
+  };
+};
+/**
+ * Snapshot of one worker pool's acquire-wait samples and pool-stat counters,
+ * forwarded periodically so the host can re-record into the shared
+ * pg.Pool histogram and observable gauges. The worker owns the real
+ * pg.Pool; the host's {@link PoolInstrumentation} is a forwarder driven
+ * by these messages.
+ */
+type PoolAcquireSamplesMessage = {
+  type: "pool-acquire-samples";
+  workerId: string; /** Stable identifier matching the host-side instrumentation name (e.g. "worker-0"). */
+  poolName: string; /** Epoch milliseconds the worker generated the batch. */
+  timestamp: number; /** Acquire-wait durations (ms) accumulated since the previous batch. */
+  durations: number[]; /** Most recent pg.Pool counter snapshot at batch send time. */
+  size: number;
+  idle: number;
+  waiting: number;
+};
+/**
+ * Union of all messages a worker may send to the parent.
+ *
+ * @see Wire Protocol Reference wiki page
+ *   (Powerhouse board wiki id: 64c03e51-1aa4-4fa9-93d8-daa45642484d)
+ */
+type WorkerMessage = ReadyMessage | ResultMessage | ModelLoadedMessage | ModelLoadFailedMessage | LogMessage | HeartbeatMessage | MetricsMessage | PoolAcquireSamplesMessage;
+//#endregion
 //#region src/executor/interfaces.d.ts
+/**
+ * Snapshot of the single in-flight slot maintained by an {@link IExecutorWorker}.
+ */
+type WorkerInFlightSnapshot = {
+  correlationId: string;
+  jobId: string;
+};
+/**
+ * Outcome of a worker-side job execution.
+ *
+ * `result` mirrors the in-process `JobResult` exactly. `writeReady` carries
+ * the operations + jobMeta the parent needs to emit `JOB_WRITE_READY`, and is
+ * present only when the worker produced operations. It is absent on failure
+ * and on success-with-no-operations.
+ */
+type WorkerExecutionOutcome = {
+  result: JobResult;
+  writeReady?: JobWriteReadyPayload;
+};
+/**
+ * Parent-side handle for a single executor worker.
+ *
+ * Implementations wrap an IPC transport (worker_threads, child_process, or a
+ * test fake) and expose a transport-agnostic surface that the worker-pool
+ * manager uses to dispatch jobs. The handle owns one worker's lifecycle
+ * (`start` -> `execute`* -> `shutdown`) and bounds its in-flight map to a
+ * single entry; `SimpleJobExecutor` is single-threaded inside the worker, so
+ * concurrent dispatches would race its caches.
+ */
+interface IExecutorWorker {
+  /** Stable identifier of the worker (mirrors `InitMessage.workerId`). */
+  readonly workerId: string;
+  /** Zero-based index within the pool, used for sticky routing. */
+  readonly index: number;
+  /**
+   * Spawn the worker (if not already started), send the `init` payload and
+   * resolve when the worker replies with `ready`.
+   */
+  start(): Promise<void>;
+  /**
+   * Dispatch a job to the worker and resolve with its outcome — the
+   * `JobResult` and, on success-with-operations, a `writeReady` payload
+   * the parent will enrich and re-emit. Rejects with a transport-level
+   * error if the worker exits, aborts, or times out before producing a
+   * result.
+   */
+  execute(job: Job, signal?: AbortSignal): Promise<WorkerExecutionOutcome>;
+  /**
+   * Request cancellation of the in-flight job (if any). The handle posts an
+   * `abort` message; if the worker fails to reply within its grace window it
+   * is force-terminated.
+   */
+  abort(correlationId: string, reason?: string): void;
+  /**
+   * Stop the worker. When `graceful` is true the handle waits for the
+   * in-flight job to settle (up to `graceMs`) before terminating; otherwise
+   * the worker is terminated immediately.
+   */
+  shutdown(graceful: boolean, graceMs?: number): Promise<void>;
+  /**
+   * Register an additional document model on the running worker. Resolves
+   * when the worker replies with `model-loaded`; rejects when it replies
+   * with `model-load-failed` or the worker exits before answering.
+   */
+  loadModel(entry: ModelManifestEntry, signal?: AbortSignal): Promise<void>;
+  /** True when no job is currently in flight. */
+  isIdle(): boolean;
+  /** Snapshot of the in-flight slot, or null when idle. */
+  getInFlight(): WorkerInFlightSnapshot | null;
+}
 /**
  * Simple interface for executing a job.
  * A JobExecutor simply takes a job and executes it - nothing more.
@@ -2019,7 +2512,7 @@ interface IJobTracker {
    * @param error - Error information including message and stack trace
    * @param job - Optional full job object for debugging purposes
    */
-  markFailed(jobId: string, error: ErrorInfo, job?: Job): void;
+  markFailed(jobId: string, error: ErrorInfo$1, job?: Job): void;
   /**
    * Retrieve the current status of a job.
    *
@@ -2064,6 +2557,18 @@ interface IQueue {
    * @returns Promise that resolves to the next job execution handle or null if no jobs available
    */
   dequeueNext(signal?: AbortSignal): Promise<IJobExecutionHandle | null>;
+  /**
+   * Get the next available job whose routing metadata satisfies the predicate.
+   * Walks ready sub-queue heads in queue insertion order, skips heads whose document
+   * is currently executing (same isDocumentExecuting gate as dequeueNext), and returns
+   * the first head for which predicate returns true.
+   * Returns null when paused, when nothing matches, or when the queue is empty.
+   * Rejects if signal is already aborted.
+   * @param predicate - Filter applied to JobRoutingMeta of each candidate head
+   * @param signal - Optional abort signal to cancel the request
+   * @returns Promise that resolves to the first matching job execution handle or null
+   */
+  dequeueNextMatching(predicate: (meta: JobRoutingMeta) => boolean, signal?: AbortSignal): Promise<IJobExecutionHandle | null>;
   /**
    * Get the current size of the queue for a specific document/scope/branch.
    * @param documentId - The document ID
@@ -2113,14 +2618,14 @@ interface IQueue {
    * @param error - Optional error information
    * @returns Promise that resolves when the job is marked as failed
    */
-  failJob(jobId: string, error?: ErrorInfo): Promise<void>;
+  failJob(jobId: string, error?: ErrorInfo$1): Promise<void>;
   /**
    * Retry a failed job.
    * @param jobId - The ID of the job to retry
    * @param error - Optional error information from the failure
    * @returns Promise that resolves when the job is requeued for retry
    */
-  retryJob(jobId: string, error?: ErrorInfo): Promise<void>;
+  retryJob(jobId: string, error?: ErrorInfo$1): Promise<void>;
   /**
    * Returns true if and only if all jobs have been resolved.
    */
@@ -2201,9 +2706,15 @@ type RegistrationResult<T> = {
  * Loader that can asynchronously resolve and return a document model module
  * for a given document type. Used by the queue to gate CREATE_DOCUMENT jobs
  * until the required model is available in the registry.
+ *
+ * `resolveSpec` is an optional companion that returns the IPC-clonable spec
+ * for the same document type. Implementations that integrate with the worker
+ * pool must provide it so the parent can broadcast `load-model` to workers
+ * after registering the model on the parent.
  */
 interface IDocumentModelLoader {
   load(documentType: string): Promise<DocumentModelModule<any>>;
+  resolveSpec?(documentType: string): Promise<ModelManifestEntry | null>;
 }
 /**
  * Registry for managing document model modules.
@@ -2488,6 +2999,53 @@ interface DocumentIndexerDatabase {
   IndexerState: IndexerStateTable;
 }
 //#endregion
+//#region src/storage/pool-instrumentation.d.ts
+/**
+ * Snapshot of a pg.Pool's internal counters at a point in time.
+ */
+type PoolStats = {
+  /** Connections currently open (idle + in-use). pg.Pool.totalCount. */size: number; /** Open connections not currently checked out. pg.Pool.idleCount. */
+  idle: number; /** Callers queued waiting for a connection. pg.Pool.waitingCount. */
+  waiting: number;
+};
+/**
+ * Observable handle over an instrumented pg.Pool. Surfaces acquire-wait
+ * timing and pool-stat counters without coupling the consumer to the
+ * underlying pg.Pool type.
+ */
+type PoolInstrumentation = {
+  /** Stable identifier for the pool (e.g. "host", "worker"). Used as a metric label. */readonly name: string; /** Current pool counters. Cheap, synchronous read off pg.Pool. */
+  getStats(): PoolStats;
+  /**
+   * Subscribe to per-acquire wait durations. Listener fires once per
+   * resolved pool.connect() call with the time spent waiting for a client.
+   * Returns an unsubscribe function.
+   */
+  onAcquire(listener: (durationMs: number) => void): () => void;
+};
+/**
+ * Wraps an existing pg.Pool with acquire-wait timing and an event
+ * subscription surface. The pool is mutated in place: pool.connect()
+ * is replaced with a timing wrapper so all callers (Kysely included)
+ * pick up the instrumentation transparently.
+ */
+declare function instrumentPgPool(pool: Pool, name: string): PoolInstrumentation;
+/**
+ * Host-side {@link PoolInstrumentation} that re-emits acquire-wait samples
+ * and pool-stat snapshots forwarded from a worker thread. The worker owns
+ * the real pg.Pool; this object lets the host's OpenTelemetry instrumentation
+ * subscribe to those events as if the pool were local.
+ *
+ * The host wires one of these per worker (one per executor worker, one per
+ * projection shard). The worker batches acquire-wait durations and periodic
+ * stats over its existing transport; the host pumps them in via
+ * {@link pushSamples} / {@link updateStats}.
+ */
+type ForwardingPoolInstrumentation = PoolInstrumentation & {
+  pushSamples(durations: number[]): void;
+  updateStats(stats: PoolStats): void;
+};
+//#endregion
 //#region src/sync/errors.d.ts
 declare class PollingChannelError extends Error {
   constructor(message: string);
@@ -3113,6 +3671,13 @@ interface ReactorModule {
   processorManagerConsistencyTracker: IConsistencyTracker;
   syncModule: SyncModule | undefined;
   reactor: IReactor;
+  /**
+   * Instrumented pg.Pool handles registered with the builder, either by
+   * createPostgresDatabase or by withInstrumentedPool. Empty when no pg
+   * pool is in use (e.g. PGlite tests). Observers iterate the array to
+   * record per-pool acquire-wait and stat metrics.
+   */
+  pools: PoolInstrumentation[];
 }
 /**
  * Container for all reactor client dependencies created during the build process.
@@ -3156,9 +3721,67 @@ declare class DriveClient implements IDriveClient {
   copyNode(driveIdentifier: string, srcNodeId: string, targetParentFolderId: string | undefined, signal?: AbortSignal): Promise<DocumentDriveDocument>;
   getNode(driveIdentifier: string, nodeId: string, signal?: AbortSignal): Promise<Node>;
   listNodes(driveIdentifier: string, parentFolder?: string | null, paging?: PagingOptions, signal?: AbortSignal): Promise<PagedResults<Node>>;
+  private documentExists;
   private removeFileNode;
 }
 //#endregion
+//#region src/cache/collection-membership-cache.d.ts
+interface ICollectionMembershipCache {
+  getCollectionsForDocuments(documentIds: string[]): Promise<Record<string, string[]>>;
+  invalidate(documentId: string): void;
+}
+//#endregion
+//#region src/registry/document-model-resolver.d.ts
+interface IDocumentModelResolver {
+  ensureModelLoaded(documentType: string): Promise<void>;
+}
+/**
+ * Post-success hook called after the resolver registers a newly loaded
+ * model on the parent's registry. Used to broadcast `load-model` to the
+ * worker pool so workers can register the same model locally.
+ */
+type ModelLoadedBroadcastHook = (entry: ModelManifestEntry) => Promise<void>;
+/**
+ * Encapsulates the logic for resolving document model modules on demand.
+ * Shared between the queue (CREATE_DOCUMENT gate) and the executor manager
+ * (post-failure recovery) so that both paths use the same deduplication
+ * and failure-caching state.
+ */
+declare class DocumentModelResolver implements IDocumentModelResolver {
+  private registry;
+  private loader;
+  private loadingModels;
+  private failedModelTypes;
+  private broadcastHook;
+  constructor(registry: IDocumentModelRegistry, loader: IDocumentModelLoader);
+  /**
+   * Install a post-success hook called after the resolver registers a
+   * newly loaded model. ReactorBuilder uses this to wire the worker-pool
+   * `load-model` broadcast without touching the resolver's constructor.
+   */
+  setBroadcastHook(hook: ModelLoadedBroadcastHook): void;
+  ensureModelLoaded(documentType: string): Promise<void>;
+  private broadcastIfPossible;
+}
+/**
+ * No-op resolver used when no document model loader is configured.
+ * Checks the registry for the model and returns if found; throws if not.
+ * Since there is no loader, missing models cannot be recovered.
+ */
+declare class NullDocumentModelResolver implements IDocumentModelResolver {
+  private registry?;
+  constructor(registry?: IDocumentModelRegistry | undefined);
+  ensureModelLoaded(documentType: string): Promise<void>;
+}
+//#endregion
+//#region src/executor/worker-pool-job-executor-manager.d.ts
+/**
+ * Factory invoked once per worker at `start()` time. The index is the
+ * worker's position in the pool and the same value the manager will use
+ * for sticky routing (`bucketFor(documentId) === index`).
+ */
+type WorkerFactory = (index: number) => IExecutorWorker;
+//#endregion
 //#region src/cache/write-cache-types.d.ts
 /**
  * Configuration options for the write cache
@@ -3191,6 +3814,207 @@ type KeyframeSnapshot = {
   document: string;
 };
 //#endregion
+//#region src/projection/protocol.d.ts
+/**
+ * Identifier for a built-in read model the projection worker materializes
+ * on init. The host names which models each shard should run; the worker
+ * constructs them itself against its local Kysely instance.
+ */
+type BuiltInReadModelKind = "document-view" | "document-indexer";
+/**
+ * Initializes a freshly spawned projection worker. The worker uses
+ * `db` to open its own pg.Pool + Kysely, loads `models` into a local
+ * `DocumentModelRegistry`, materializes each `readModelKinds` entry as a
+ * concrete read model bound to the local DB, and starts a local
+ * `ReadModelCoordinator` that consumes the JOB_WRITE_READY relays.
+ */
+type ProjectionInitMessage = {
+  type: "init";
+  correlationId: string;
+  shardId: string;
+  shardIndex: number;
+  shardCount: number;
+  db: DbConfig;
+  models: ModelManifestEntry[];
+  preReadyKinds: BuiltInReadModelKind[];
+  postReadyKinds: BuiltInReadModelKind[];
+  chainDepthReportIntervalMs: number;
+};
+/**
+ * Relays a JOB_WRITE_READY event from the host bus into the worker's
+ * local bus, where the in-worker `ReadModelCoordinator` picks it up.
+ *
+ * The host fans messages to shards via `bucketFor(documentId, shardCount)`
+ * — the worker does not re-hash and assumes the message landed on it
+ * because the host already chose this shard.
+ */
+type ProjectionWriteReadyMessage = {
+  type: "write-ready";
+  jobId: string;
+  operations: OperationWithContext$1[];
+  jobMeta: JobMeta;
+  collectionMemberships?: Record<string, string[]>;
+};
+/**
+ * Asks the worker to drain its in-flight chains and respond with
+ * {@link ProjectionDrainedMessage}.
+ */
+type ProjectionDrainMessage = {
+  type: "drain";
+  correlationId: string;
+};
+/**
+ * Asks the worker to drain in-flight work, close its DB pool, and exit.
+ */
+type ProjectionShutdownMessage = {
+  type: "shutdown";
+  correlationId: string;
+  graceMs?: number;
+};
+type ProjectionParentMessage = ProjectionInitMessage | ProjectionWriteReadyMessage | ProjectionDrainMessage | ProjectionShutdownMessage;
+/**
+ * Announces that the worker has finished `init` and is ready to accept
+ * `write-ready` relays.
+ */
+type ProjectionReadyMessage = {
+  type: "ready";
+  correlationId: string;
+  shardId: string;
+};
+/**
+ * Forwarded JOB_READ_READY event from the worker's local bus. The host
+ * re-emits this on the host bus so observers (sync manager, awaiters,
+ * tests) see it exactly once per job.
+ */
+type ProjectionReadReadyMessage = {
+  type: "read-ready";
+  shardId: string;
+  jobId: string;
+  operations: OperationWithContext$1[];
+};
+/**
+ * Forwarded READMODEL_INDEXED event from the worker's local bus.
+ */
+type ProjectionReadModelIndexedMessage = {
+  type: "readmodel-indexed";
+  shardId: string;
+  jobId: string;
+  readModelName: string;
+  stage: ReadModelIndexingStage;
+  durationMs: number;
+  operationCount: number;
+  success: boolean;
+};
+/**
+ * Forwarded READMODEL_BATCH_COMPLETED event from the worker's local bus.
+ */
+type ProjectionBatchCompletedMessage = {
+  type: "readmodel-batch-completed";
+  shardId: string;
+  jobId: string;
+  batchSize: number;
+  chainWaitDurationMs: number;
+  preReadyDurationMs: number;
+  emitDurationMs: number;
+  postReadyDurationMs: number;
+};
+/**
+ * Periodic chain-depth report. Workers post this on a fixed cadence so
+ * the host can aggregate per-shard depths without polling.
+ */
+type ProjectionChainDepthMessage = {
+  type: "chain-depth";
+  shardId: string;
+  depth: number;
+  timestamp: number;
+};
+/**
+ * Snapshot of one shard's pg.Pool acquire-wait samples and pool-stat
+ * counters. The shard owns its real pg.Pool; the host's
+ * {@link PoolInstrumentation} is a forwarder driven by these messages.
+ */
+type ProjectionPoolAcquireSamplesMessage = {
+  type: "pool-acquire-samples";
+  shardId: string; /** Stable identifier matching the host-side instrumentation name. */
+  poolName: string; /** Epoch milliseconds the worker generated the batch. */
+  timestamp: number; /** Acquire-wait durations (ms) accumulated since the previous batch. */
+  durations: number[]; /** Most recent pg.Pool counter snapshot at batch send time. */
+  size: number;
+  idle: number;
+  waiting: number;
+};
+/**
+ * Acknowledges that a `drain` request has flushed all in-flight chains.
+ */
+type ProjectionDrainedMessage = {
+  type: "drained";
+  correlationId: string;
+  shardId: string;
+};
+/**
+ * Forwarded log line from the worker. Mirrors the executor worker's
+ * sanitized log envelope so callers can route both through the same
+ * host-side logger.
+ */
+type ProjectionLogMessage = {
+  type: "log";
+  shardId: string;
+  level: "debug" | "info" | "warn" | "error";
+  message: string;
+  args: SanitizedArg[];
+  timestamp: number;
+};
+type ProjectionWorkerMessage = ProjectionReadyMessage | ProjectionReadReadyMessage | ProjectionReadModelIndexedMessage | ProjectionBatchCompletedMessage | ProjectionChainDepthMessage | ProjectionPoolAcquireSamplesMessage | ProjectionDrainedMessage | ProjectionLogMessage;
+//#endregion
+//#region src/projection/transport.d.ts
+type ProjectionTransportEventMap = {
+  message: ProjectionWorkerMessage;
+  error: Error;
+  exit: number;
+};
+type ProjectionTransportEvent = keyof ProjectionTransportEventMap;
+type ProjectionTransportListener<E extends ProjectionTransportEvent> = (payload: ProjectionTransportEventMap[E]) => void;
+/**
+ * Minimal subset of `worker_threads.Worker` the {@link ProjectionShardManager}
+ * relies on. The host writes against this interface so tests can swap in
+ * a fake transport without spawning real worker threads.
+ */
+interface IProjectionTransport {
+  postMessage(message: ProjectionParentMessage): void;
+  on<E extends ProjectionTransportEvent>(event: E, listener: ProjectionTransportListener<E>): void;
+  off<E extends ProjectionTransportEvent>(event: E, listener: ProjectionTransportListener<E>): void;
+  terminate(): Promise<number>;
+}
+//#endregion
+//#region src/projection/projection-shard-manager.d.ts
+/**
+ * Factory that builds one projection-worker transport. Mirrors
+ * `WorkerFactory` from the executor pool: lets tests inject fake
+ * transports without spawning real worker threads.
+ */
+type ProjectionWorkerFactory = (shardIndex: number, shardId: string) => IProjectionTransport;
+type ProjectionShardManagerConfig = {
+  shardCount: number;
+  db: DbConfig;
+  models: ModelManifestEntry[];
+  preReadyKinds: BuiltInReadModelKind[];
+  postReadyKinds: BuiltInReadModelKind[];
+  factory: ProjectionWorkerFactory;
+  logger: ILogger;
+  hostBus: IEventBus;
+  initTimeoutMs?: number;
+  shutdownGraceMs?: number;
+  drainTimeoutMs?: number;
+  chainDepthReportIntervalMs?: number;
+  /**
+   * Host-side forwarding instrumentations indexed by shard index. The
+   * manager routes each shard's `pool-acquire-samples` message to the
+   * matching forwarder so the host's OpenTelemetry instrumentation records
+   * acquire-wait latencies as if each shard's pg.Pool were local.
+   */
+  poolInstrumentations?: ForwardingPoolInstrumentation[];
+};
+//#endregion
 //#region src/signer/types.d.ts
 /**
  * Configuration for signing and verification.
@@ -3249,6 +4073,36 @@ interface ReadModelFactoryDeps {
  * dependencies once they are available. Awaited during `buildModule()`.
  */
 type ReadModelFactory = (deps: ReadModelFactoryDeps) => IReadModel | Promise<IReadModel>;
+/**
+ * Describes a document-model package the worker should import at runtime.
+ * Either a bare-specifier package or an absolute file path.
+ */
+type DocumentModelSpecInput = {
+  packageName: string;
+  version: string;
+} | {
+  filePath: string;
+};
+/**
+ * Caller-facing config for {@link ReactorBuilder.withProjectionShards}.
+ * When set, the builder replaces the in-process
+ * {@link ReadModelCoordinator} with a {@link ProjectionShardManager} that
+ * fans JOB_WRITE_READY events to N projection workers sharded by
+ * documentId.
+ *
+ * @see Sharded projection workers sub-feature brief
+ *   (Powerhouse board wiki id: eb26f01f-8f68-4918-a6f6-ac7a4679b533)
+ */
+type ProjectionShardBuilderConfig = {
+  shardCount: number;
+  preReadyKinds: BuiltInReadModelKind[];
+  postReadyKinds: BuiltInReadModelKind[];
+  poolSize?: number;
+  initTimeoutMs?: number;
+  shutdownGraceMs?: number;
+  drainTimeoutMs?: number;
+  chainDepthReportIntervalMs?: number;
+};
 declare class ReactorBuilder {
   private logger?;
   private documentModels;
@@ -3272,6 +4126,15 @@ declare class ReactorBuilder {
   private documentModelLoader?;
   private shutdownHooks;
   private driveContainerTypes;
+  private documentModelSpecs;
+  private workerPoolConfig?;
+  private resolvedModelManifest?;
+  private workerDbConfig?;
+  private workerSignatureVerifierSpec?;
+  private workerFactory?;
+  private projectionShardConfig?;
+  private projectionWorkerFactory?;
+  private instrumentedPools;
   withLogger(logger: ILogger): this;
   withDocumentModels(models: DocumentModelModule<any>[]): this;
   withUpgradeManifests(manifests: UpgradeManifest<readonly number[]>[]): this;
@@ -3295,6 +4158,14 @@ declare class ReactorBuilder {
   withEventBus(eventBus: IEventBus): this;
   withSignatureVerifier(verifier: SignatureVerificationHandler): this;
   withKysely(kysely: Kysely<Database>): this;
+  /**
+   * Register an externally-constructed pg.Pool's {@link PoolInstrumentation}
+   * so it surfaces through {@link ReactorModule.pools}. Use this when the
+   * caller built the pool itself (e.g. the in-process bench host wiring) so
+   * pool acquire-wait and pool-stat metrics still emit. The builder also
+   * registers any pool it constructs internally via {@link createPostgresDatabase}.
+   */
+  withInstrumentedPool(instrumentation: PoolInstrumentation): this;
   withQueue(queue: IQueue): this;
   withChannelScheme(scheme: ChannelScheme): this;
   withJwtHandler(handler: JwtHandler): this;
@@ -3309,8 +4180,79 @@ declare class ReactorBuilder {
    * shutdown chain.
    */
   withShutdownHook(hook: () => Promise<void>): this;
+  withDocumentModelSpecs(specs: DocumentModelSpecInput[]): this;
+  /**
+   * Stores the worker-pool configuration. When `config.enabled === true` the
+   * builder constructs a {@link WorkerPoolJobExecutorManager} in place of the
+   * in-process {@link SimpleJobExecutorManager}.
+   */
+  withWorkerPool(config: WorkerPoolConfig): this;
+  /**
+   * Postgres connection info forwarded to each worker so it can open its own
+   * pool. Required when `workerPool.enabled === true` unless a custom
+   * `withWorkerFactory` or `withExecutor` is provided.
+   */
+  withWorkerDbConfig(db: DbConfig): this;
+  /**
+   * Factory spec the worker imports to instantiate its signature verifier.
+   * Required when `workerPool.enabled === true` unless a custom
+   * `withWorkerFactory` or `withExecutor` is provided.
+   */
+  withWorkerSignatureVerifierSpec(spec: SignatureVerifierSpec): this;
+  /**
+   * Inject a custom {@link WorkerFactory}. When set, the builder skips
+   * default thread-transport wiring and hands the factory directly to the
+   * pool manager. Use this in tests or to plug in a different transport
+   * (e.g. a child-process adapter).
+   */
+  withWorkerFactory(factory: WorkerFactory): this;
+  /**
+   * Configure N sharded projection workers. When set, the builder replaces
+   * the default in-process {@link ReadModelCoordinator} with a
+   * {@link ProjectionShardManager}. The same `DbConfig` registered via
+   * {@link withWorkerDbConfig} is reused for the projection workers'
+   * connection info; only the `poolSize` is overridden by
+   * {@link ProjectionShardBuilderConfig.poolSize}.
+   *
+   * Requires {@link withWorkerDbConfig} (the projection workers need
+   * connection info to open their own pools). The same model manifest
+   * resolved from {@link withDocumentModelSpecs} is forwarded.
+   */
+  withProjectionShards(config: ProjectionShardBuilderConfig): this;
+  /**
+   * Inject a custom {@link ProjectionWorkerFactory}. When set, the builder
+   * skips default thread-transport wiring for the projection shards and
+   * hands the factory directly to {@link ProjectionShardManager}.
+   */
+  withProjectionWorkerFactory(factory: ProjectionWorkerFactory): this;
+  getResolvedModelManifest(): ModelManifestEntry[] | undefined;
   build(): Promise<IReactor>;
   buildModule(): Promise<ReactorModule>;
+  /**
+   * Constructs a {@link ProjectionShardManager} bound to the host event
+   * bus. Builds the default thread-transport factory unless one was
+   * injected via {@link withProjectionWorkerFactory}. Calls
+   * `manager.startup()` so all N workers reach READY before the reactor
+   * is returned to the caller.
+   */
+  private createProjectionShardManager;
+  private createDefaultProjectionWorkerFactory;
+  /**
+   * Default {@link WorkerFactory} used when `workerPool.enabled` is set and
+   * the caller did not inject `withWorkerFactory`. Each worker spawns a real
+   * `node:worker_threads` Worker pointing at the compiled `worker/entry.js`.
+   */
+  private createDefaultWorkerFactory;
+  /**
+   * Builds the parent Kysely instance against a real Postgres server using
+   * the same {@link DbConfig} the workers receive at init. Used in the
+   * worker-pool path so the parent reactor and each worker thread share
+   * storage; PGlite cannot be shared across threads. The constructed pool
+   * is wrapped with {@link instrumentPgPool} and the resulting
+   * {@link PoolInstrumentation} is pushed onto {@link instrumentedPools} so
+   * the reactor module exposes acquire-wait and pool-stat surfaces.
+   */
+  private createPostgresDatabase;
   private attachSignalHandlers;
 }
 //#endregion
@@ -3505,35 +4447,6 @@ declare class EventBus implements IEventBus {
   emit(type: number, data: any): Promise<void>;
 }
 //#endregion
-//#region src/registry/document-model-resolver.d.ts
-interface IDocumentModelResolver {
-  ensureModelLoaded(documentType: string): Promise<void>;
-}
-/**
- * Encapsulates the logic for resolving document model modules on demand.
- * Shared between the queue (CREATE_DOCUMENT gate) and the executor manager
- * (post-failure recovery) so that both paths use the same deduplication
- * and failure-caching state.
- */
-declare class DocumentModelResolver implements IDocumentModelResolver {
-  private registry;
-  private loader;
-  private loadingModels;
-  private failedModelTypes;
-  constructor(registry: IDocumentModelRegistry, loader: IDocumentModelLoader);
-  ensureModelLoaded(documentType: string): Promise<void>;
-}
-/**
- * No-op resolver used when no document model loader is configured.
- * Checks the registry for the model and returns if found; throws if not.
- * Since there is no loader, missing models cannot be recovered.
- */
-declare class NullDocumentModelResolver implements IDocumentModelResolver {
-  private registry?;
-  constructor(registry?: IDocumentModelRegistry | undefined);
-  ensureModelLoaded(documentType: string): Promise<void>;
-}
-//#endregion
 //#region src/queue/queue.d.ts
 /**
  * In-memory implementation of the IQueue interface.
@@ -3593,6 +4506,7 @@ declare class InMemoryQueue implements IQueue {
   enqueue(job: Job): Promise<void>;
   dequeue(documentId: string, scope: string, branch: string, signal?: AbortSignal): Promise<IJobExecutionHandle | null>;
   dequeueNext(signal?: AbortSignal): Promise<IJobExecutionHandle | null>;
+  dequeueNextMatching(predicate: (meta: JobRoutingMeta) => boolean, signal?: AbortSignal): Promise<IJobExecutionHandle | null>;
   size(documentId: string, scope: string, branch: string): Promise<number>;
   totalSize(): Promise<number>;
   remove(jobId: string): Promise<boolean>;
@@ -3600,9 +4514,9 @@ declare class InMemoryQueue implements IQueue {
   clearAll(): Promise<void>;
   hasJobs(): Promise<boolean>;
   completeJob(jobId: string): Promise<void>;
-  failJob(jobId: string, error?: ErrorInfo): Promise<void>;
+  failJob(jobId: string, error?: ErrorInfo$1): Promise<void>;
   deferJob(jobId: string): void;
-  retryJob(jobId: string, error?: ErrorInfo): Promise<void>;
+  retryJob(jobId: string, error?: ErrorInfo$1): Promise<void>;
   /**
    * Check if the queue is drained and call the callback if it is
    */
@@ -3664,7 +4578,7 @@ declare class InMemoryJobTracker implements IJobTracker {
   shutdown(): void;
   registerJob(jobInfo: JobInfo): void;
   markRunning(jobId: string): void;
-  markFailed(jobId: string, error: ErrorInfo, job?: Job): void;
+  markFailed(jobId: string, error: ErrorInfo$1, job?: Job): void;
   getJobStatus(jobId: string): JobInfo | null;
 }
 //#endregion
@@ -3687,6 +4601,7 @@ declare class SimpleJobExecutorManager implements IJobExecutorManager {
   private totalJobsProcessed;
   private unsubscribe?;
   private deferredJobs;
+  private resultHandler;
   private jobTimeoutMs;
   constructor(executorFactory: JobExecutorFactory, eventBus: IEventBus, queue: IQueue, jobTracker: IJobTracker, logger: ILogger, resolver: IDocumentModelResolver, jobTimeoutMs?: number);
   start(numExecutors: number): Promise<void>;
@@ -3696,16 +4611,7 @@ declare class SimpleJobExecutorManager implements IJobExecutorManager {
   private processNextJob;
   private checkForMoreJobs;
   private processExistingJobs;
-  private toErrorInfo;
-  private hasCreateDocumentAction;
   private flushDeferredJobs;
-  private formatErrorHistory;
-}
-//#endregion
-//#region src/cache/collection-membership-cache.d.ts
-interface ICollectionMembershipCache {
-  getCollectionsForDocuments(documentIds: string[]): Promise<Record<string, string[]>>;
-  invalidate(documentId: string): void;
 }
 //#endregion
 //#region src/cache/document-meta-cache-types.d.ts
@@ -3993,8 +4899,10 @@ declare class KyselyOperationStore implements IOperationStore {
   constructor(db: Kysely<Database$1>);
   private get queryExecutor();
   withTransaction(trx: Transaction<Database$1>): KyselyOperationStore;
-  apply(documentId: string, documentType: string, scope: string, branch: string, revision: number, fn: (txn: AtomicTxn) => void | Promise<void>, signal?: AbortSignal): Promise<void>;
+  apply(documentId: string, documentType: string, scope: string, branch: string, revision: number, fn: (txn: AtomicTxn) => void | Promise<void>, signal?: AbortSignal): Promise<Operation[]>;
+  private resolveUniqueConstraint;
   private executeApply;
+  private findIdempotentReplay;
   getSince(documentId: string, scope: string, branch: string, revision: number, filter?: OperationFilter, paging?: PagingOptions, signal?: AbortSignal): Promise<PagedResults<Operation>>;
   getSinceId(id: number, paging?: PagingOptions, signal?: AbortSignal): Promise<PagedResults<OperationWithContext$1>>;
   getConflicting(documentId: string, scope: string, branch: string, minTimestamp: string, paging?: PagingOptions, signal?: AbortSignal): Promise<PagedResults<Operation>>;
@@ -4067,6 +4975,17 @@ declare class SimpleJobExecutor implements IJobExecutor {
   private accumulateResultOrReturnError;
 }
 //#endregion
+//#region src/executor/worker/forwarding-logger.d.ts
+declare function createForwardingLogger(post: (msg: LogMessage) => void, level?: ILogger["level"], tags?: string[]): ILogger;
+//#endregion
+//#region src/executor/worker/sanitize.d.ts
+declare function errorToInfo(err: unknown): ErrorInfo;
+declare function sanitizeArg(value: unknown, depth?: number, seen?: WeakSet<object>): SanitizedArg;
+//#endregion
+//#region src/executor/worker/index.d.ts
+/** Absolute path to the worker entry script for use with `new Worker(workerEntryPath)`. */
+declare const workerEntryPath: string;
+//#endregion
 //#region src/registry/errors.d.ts
 /**
  * Error thrown when a document model module is not found in the registry.
@@ -4199,16 +5118,10 @@ declare class KyselyDocumentIndexer extends BaseReadModel implements IDocumentIn
 //#region src/read-models/coordinator.d.ts
 /**
  * Coordinates read model synchronization by listening to operation write events
- * and updating all registered read models in parallel.
- *
- * This coordinator is responsible for:
- * - Subscribing to OPERATION_WRITTEN events from the event bus
- * - Distributing operation updates to all registered read models
- * - Managing the lifecycle of read model subscriptions
- *
- * Read models are updated asynchronously and in parallel to avoid blocking
- * the write path. Errors in read model updates are propagated through the
- * event bus but do not affect the write operation success.
+ * and updating all registered read models on per-`documentId:scope:branch`
+ * serial chains. Cross-key projection runs in parallel; same-key projection is
+ * serialized so the executor can return to dispatch without holding ordering
+ * implicitly.
  */
 declare class ReadModelCoordinator implements IReadModelCoordinator {
   private eventBus;
@@ -4216,23 +5129,26 @@ declare class ReadModelCoordinator implements IReadModelCoordinator {
   readonly postReady: IReadModel[];
   private unsubscribe?;
   private isRunning;
+  private readonly chains;
+  private readonly logger;
   readonly readModels: IReadModel[];
   constructor(eventBus: IEventBus, preReady: IReadModel[], postReady: IReadModel[]);
-  /**
-   * Start listening for operation events and updating read models.
-   * Can be called multiple times safely (subsequent calls are no-ops).
-   */
   start(): void;
-  /**
-   * Stop listening and clean up subscriptions.
-   * Can be called multiple times safely (subsequent calls are no-ops).
-   */
   stop(): void;
   /**
-   * Handle write ready events by updating all read models in parallel.
-   * Errors from individual read models are collected and re-thrown as an aggregate.
+   * Resolves when every per-queueKey projection chain has flushed. Intended
+   * for test fixtures and explicit shutdown; production callers use
+   * consistency tokens instead.
    */
+  drain(): Promise<void>;
+  getChainDepth(): number;
   private handleWriteReady;
+  private emitEmptyReadReady;
+  private runChain;
+  private indexWithTiming;
+  private emitReadModelIndexed;
+  private emitBatchCompleted;
+  private queueKeyFor;
 }
 //#endregion
 //#region src/read-models/document-view.d.ts
@@ -4663,5 +5579,5 @@ declare class ProcessorManager extends BaseReadModel implements IProcessorManage
   private deleteProcessorCursors;
 }
 //#endregion
-export { type AtomicTxn, type AttachmentHash, type AttachmentRef, BaseReadModel, type BatchExecutionRequest, type BatchExecutionResult, type BatchLoadRequest, type BatchLoadResult, type CachedSnapshot, type ChannelConfig, ChannelError, ChannelErrorSource, type ChannelHealth, type ChannelMeta, ChannelScheme, type ConnectionState, type ConnectionStateChangeCallback, type ConnectionStateChangedEvent, type ConnectionStateSnapshot, type ConsistencyCoordinate, type ConsistencyKey, type ConsistencyToken, ConsistencyTracker, DEFAULT_DRIVE_CONTAINER_TYPES, type Database, type DeadLetterAddedEvent, DefaultSubscriptionErrorHandler, type DocumentChangeEvent, DocumentChangeType, type DocumentGraphEdge, type DocumentIndexerDatabase, DocumentIntegrityService, DocumentModelRegistry, DocumentModelResolver, type DocumentRelationship, type DocumentRevisions, type DocumentStreamKey, type DocumentViewDatabase, DriveClient, DuplicateManifestError, DuplicateModuleError, DuplicateOperationError, EventBus, EventBusAggregateError, type ExecutionJobPlan, type ExecutorStartedEvent, type ExecutorStoppedEvent, type GqlChannelConfig, GqlRequestChannel, GqlRequestChannelFactory, GqlResponseChannel, GqlResponseChannelFactory, type IChannel, type IChannelFactory, type IConsistencyTracker, type IDocumentGraph, type IDocumentIndexer, type IDocumentIntegrityService, type IDocumentModelLoader, type IDocumentModelRegistry, type IDocumentModelResolver, type IDocumentView, type IDriveClient, type IEventBus, type IJobAwaiter, type IJobExecutor, type IJobExecutorManager, type IJobTracker, type IKeyframeStore, type IOperationIndex, type IOperationStore, type IPollTimer, type IProcessor, type IProcessorHostModule, type IProcessorManager, type IQueue, type IReactor, type IReactorClient, type IReactorSubscriptionManager, type IReadModel, type IReadModelCoordinator, type IRelationalDb, type ISubscriptionErrorHandler, type ISyncCursorStorage, type ISyncManager, type ISyncRemoteStorage, type ISyncStatusTracker, type IWriteCache, SimpleJobExecutor as InMemoryJobExecutor, SimpleJobExecutor, InMemoryJobTracker, InMemoryQueue, type InsertableDocumentSnapshot, IntervalPollTimer, InvalidModuleError, type Job, type JobAvailableEvent, JobAwaiter, type JobCompletedEvent, type JobExecutorConfig, JobExecutorEventTypes, type JobExecutorFactory, type JobFailedEvent, type JobInfo, type JobPendingEvent, type JobReadReadyEvent, type JobResult, type JobRunningEvent, type JobStartedEvent, JobStatus, type JobWriteReadyEvent, type JwtHandler, type KeyframeSnapshot, type KeyframeValidationIssue, KyselyDocumentIndexer, KyselyDocumentView, KyselyKeyframeStore, KyselyOperationStore, KyselySyncCursorStorage, KyselySyncRemoteStorage, KyselyWriteCache, type LoadJobPlan, Mailbox, ModuleNotFoundError, NullDocumentModelResolver, type OperationBatch, type OperationContext, type OperationFilter, type OperationIndexEntry, type OperationTable, type OperationWithContext, OptimisticLockError, type PagedResults, type PagingOptions, type ParsedDriveUrl, type ParsedPaging, PollBehavior, PollingChannelError, type ProcessorApp, type ProcessorFactory, type ProcessorFactoryBuilder, type ProcessorFilter, ProcessorManager, type ProcessorRecord, type ProcessorStatus, PropagationMode, QueueEventTypes, REACTOR_SCHEMA, Reactor, ReactorBuilder, ReactorClient, ReactorClientBuilder, type ReactorClientModule, ReactorEventTypes, type ReactorFeatures, type JobFailedEvent$1 as ReactorJobFailedEvent, type ReactorModule, ReactorSubscriptionManager, ReadModelCoordinator, type ReadModelFactory, type ReadModelFactoryDeps, type RebuildResult, RelationalDbProcessor, RelationshipChangeType, type Remote, type RemoteCursor, type RemoteFilter, type RemoteOptions, type RemoteRecord, type RemoteStatus, RevisionMismatchError, type SearchFilter, type ShutdownStatus, type SignatureVerificationHandler, type SignerConfig, SimpleJobExecutorManager, type SnapshotValidationIssue, type Database$1 as StorageDatabase, type SubscriptionErrorContext, SyncBuilder, type SyncEnvelope, type SyncEnvelopeType, SyncEventTypes, type SyncFailedEvent, type SyncModule, SyncOperation, SyncOperationAggregateError, type SyncOperationErrorType, SyncOperationStatus, type SyncPendingEvent, SyncStatus, type SyncStatusChangeCallback, SyncStatusTracker, type SyncSucceededEvent, type TrackedProcessor, type Unsubscribe, type ValidationResult, type ViewFilter, type WriteCacheConfig, addRelationshipAction, batchOperationsByDocument, consolidateSyncOperations, createDocumentAction, createMutableShutdownStatus, createRelationalDb, deleteDocumentAction, documentActions, driveCollectionId, driveIdFromUrl, envelopesToSyncOperations, getMigrationStatus, makeConsistencyKey, parseDriveUrl, parsePagingOptions, removeRelationshipAction, runMigrations, trimMailboxFromAckOrdinal, updateRelationshipAction, upgradeDocumentAction };
+export { type AbortMessage, type AtomicTxn, type AttachmentHash, type AttachmentRef, BaseReadModel, type BatchExecutionRequest, type BatchExecutionResult, type BatchLoadRequest, type BatchLoadResult, type BuiltInReadModelKind, type CachedSnapshot, type ChannelConfig, ChannelError, ChannelErrorSource, type ChannelHealth, type ChannelMeta, ChannelScheme, type ConnectionState, type ConnectionStateChangeCallback, type ConnectionStateChangedEvent, type ConnectionStateSnapshot, type ConsistencyCoordinate, type ConsistencyKey, type ConsistencyToken, ConsistencyTracker, DEFAULT_DRIVE_CONTAINER_TYPES, type Database, type DbConfig, type DeadLetterAddedEvent, DefaultSubscriptionErrorHandler, type DocumentChangeEvent, DocumentChangeType, type DocumentGraphEdge, type DocumentIndexerDatabase, DocumentIntegrityService, DocumentModelRegistry, DocumentModelResolver, type DocumentModelSpec, type DocumentModelSpecInput, type DocumentRelationship, type DocumentRevisions, type DocumentStreamKey, type DocumentViewDatabase, DriveClient, DuplicateManifestError, DuplicateModuleError, DuplicateOperationError, EventBus, EventBusAggregateError, type ExecuteMessage, type ExecutionJobPlan, type ExecutorStartedEvent, type ExecutorStoppedEvent, type FactorySpec, type GqlChannelConfig, GqlRequestChannel, GqlRequestChannelFactory, GqlResponseChannel, GqlResponseChannelFactory, type HeartbeatMessage, type IChannel, type IChannelFactory, type IConsistencyTracker, type IDocumentGraph, type IDocumentIndexer, type IDocumentIntegrityService, type IDocumentModelLoader, type IDocumentModelRegistry, type IDocumentModelResolver, type IDocumentView, type IDriveClient, type IEventBus, type IJobAwaiter, type IJobExecutor, type IJobExecutorManager, type IJobTracker, type IKeyframeStore, type IOperationIndex, type IOperationStore, type IPollTimer, type IProcessor, type IProcessorHostModule, type IProcessorManager, type IProjectionTransport, type IQueue, type IReactor, type IReactorClient, type IReactorSubscriptionManager, type IReadModel, type IReadModelCoordinator, type IRelationalDb, type ISubscriptionErrorHandler, type ISyncCursorStorage, type ISyncManager, type ISyncRemoteStorage, type ISyncStatusTracker, type IWriteCache, SimpleJobExecutor as InMemoryJobExecutor, SimpleJobExecutor, InMemoryJobTracker, InMemoryQueue, type InitMessage, type InsertableDocumentSnapshot, IntervalPollTimer, InvalidModuleError, type Job, type JobAvailableEvent, JobAwaiter, type JobCompletedEvent, type JobExecutorConfig, JobExecutorEventTypes, type JobExecutorFactory, type JobFailedEvent, type JobInfo, type JobPendingEvent, type JobReadReadyEvent, type JobResult, type JobRunningEvent, type JobStartedEvent, JobStatus, type JobWriteReadyEvent, type JobWriteReadyPayload, type JwtHandler, type KeyframeSnapshot, type KeyframeValidationIssue, KyselyDocumentIndexer, KyselyDocumentView, KyselyKeyframeStore, KyselyOperationStore, KyselySyncCursorStorage, KyselySyncRemoteStorage, KyselyWriteCache, type LoadJobPlan, type LoadModelMessage, type LogMessage, Mailbox, type MetricsMessage, type ModelLoadFailedMessage, type ModelLoadedMessage, type ModelManifestEntry, ModuleNotFoundError, type ModuleRef, NullDocumentModelResolver, type OperationBatch, type OperationContext, type OperationFilter, type OperationIndexEntry, type OperationTable, type OperationWithContext, OptimisticLockError, type PagedResults, type PagingOptions, type ParentMessage, type ParsedDriveUrl, type ParsedPaging, PollBehavior, PollingChannelError, type PoolInstrumentation, type PoolStats, type ProcessorApp, type ProcessorFactory, type ProcessorFactoryBuilder, type ProcessorFilter, ProcessorManager, type ProcessorRecord, type ProcessorStatus, type ProjectionShardBuilderConfig, type ProjectionShardManagerConfig, type ProjectionWorkerFactory, PropagationMode, QueueEventTypes, REACTOR_SCHEMA, Reactor, ReactorBuilder, ReactorClient, ReactorClientBuilder, type ReactorClientModule, ReactorEventTypes, type ReactorFeatures, type JobFailedEvent$1 as ReactorJobFailedEvent, type ReactorModule, ReactorSubscriptionManager, type ReadModelBatchCompletedEvent, ReadModelCoordinator, type ReadModelFactory, type ReadModelFactoryDeps, type ReadModelIndexedEvent, type ReadModelIndexingStage, type ReadModelStage, type ReadyMessage, type RebuildResult, RelationalDbProcessor, RelationshipChangeType, type Remote, type RemoteCursor, type RemoteFilter, type RemoteOptions, type RemoteRecord, type RemoteStatus, type ResultMessage, RevisionMismatchError, type SanitizedArg, type SearchFilter, type ShutdownMessage, type ShutdownStatus, type SignatureVerificationHandler, type SignatureVerifierSpec, type SignerConfig, SimpleJobExecutorManager, type SnapshotValidationIssue, type Database$1 as StorageDatabase, type SubscriptionErrorContext, SyncBuilder, type SyncEnvelope, type SyncEnvelopeType, SyncEventTypes, type SyncFailedEvent, type SyncModule, SyncOperation, SyncOperationAggregateError, type SyncOperationErrorType, SyncOperationStatus, type SyncPendingEvent, SyncStatus, type SyncStatusChangeCallback, SyncStatusTracker, type SyncSucceededEvent, type TrackedProcessor, type Unsubscribe, type ValidationResult, type ViewFilter, type ErrorInfo as WorkerErrorInfo, type WorkerMessage, type WorkerPoolConfig, type WriteCacheConfig, addRelationshipAction, batchOperationsByDocument, consolidateSyncOperations, createDocumentAction, createForwardingLogger, createMutableShutdownStatus, createRelationalDb, deleteDocumentAction, documentActions, driveCollectionId, driveIdFromUrl, envelopesToSyncOperations, errorToInfo, getMigrationStatus, instrumentPgPool, makeConsistencyKey, parseDriveUrl, parsePagingOptions, removeRelationshipAction, runMigrations, sanitizeArg, trimMailboxFromAckOrdinal, updateRelationshipAction, upgradeDocumentAction, workerEntryPath };
 //# sourceMappingURL=index.d.ts.map