@powerhousedao/reactor 6.2.2-dev.23 → 6.2.2-dev.24

package/dist/entry.js

@@ -1,6 +1,6 @@
-import { o as instrumentPgPool } from "./drive-container-types-DrQMmpCa.js";
+import { o as instrumentPgPool } from "./drive-container-types-uigTGO3i.js";
 import { n as errorToInfo, t as createForwardingLogger } from "./forwarding-logger-BBkMSxuJ.js";
-import { n as defaultLoadFactory, t as buildWorkerExecutor } from "./build-worker-executor-CE-Yyezb.js";
+import { n as defaultLoadFactory, t as buildWorkerExecutor } from "./build-worker-executor-BTWIynvM.js";
 import { ConsoleLogger } from "document-model";
 import { isMainThread, parentPort } from "node:worker_threads";
 //#region src/executor/worker/run-worker.ts
@@ -120,6 +120,7 @@ function runWorker(parentPort, overrides = {}) {
 			init: msg,
 			database: database.kysely,
 			logger: new ConsoleLogger([`reactor-worker:${msg.workerId}`]),
+			executorConfig: msg.executorConfig,
 			loadFactory: activeLoadFactory
 		});
 		if (database.poolInstrumentation) startPoolReporter(database.poolInstrumentation);

package/dist/entry.js.map

@@ -1 +1 @@
-{"version":3,"file":"entry.js","names":[],"sources":["../src/executor/worker/run-worker.ts","../src/executor/worker/entry.ts"],"sourcesContent":["import type { DocumentModelModule } from \"@powerhousedao/shared/document-model\";\nimport { ConsoleLogger } from \"document-model\";\nimport type { Kysely } from \"kysely\";\nimport type { MessagePort } from \"node:worker_threads\";\nimport type { Database } from \"../../core/types.js\";\nimport type { Job } from \"../../queue/types.js\";\nimport {\n  instrumentPgPool,\n  type PoolInstrumentation,\n} from \"../../storage/pool-instrumentation.js\";\nimport {\n  buildWorkerExecutor,\n  defaultLoadFactory,\n  type BuildWorkerExecutorOptions,\n  type WorkerExecutorStack,\n} from \"./build-worker-executor.js\";\nimport { createForwardingLogger } from \"./forwarding-logger.js\";\nimport type {\n  DbConfig,\n  FactorySpec,\n  InitMessage,\n  LoadModelMessage,\n  ParentMessage,\n  WorkerMessage,\n} from \"./protocol.js\";\nimport { errorToInfo } from \"./sanitize.js\";\n\nconst POOL_SAMPLE_INTERVAL_MS = 1_000;\n\n/**\n * Closeable handle around the parent's Postgres pool the worker owns.\n * Decoupled so tests can substitute a PGlite-backed Kysely.\n *\n * When the worker owns a real pg.Pool, the handle exposes a\n * {@link PoolInstrumentation} so the run-loop can subscribe to acquire-wait\n * samples and forward them to the host. Tests that swap in PGlite leave\n * this undefined; pool metrics simply do not emit in that path.\n */\nexport type WorkerDatabaseHandle = {\n  kysely: Kysely<Database>;\n  poolInstrumentation?: PoolInstrumentation;\n  shutdown(): Promise<void>;\n};\n\nexport type RunWorkerOverrides = {\n  /**\n   * Builds the worker's Kysely instance from the init's DbConfig. Defaults\n   * to a real Postgres pool. Tests typically swap this for PGlite.\n   */\n  createDatabase?: (\n    config: DbConfig,\n    workerId: string,\n  ) => Promise<WorkerDatabaseHandle>;\n  /**\n   * Overrides the dynamic-import factory loader used for the signature\n   * verifier and document model manifest. Tests usually inject this so\n   * they don't need real packages.\n   */\n  loadFactory?: BuildWorkerExecutorOptions[\"loadFactory\"];\n  /**\n   * Called after the database is created but before the executor stack\n   * is built. Lets tests run reactor migrations against PGlite, since\n   * the production parent runs them once against shared Postgres.\n   */\n  beforeBuildExecutor?: (db: Kysely<Database>) => Promise<void>;\n};\n\nasync function defaultCreateDatabase(\n  config: DbConfig,\n  workerId: string,\n): Promise<WorkerDatabaseHandle> {\n  const { Kysely, PostgresDialect } = await import(\"kysely\");\n  const pgModule = await import(\"pg\");\n  const Pool = pgModule.default.Pool;\n  const pool = new Pool({\n    host: config.host,\n    port: config.port,\n    database: config.database,\n    user: config.user,\n    password: config.password,\n    ssl: config.ssl ? { rejectUnauthorized: false } : undefined,\n    application_name: config.applicationName ?? workerId,\n    max: config.poolSize,\n    connectionTimeoutMillis: config.connectionTimeoutMillis,\n    idleTimeoutMillis: config.idleTimeoutMillis,\n  });\n  const poolInstrumentation = instrumentPgPool(pool, workerId);\n  const kysely = new Kysely<Database>({\n    dialect: new PostgresDialect({ pool }),\n  });\n  return {\n    kysely,\n    poolInstrumentation,\n    async shutdown(): Promise<void> {\n      try {\n        await kysely.destroy();\n      } catch {\n        // best-effort\n      }\n      try {\n        await pool.end();\n      } catch {\n        // best-effort\n      }\n    },\n  };\n}\n\n/**\n * Drives the worker's message loop. Owns lifecycle of the database handle\n * and executor stack. The default factories build a real Postgres pool and\n * use dynamic `import()` for model/verifier specs; tests inject overrides\n * for an in-process PGlite path.\n */\nexport function runWorker(\n  parentPort: MessagePort,\n  overrides: RunWorkerOverrides = {},\n): void {\n  let workerId = \"\";\n  let initCompleted = false;\n  let initConfig: InitMessage | null = null;\n  let executorStack: WorkerExecutorStack | null = null;\n  let database: WorkerDatabaseHandle | null = null;\n  let poolSampleTimer: NodeJS.Timeout | null = null;\n  let pendingPoolSamples: number[] = [];\n  let detachPoolListener: (() => void) | null = null;\n  const activeLoadFactory: NonNullable<\n    BuildWorkerExecutorOptions[\"loadFactory\"]\n  > = overrides.loadFactory ?? defaultLoadFactory;\n\n  function post(msg: WorkerMessage): void {\n    parentPort.postMessage(msg);\n  }\n\n  const logger = createForwardingLogger(post);\n\n  function startPoolReporter(instrumentation: PoolInstrumentation): void {\n    detachPoolListener = instrumentation.onAcquire((durationMs) => {\n      pendingPoolSamples.push(durationMs);\n    });\n    poolSampleTimer = setInterval(() => {\n      if (pendingPoolSamples.length === 0) {\n        return;\n      }\n      const durations = pendingPoolSamples;\n      pendingPoolSamples = [];\n      const stats = instrumentation.getStats();\n      post({\n        type: \"pool-acquire-samples\",\n        workerId,\n        poolName: instrumentation.name,\n        timestamp: Date.now(),\n        durations,\n        size: stats.size,\n        idle: stats.idle,\n        waiting: stats.waiting,\n      });\n    }, POOL_SAMPLE_INTERVAL_MS);\n    poolSampleTimer.unref();\n  }\n\n  function stopPoolReporter(): void {\n    if (detachPoolListener) {\n      detachPoolListener();\n      detachPoolListener = null;\n    }\n    if (poolSampleTimer) {\n      clearInterval(poolSampleTimer);\n      poolSampleTimer = null;\n    }\n    pendingPoolSamples = [];\n  }\n\n  process.on(\"uncaughtException\", (err: unknown) => {\n    try {\n      post({\n        type: \"log\",\n        level: \"error\",\n        message: \"worker uncaughtException\",\n        args: [errorToInfo(err)],\n        timestamp: Date.now(),\n      });\n    } catch {\n      // nothing left to do\n    }\n    throw err;\n  });\n\n  process.on(\"unhandledRejection\", (reason: unknown) => {\n    try {\n      post({\n        type: \"log\",\n        level: \"error\",\n        message: \"worker unhandledRejection\",\n        args: [errorToInfo(reason)],\n        timestamp: Date.now(),\n      });\n    } catch {\n      // nothing left to do\n    }\n  });\n\n  async function handleInit(msg: InitMessage): Promise<void> {\n    workerId = msg.workerId;\n    initConfig = msg;\n    const createDb = overrides.createDatabase ?? defaultCreateDatabase;\n    database = await createDb(msg.db, msg.workerId);\n    if (overrides.beforeBuildExecutor) {\n      await overrides.beforeBuildExecutor(database.kysely);\n    }\n    executorStack = await buildWorkerExecutor({\n      init: msg,\n      database: database.kysely,\n      logger: new ConsoleLogger([`reactor-worker:${msg.workerId}`]),\n      loadFactory: activeLoadFactory,\n    });\n    if (database.poolInstrumentation) {\n      startPoolReporter(database.poolInstrumentation);\n    }\n    initCompleted = true;\n    logger.info(\"worker initialized: @workerId\", msg.workerId);\n    post({\n      type: \"ready\",\n      correlationId: msg.correlationId,\n      workerId: msg.workerId,\n    });\n  }\n\n  async function handleExecute(correlationId: string, job: Job): Promise<void> {\n    if (!executorStack) {\n      post({\n        type: \"result\",\n        correlationId,\n        result: { job, success: false },\n        error: errorToInfo(new Error(\"execute received before init\")),\n      });\n      return;\n    }\n    try {\n      const result = await executorStack.executor.executeJob(job);\n      const writeReady = executorStack.takeLastWriteReady();\n      post({\n        type: \"result\",\n        correlationId,\n        result,\n        writeReady: writeReady ?? undefined,\n      });\n    } catch (error) {\n      post({\n        type: \"result\",\n        correlationId,\n        result: { job, success: false },\n        error: errorToInfo(error),\n      });\n    }\n  }\n\n  async function handleLoadModel(msg: LoadModelMessage): Promise<void> {\n    const stack = executorStack;\n    if (!stack) {\n      post({\n        type: \"model-load-failed\",\n        correlationId: msg.correlationId,\n        documentType: msg.model.documentType,\n        version: msg.model.version,\n        error: errorToInfo(new Error(\"load-model received before init\")),\n      });\n      return;\n    }\n    let module: DocumentModelModule;\n    try {\n      module = (await activeLoadFactory(msg.model.spec)) as DocumentModelModule;\n    } catch (error) {\n      post({\n        type: \"model-load-failed\",\n        correlationId: msg.correlationId,\n        documentType: msg.model.documentType,\n        version: msg.model.version,\n        error: errorToInfo(error),\n      });\n      return;\n    }\n    const [result] = stack.registry.registerModules(module);\n    if (result.status === \"error\") {\n      post({\n        type: \"model-load-failed\",\n        correlationId: msg.correlationId,\n        documentType: msg.model.documentType,\n        version: msg.model.version,\n        error: errorToInfo(result.error),\n      });\n      return;\n    }\n    post({\n      type: \"model-loaded\",\n      correlationId: msg.correlationId,\n      documentType: msg.model.documentType,\n      version: msg.model.version,\n    });\n  }\n\n  async function shutdownDatabase(): Promise<void> {\n    stopPoolReporter();\n    if (database) {\n      await database.shutdown();\n    }\n  }\n\n  function handleParentMessage(msg: ParentMessage): void {\n    switch (msg.type) {\n      case \"init\": {\n        handleInit(msg).catch((err: unknown) => {\n          post({\n            type: \"log\",\n            level: \"error\",\n            message: \"worker init failed\",\n            args: [errorToInfo(err)],\n            timestamp: Date.now(),\n          });\n        });\n        break;\n      }\n\n      case \"execute\": {\n        if (!initCompleted) {\n          logger.warn(\"received execute before init\");\n          post({\n            type: \"result\",\n            correlationId: msg.correlationId,\n            result: { job: msg.job, success: false },\n            error: errorToInfo(new Error(\"execute received before init\")),\n          });\n          break;\n        }\n        handleExecute(msg.correlationId, msg.job).catch((err: unknown) => {\n          post({\n            type: \"result\",\n            correlationId: msg.correlationId,\n            result: { job: msg.job, success: false },\n            error: errorToInfo(err),\n          });\n        });\n        break;\n      }\n\n      case \"shutdown\": {\n        logger.info(\"worker shutting down: @workerId\", workerId);\n        void shutdownDatabase().finally(() => {\n          post({\n            type: \"log\",\n            level: \"info\",\n            message: \"worker shutdown\",\n            args: [],\n            timestamp: Date.now(),\n          });\n          process.exit(0);\n        });\n        break;\n      }\n\n      case \"abort\": {\n        logger.warn(\n          \"abort received (no-op stub): @correlationId\",\n          msg.correlationId,\n        );\n        break;\n      }\n\n      case \"load-model\": {\n        handleLoadModel(msg).catch((err: unknown) => {\n          post({\n            type: \"model-load-failed\",\n            correlationId: msg.correlationId,\n            documentType: msg.model.documentType,\n            version: msg.model.version,\n            error: errorToInfo(err),\n          });\n        });\n        break;\n      }\n\n      default: {\n        const raw = msg as Record<string, unknown>;\n        if (raw[\"type\"] === \"__test_throw\") {\n          const rawReason = raw[\"reason\"];\n          const reason =\n            typeof rawReason === \"string\"\n              ? rawReason\n              : \"synthetic uncaughtException\";\n          setTimeout(() => {\n            throw new Error(reason);\n          }, 0);\n          return;\n        }\n        const _exhaustive: never = msg;\n        void _exhaustive;\n        break;\n      }\n    }\n  }\n\n  parentPort.on(\"message\", handleParentMessage);\n\n  // Test-only exports surfaced on a side-channel for unit tests that drive\n  // the message loop directly without a real worker_threads parent.\n  const harness = {\n    handleParentMessage,\n    get initCompleted(): boolean {\n      return initCompleted;\n    },\n    get initConfig(): InitMessage | null {\n      return initConfig;\n    },\n    get workerId(): string {\n      return workerId;\n    },\n  };\n  (\n    parentPort as unknown as { __reactorWorkerHarness?: unknown }\n  ).__reactorWorkerHarness = harness;\n}\n\nexport type FactorySpecForTesting = FactorySpec;\n","import { isMainThread, parentPort } from \"node:worker_threads\";\nimport { runWorker } from \"./run-worker.js\";\n\nif (isMainThread || parentPort === null) {\n  throw new Error(\"entry.ts must be run as a worker thread\");\n}\n\nrunWorker(parentPort);\n"],"mappings":"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"}
+{"version":3,"file":"entry.js","names":[],"sources":["../src/executor/worker/run-worker.ts","../src/executor/worker/entry.ts"],"sourcesContent":["import type { DocumentModelModule } from \"@powerhousedao/shared/document-model\";\nimport { ConsoleLogger } from \"document-model\";\nimport type { Kysely } from \"kysely\";\nimport type { MessagePort } from \"node:worker_threads\";\nimport type { Database } from \"../../core/types.js\";\nimport type { Job } from \"../../queue/types.js\";\nimport {\n  instrumentPgPool,\n  type PoolInstrumentation,\n} from \"../../storage/pool-instrumentation.js\";\nimport {\n  buildWorkerExecutor,\n  defaultLoadFactory,\n  type BuildWorkerExecutorOptions,\n  type WorkerExecutorStack,\n} from \"./build-worker-executor.js\";\nimport { createForwardingLogger } from \"./forwarding-logger.js\";\nimport type {\n  DbConfig,\n  FactorySpec,\n  InitMessage,\n  LoadModelMessage,\n  ParentMessage,\n  WorkerMessage,\n} from \"./protocol.js\";\nimport { errorToInfo } from \"./sanitize.js\";\n\nconst POOL_SAMPLE_INTERVAL_MS = 1_000;\n\n/**\n * Closeable handle around the parent's Postgres pool the worker owns.\n * Decoupled so tests can substitute a PGlite-backed Kysely.\n *\n * When the worker owns a real pg.Pool, the handle exposes a\n * {@link PoolInstrumentation} so the run-loop can subscribe to acquire-wait\n * samples and forward them to the host. Tests that swap in PGlite leave\n * this undefined; pool metrics simply do not emit in that path.\n */\nexport type WorkerDatabaseHandle = {\n  kysely: Kysely<Database>;\n  poolInstrumentation?: PoolInstrumentation;\n  shutdown(): Promise<void>;\n};\n\nexport type RunWorkerOverrides = {\n  /**\n   * Builds the worker's Kysely instance from the init's DbConfig. Defaults\n   * to a real Postgres pool. Tests typically swap this for PGlite.\n   */\n  createDatabase?: (\n    config: DbConfig,\n    workerId: string,\n  ) => Promise<WorkerDatabaseHandle>;\n  /**\n   * Overrides the dynamic-import factory loader used for the signature\n   * verifier and document model manifest. Tests usually inject this so\n   * they don't need real packages.\n   */\n  loadFactory?: BuildWorkerExecutorOptions[\"loadFactory\"];\n  /**\n   * Called after the database is created but before the executor stack\n   * is built. Lets tests run reactor migrations against PGlite, since\n   * the production parent runs them once against shared Postgres.\n   */\n  beforeBuildExecutor?: (db: Kysely<Database>) => Promise<void>;\n};\n\nasync function defaultCreateDatabase(\n  config: DbConfig,\n  workerId: string,\n): Promise<WorkerDatabaseHandle> {\n  const { Kysely, PostgresDialect } = await import(\"kysely\");\n  const pgModule = await import(\"pg\");\n  const Pool = pgModule.default.Pool;\n  const pool = new Pool({\n    host: config.host,\n    port: config.port,\n    database: config.database,\n    user: config.user,\n    password: config.password,\n    ssl: config.ssl ? { rejectUnauthorized: false } : undefined,\n    application_name: config.applicationName ?? workerId,\n    max: config.poolSize,\n    connectionTimeoutMillis: config.connectionTimeoutMillis,\n    idleTimeoutMillis: config.idleTimeoutMillis,\n  });\n  const poolInstrumentation = instrumentPgPool(pool, workerId);\n  const kysely = new Kysely<Database>({\n    dialect: new PostgresDialect({ pool }),\n  });\n  return {\n    kysely,\n    poolInstrumentation,\n    async shutdown(): Promise<void> {\n      try {\n        await kysely.destroy();\n      } catch {\n        // best-effort\n      }\n      try {\n        await pool.end();\n      } catch {\n        // best-effort\n      }\n    },\n  };\n}\n\n/**\n * Drives the worker's message loop. Owns lifecycle of the database handle\n * and executor stack. The default factories build a real Postgres pool and\n * use dynamic `import()` for model/verifier specs; tests inject overrides\n * for an in-process PGlite path.\n */\nexport function runWorker(\n  parentPort: MessagePort,\n  overrides: RunWorkerOverrides = {},\n): void {\n  let workerId = \"\";\n  let initCompleted = false;\n  let initConfig: InitMessage | null = null;\n  let executorStack: WorkerExecutorStack | null = null;\n  let database: WorkerDatabaseHandle | null = null;\n  let poolSampleTimer: NodeJS.Timeout | null = null;\n  let pendingPoolSamples: number[] = [];\n  let detachPoolListener: (() => void) | null = null;\n  const activeLoadFactory: NonNullable<\n    BuildWorkerExecutorOptions[\"loadFactory\"]\n  > = overrides.loadFactory ?? defaultLoadFactory;\n\n  function post(msg: WorkerMessage): void {\n    parentPort.postMessage(msg);\n  }\n\n  const logger = createForwardingLogger(post);\n\n  function startPoolReporter(instrumentation: PoolInstrumentation): void {\n    detachPoolListener = instrumentation.onAcquire((durationMs) => {\n      pendingPoolSamples.push(durationMs);\n    });\n    poolSampleTimer = setInterval(() => {\n      if (pendingPoolSamples.length === 0) {\n        return;\n      }\n      const durations = pendingPoolSamples;\n      pendingPoolSamples = [];\n      const stats = instrumentation.getStats();\n      post({\n        type: \"pool-acquire-samples\",\n        workerId,\n        poolName: instrumentation.name,\n        timestamp: Date.now(),\n        durations,\n        size: stats.size,\n        idle: stats.idle,\n        waiting: stats.waiting,\n      });\n    }, POOL_SAMPLE_INTERVAL_MS);\n    poolSampleTimer.unref();\n  }\n\n  function stopPoolReporter(): void {\n    if (detachPoolListener) {\n      detachPoolListener();\n      detachPoolListener = null;\n    }\n    if (poolSampleTimer) {\n      clearInterval(poolSampleTimer);\n      poolSampleTimer = null;\n    }\n    pendingPoolSamples = [];\n  }\n\n  process.on(\"uncaughtException\", (err: unknown) => {\n    try {\n      post({\n        type: \"log\",\n        level: \"error\",\n        message: \"worker uncaughtException\",\n        args: [errorToInfo(err)],\n        timestamp: Date.now(),\n      });\n    } catch {\n      // nothing left to do\n    }\n    throw err;\n  });\n\n  process.on(\"unhandledRejection\", (reason: unknown) => {\n    try {\n      post({\n        type: \"log\",\n        level: \"error\",\n        message: \"worker unhandledRejection\",\n        args: [errorToInfo(reason)],\n        timestamp: Date.now(),\n      });\n    } catch {\n      // nothing left to do\n    }\n  });\n\n  async function handleInit(msg: InitMessage): Promise<void> {\n    workerId = msg.workerId;\n    initConfig = msg;\n    const createDb = overrides.createDatabase ?? defaultCreateDatabase;\n    database = await createDb(msg.db, msg.workerId);\n    if (overrides.beforeBuildExecutor) {\n      await overrides.beforeBuildExecutor(database.kysely);\n    }\n    executorStack = await buildWorkerExecutor({\n      init: msg,\n      database: database.kysely,\n      logger: new ConsoleLogger([`reactor-worker:${msg.workerId}`]),\n      executorConfig: msg.executorConfig,\n      loadFactory: activeLoadFactory,\n    });\n    if (database.poolInstrumentation) {\n      startPoolReporter(database.poolInstrumentation);\n    }\n    initCompleted = true;\n    logger.info(\"worker initialized: @workerId\", msg.workerId);\n    post({\n      type: \"ready\",\n      correlationId: msg.correlationId,\n      workerId: msg.workerId,\n    });\n  }\n\n  async function handleExecute(correlationId: string, job: Job): Promise<void> {\n    if (!executorStack) {\n      post({\n        type: \"result\",\n        correlationId,\n        result: { job, success: false },\n        error: errorToInfo(new Error(\"execute received before init\")),\n      });\n      return;\n    }\n    try {\n      const result = await executorStack.executor.executeJob(job);\n      const writeReady = executorStack.takeLastWriteReady();\n      post({\n        type: \"result\",\n        correlationId,\n        result,\n        writeReady: writeReady ?? undefined,\n      });\n    } catch (error) {\n      post({\n        type: \"result\",\n        correlationId,\n        result: { job, success: false },\n        error: errorToInfo(error),\n      });\n    }\n  }\n\n  async function handleLoadModel(msg: LoadModelMessage): Promise<void> {\n    const stack = executorStack;\n    if (!stack) {\n      post({\n        type: \"model-load-failed\",\n        correlationId: msg.correlationId,\n        documentType: msg.model.documentType,\n        version: msg.model.version,\n        error: errorToInfo(new Error(\"load-model received before init\")),\n      });\n      return;\n    }\n    let module: DocumentModelModule;\n    try {\n      module = (await activeLoadFactory(msg.model.spec)) as DocumentModelModule;\n    } catch (error) {\n      post({\n        type: \"model-load-failed\",\n        correlationId: msg.correlationId,\n        documentType: msg.model.documentType,\n        version: msg.model.version,\n        error: errorToInfo(error),\n      });\n      return;\n    }\n    const [result] = stack.registry.registerModules(module);\n    if (result.status === \"error\") {\n      post({\n        type: \"model-load-failed\",\n        correlationId: msg.correlationId,\n        documentType: msg.model.documentType,\n        version: msg.model.version,\n        error: errorToInfo(result.error),\n      });\n      return;\n    }\n    post({\n      type: \"model-loaded\",\n      correlationId: msg.correlationId,\n      documentType: msg.model.documentType,\n      version: msg.model.version,\n    });\n  }\n\n  async function shutdownDatabase(): Promise<void> {\n    stopPoolReporter();\n    if (database) {\n      await database.shutdown();\n    }\n  }\n\n  function handleParentMessage(msg: ParentMessage): void {\n    switch (msg.type) {\n      case \"init\": {\n        handleInit(msg).catch((err: unknown) => {\n          post({\n            type: \"log\",\n            level: \"error\",\n            message: \"worker init failed\",\n            args: [errorToInfo(err)],\n            timestamp: Date.now(),\n          });\n        });\n        break;\n      }\n\n      case \"execute\": {\n        if (!initCompleted) {\n          logger.warn(\"received execute before init\");\n          post({\n            type: \"result\",\n            correlationId: msg.correlationId,\n            result: { job: msg.job, success: false },\n            error: errorToInfo(new Error(\"execute received before init\")),\n          });\n          break;\n        }\n        handleExecute(msg.correlationId, msg.job).catch((err: unknown) => {\n          post({\n            type: \"result\",\n            correlationId: msg.correlationId,\n            result: { job: msg.job, success: false },\n            error: errorToInfo(err),\n          });\n        });\n        break;\n      }\n\n      case \"shutdown\": {\n        logger.info(\"worker shutting down: @workerId\", workerId);\n        void shutdownDatabase().finally(() => {\n          post({\n            type: \"log\",\n            level: \"info\",\n            message: \"worker shutdown\",\n            args: [],\n            timestamp: Date.now(),\n          });\n          process.exit(0);\n        });\n        break;\n      }\n\n      case \"abort\": {\n        logger.warn(\n          \"abort received (no-op stub): @correlationId\",\n          msg.correlationId,\n        );\n        break;\n      }\n\n      case \"load-model\": {\n        handleLoadModel(msg).catch((err: unknown) => {\n          post({\n            type: \"model-load-failed\",\n            correlationId: msg.correlationId,\n            documentType: msg.model.documentType,\n            version: msg.model.version,\n            error: errorToInfo(err),\n          });\n        });\n        break;\n      }\n\n      default: {\n        const raw = msg as Record<string, unknown>;\n        if (raw[\"type\"] === \"__test_throw\") {\n          const rawReason = raw[\"reason\"];\n          const reason =\n            typeof rawReason === \"string\"\n              ? rawReason\n              : \"synthetic uncaughtException\";\n          setTimeout(() => {\n            throw new Error(reason);\n          }, 0);\n          return;\n        }\n        const _exhaustive: never = msg;\n        void _exhaustive;\n        break;\n      }\n    }\n  }\n\n  parentPort.on(\"message\", handleParentMessage);\n\n  // Test-only exports surfaced on a side-channel for unit tests that drive\n  // the message loop directly without a real worker_threads parent.\n  const harness = {\n    handleParentMessage,\n    get initCompleted(): boolean {\n      return initCompleted;\n    },\n    get initConfig(): InitMessage | null {\n      return initConfig;\n    },\n    get workerId(): string {\n      return workerId;\n    },\n  };\n  (\n    parentPort as unknown as { __reactorWorkerHarness?: unknown }\n  ).__reactorWorkerHarness = harness;\n}\n\nexport type FactorySpecForTesting = FactorySpec;\n","import { isMainThread, parentPort } from \"node:worker_threads\";\nimport { runWorker } from \"./run-worker.js\";\n\nif (isMainThread || parentPort === null) {\n  throw new Error(\"entry.ts must be run as a worker thread\");\n}\n\nrunWorker(parentPort);\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -580,6 +580,8 @@ type AppendConditionStream = {
 type AppendCondition = {
   streams: AppendConditionStream[];
 };
+/** Error history keeps messages, not classes, so failures match by prefix. */
+declare const APPEND_CONDITION_FAILED_PREFIX = "Append condition failed: ";
 /**
  * A read-set stream grew before the append committed. A concurrency
  * conflict, not a fault: the caller retries against the new stream heads.
@@ -588,6 +590,8 @@ declare class AppendConditionFailedError extends Error {
   readonly condition: AppendCondition;
   constructor(condition: AppendCondition);
   static isError(error: unknown): error is AppendConditionFailedError;
+  /** True when a recorded error message is an append-condition failure. */
+  static isFailureMessage(message: string): boolean;
 }
 /**
  * A write transaction passed to {@link IOperationStore.apply}. Accumulates
@@ -1211,6 +1215,51 @@ declare class DriveCollectionId {
   equals(other: DriveCollectionId): boolean;
 }
 //#endregion
+//#region src/cache/write-cache-types.d.ts
+/**
+ * Configuration options for the write cache
+ */
+type WriteCacheConfig = {
+  /** Maximum number of document streams to cache (LRU eviction). Default: 1000 */maxDocuments: number; /** Number of snapshots to keep in each document's ring buffer. Default: 10 */
+  ringBufferSize: number; /** Persist a keyframe snapshot every N revisions. Default: 10 */
+  keyframeInterval: number;
+};
+/**
+ * Unique identifier for a document stream
+ */
+type DocumentStreamKey = {
+  /** Document identifier */documentId: string; /** Operation scope */
+  scope: string; /** Branch name */
+  branch: string;
+};
+/**
+ * Where a snapshot sits in its stream.
+ *
+ * - `Head`: the newest revision of the stream when it was stored. Only these
+ *   can answer a read that asks for the head.
+ * - `Historical`: state at an earlier revision. Usable as a starting point to
+ *   replay forward from, and as an answer to a read for that same revision.
+ */
+declare enum SnapshotPosition {
+  Head = "head",
+  Historical = "historical"
+}
+/**
+ * A cached document snapshot at a specific revision
+ */
+type CachedSnapshot = {
+  /** The revision number of this snapshot */revision: number; /** The document state at this revision */
+  document: PHDocument; /** Where this snapshot sat in the stream when it was stored */
+  position: SnapshotPosition;
+};
+/**
+ * Serialized keyframe snapshot for K/V store persistence
+ */
+type KeyframeSnapshot = {
+  /** The revision number of this keyframe */revision: number; /** Serialized document state */
+  document: string;
+};
+//#endregion
 //#region src/cache/write/interfaces.d.ts
 /**
  * IWriteCache is a write-side projection that optimizes document state retrieval
@@ -1225,7 +1274,8 @@ interface IWriteCache {
    * @param documentId - The document identifier
    * @param scope - Operation scope
    * @param branch - Branch name
-   * @param targetRevision - The exact revision to retrieve (optional, defaults to latest)
+   * @param targetRevision - Index of the last operation to apply, defaulting
+   *   to latest. An operation index, never `header.revision[scope]`.
    * @param signal - Optional abort signal to cancel the operation
    * @returns The complete document at the specified revision
    *
@@ -1251,15 +1301,19 @@ interface IWriteCache {
    * @param documentId - The document identifier
    * @param scope - Operation scope
    * @param branch - Branch name
-   * @param revision - The revision this document represents
+   * @param revision - Index of the last operation this document reflects, so
+   *   `header.revision[scope]` is one greater. -1 for an empty scope.
    * @param document - The document to cache
+   * @param position - Whether `revision` is the stream's head. Nothing checks
+   *   it: claiming `Head` for an earlier revision makes a getState() with no
+   *   target return stale state.
    *
    * @example
    * ```typescript
-   * cache.putState(docId, 'global', 'main', 42, document);
+   * cache.putState(docId, 'global', 'main', 42, document, SnapshotPosition.Head);
    * ```
    */
-  putState(documentId: string, scope: string, branch: string, revision: number, document: PHDocument): void;
+  putState(documentId: string, scope: string, branch: string, revision: number, document: PHDocument, position: SnapshotPosition): void;
   /**
    * Invalidates (removes) cached entries for a document stream.
    *
@@ -2304,7 +2358,8 @@ type InitMessage = {
   poolConfig: WorkerPoolConfig;
   db: DbConfig; /** Omitted = the worker performs no executor-side signature verification. */
   signatureVerifier?: SignatureVerifierSpec;
-  models: ModelManifestEntry[];
+  models: ModelManifestEntry[]; /** Omitted = the worker builds its executor with the built-in defaults. */
+  executorConfig?: JobExecutorConfig;
 };
 /**
  * Dispatches a job to the worker for execution.
@@ -3942,38 +3997,6 @@ declare class NullDocumentModelResolver implements IDocumentModelResolver {
  */
 type WorkerFactory = (index: number) => IExecutorWorker;
 //#endregion
-//#region src/cache/write-cache-types.d.ts
-/**
- * Configuration options for the write cache
- */
-type WriteCacheConfig = {
-  /** Maximum number of document streams to cache (LRU eviction). Default: 1000 */maxDocuments: number; /** Number of snapshots to keep in each document's ring buffer. Default: 10 */
-  ringBufferSize: number; /** Persist a keyframe snapshot every N revisions. Default: 10 */
-  keyframeInterval: number;
-};
-/**
- * Unique identifier for a document stream
- */
-type DocumentStreamKey = {
-  /** Document identifier */documentId: string; /** Operation scope */
-  scope: string; /** Branch name */
-  branch: string;
-};
-/**
- * A cached document snapshot at a specific revision
- */
-type CachedSnapshot = {
-  /** The revision number of this snapshot */revision: number; /** The document state at this revision */
-  document: PHDocument;
-};
-/**
- * Serialized keyframe snapshot for K/V store persistence
- */
-type KeyframeSnapshot = {
-  /** The revision number of this keyframe */revision: number; /** Serialized document state */
-  document: string;
-};
-//#endregion
 //#region src/projection/protocol.d.ts
 /**
  * Identifier for a built-in read model the projection worker materializes
@@ -4993,6 +5016,8 @@ declare class KyselyWriteCache implements IWriteCache {
   /**
    * Retrieves document state at a specific revision from cache or rebuilds it.
    *
+   * Note: this returns a _shallow_ copy of the document.
+   *
    * Cache hit path: Returns cached snapshot if available (O(1))
    * Warm miss path: Rebuilds from cached base revision + incremental ops
    * Cold miss path: Rebuilds from keyframe or from scratch using all operations
@@ -5030,7 +5055,8 @@ declare class KyselyWriteCache implements IWriteCache {
    * @param document - The document to cache
    * @throws {Error} If document serialization fails
    */
-  putState(documentId: string, scope: string, branch: string, revision: number, document: PHDocument): void;
+  putState(documentId: string, scope: string, branch: string, revision: number, document: PHDocument, position: SnapshotPosition): void;
+  private store;
   /**
    * Invalidates cached document streams.
    *
@@ -5059,6 +5085,13 @@ declare class KyselyWriteCache implements IWriteCache {
   getStream(documentId: string, scope: string, branch: string): DocumentStream | undefined;
   private findNearestKeyframe;
   private coldMissRebuild;
+  /**
+   * Copies the current document revisions onto the document. Overwrites the
+   * requested scope revision with the target revision, if provided.
+   */
+  private stampRevisions;
+  /** The stored operation at `index`, or undefined if it is no longer there. */
+  private operationAt;
   /**
    * Resolves which module version to use for a given operation in phase 2.
    *
@@ -5829,5 +5862,5 @@ declare class ProcessorManager extends BaseReadModel implements IProcessorManage
   private deleteProcessorCursors;
 }
 //#endregion
-export { type AbortMessage, type AppendCondition, AppendConditionFailedError, type AppendConditionStream, type AtomicTxn, type AttachmentHash, type AttachmentRef, BaseReadModel, type BatchExecutionRequest, type BatchExecutionResult, type BatchLoadRequest, type BatchLoadResult, type BuiltDecisionModel, 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, DRIVE_AUTH_ERROR_MESSAGES, type Database, type DbConfig, type DeadLetterAddedEvent, type DecisionContext, type DecisionModel, type DecisionTarget, DefaultSubscriptionErrorHandler, type DocumentChangeEvent, DocumentChangeType, type DocumentGraphEdge, type DocumentIndexerDatabase, DocumentIntegrityService, DocumentModelRegistry, DocumentModelResolver, type DocumentModelSource, type DocumentModelSpec, type DocumentRelationship, type DocumentRevisions, type DocumentStreamKey, type DocumentViewDatabase, DriveClient, DriveCollectionId, DuplicateManifestError, DuplicateModuleError, DuplicateOperationError, EventBus, EventBusAggregateError, type ExecuteMessage, type ExecutionJobPlan, type ExecutorStartedEvent, type ExecutorStoppedEvent, type FactorySpec, type FileModelSource, 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 ILiveReadModelCoordinator, type IMailbox, 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 InProcessReactorClientModule, type InProcessReactorModule, type InProcessSyncModule, 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 ModelLoadedEvent, type ModelLoadedMessage, type ModelManifestEntry, ModuleNotFoundError, type ModuleRef, NullDocumentModelResolver, type OperationBatch, type OperationContext, type OperationFilter, type OperationIndexEntry, type OperationTable, type OperationWithContext, OptimisticLockError, type PackageModelSource, 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 Projection, 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 ReadModelRegistrationStage, type ReadModelStage, type ReadyMessage, type RebuildResult, RelationalDbProcessor, RelationshipChangeType, type Remote, type RemoteCursor, type RemoteFilter, type RemoteMeta, type RemoteOptions, type RemoteRecord, type RemoteStatus, type ResultMessage, RetryAccounting, RevisionMismatchError, type SanitizedArg, type SearchFilter, type ShutdownMessage, type ShutdownStatus, type SignatureVerificationHandler, type SignatureVerifierSpec, type SignerConfig, SimpleJobExecutorManager, type SnapshotValidationIssue, type Database$1 as StorageDatabase, type StreamQuery, 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 WorkerPoolOptions, type WriteCacheConfig, addRelationshipAction, batchOperationsByDocument, buildDecisionModel, consolidateSyncOperations, createDocumentAction, createForwardingLogger, createMutableShutdownStatus, createRelationalDb, deleteDocumentAction, documentActions, driveIdFromUrl, envelopesToSyncOperations, errorToInfo, getMigrationStatus, instrumentPgPool, isDriveAuthError, makeConsistencyKey, parseDriveUrl, parsePagingOptions, removeRelationshipAction, runMigrations, sanitizeArg, supportsLiveReadModelRegistration, trimMailboxFromAckOrdinal, updateRelationshipAction, upgradeDocumentAction, workerEntryPath };
+export { APPEND_CONDITION_FAILED_PREFIX, type AbortMessage, type AppendCondition, AppendConditionFailedError, type AppendConditionStream, type AtomicTxn, type AttachmentHash, type AttachmentRef, BaseReadModel, type BatchExecutionRequest, type BatchExecutionResult, type BatchLoadRequest, type BatchLoadResult, type BuiltDecisionModel, 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, DRIVE_AUTH_ERROR_MESSAGES, type Database, type DbConfig, type DeadLetterAddedEvent, type DecisionContext, type DecisionModel, type DecisionTarget, DefaultSubscriptionErrorHandler, type DocumentChangeEvent, DocumentChangeType, type DocumentGraphEdge, type DocumentIndexerDatabase, DocumentIntegrityService, DocumentModelRegistry, DocumentModelResolver, type DocumentModelSource, type DocumentModelSpec, type DocumentRelationship, type DocumentRevisions, type DocumentStreamKey, type DocumentViewDatabase, DriveClient, DriveCollectionId, DuplicateManifestError, DuplicateModuleError, DuplicateOperationError, EventBus, EventBusAggregateError, type ExecuteMessage, type ExecutionJobPlan, type ExecutorStartedEvent, type ExecutorStoppedEvent, type FactorySpec, type FileModelSource, 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 ILiveReadModelCoordinator, type IMailbox, 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 InProcessReactorClientModule, type InProcessReactorModule, type InProcessSyncModule, 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 ModelLoadedEvent, type ModelLoadedMessage, type ModelManifestEntry, ModuleNotFoundError, type ModuleRef, NullDocumentModelResolver, type OperationBatch, type OperationContext, type OperationFilter, type OperationIndexEntry, type OperationTable, type OperationWithContext, OptimisticLockError, type PackageModelSource, 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 Projection, 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 ReadModelRegistrationStage, type ReadModelStage, type ReadyMessage, type RebuildResult, RelationalDbProcessor, RelationshipChangeType, type Remote, type RemoteCursor, type RemoteFilter, type RemoteMeta, type RemoteOptions, type RemoteRecord, type RemoteStatus, type ResultMessage, RetryAccounting, RevisionMismatchError, type SanitizedArg, type SearchFilter, type ShutdownMessage, type ShutdownStatus, type SignatureVerificationHandler, type SignatureVerifierSpec, type SignerConfig, SimpleJobExecutorManager, type SnapshotValidationIssue, type Database$1 as StorageDatabase, type StreamQuery, 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 WorkerPoolOptions, type WriteCacheConfig, addRelationshipAction, batchOperationsByDocument, buildDecisionModel, consolidateSyncOperations, createDocumentAction, createForwardingLogger, createMutableShutdownStatus, createRelationalDb, deleteDocumentAction, documentActions, driveIdFromUrl, envelopesToSyncOperations, errorToInfo, getMigrationStatus, instrumentPgPool, isDriveAuthError, makeConsistencyKey, parseDriveUrl, parsePagingOptions, removeRelationshipAction, runMigrations, sanitizeArg, supportsLiveReadModelRegistration, trimMailboxFromAckOrdinal, updateRelationshipAction, upgradeDocumentAction, workerEntryPath };
 //# sourceMappingURL=index.d.ts.map