@fullstackhouse/open-mercato-durable-work 0.1.4 → 0.2.0

package/dist/index.js

@@ -36,6 +36,7 @@ import { reconcileOnce } from "./core/reconciler.js";
 import { RECONCILE_QUEUE, RECONCILE_TICK_ID, enqueueJob, startWorker } from "./core/worker.js";
 import { PORTABLE_QUEUE_NAME, deliveryId, makeOwnerId, parseDeliveryId, queueNameFor, sliceIdempotencyKey } from "./core/ids.js";
 import { createTransport, readConfig } from "./om/config.js";
+import { resetInProcessWorker, startInProcessWorker } from "./om/in-process-worker.js";
 import { mikroExecutor, mikroTx } from "./om/sql-executor-mikro.js";
 import { createProgressMirror } from "./om/progress-mirror.js";
 import { DurableWorkJob } from "./modules/durable_work/data/entities.js";
@@ -87,11 +88,13 @@ export {
   readConfig,
   reconcileOnce,
   registry,
+  resetInProcessWorker,
   resolveKind,
   runAfterTransition,
   runSlice,
   runTerminalTransition,
   sliceIdempotencyKey,
+  startInProcessWorker,
   startWorker,
   store,
   transportConformance

package/dist/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/index.ts"],
-  "sourcesContent": ["// Public API of @fullstackhouse/open-mercato-durable-work.\n//\n// The OM module itself lives at ./modules/durable_work and is loaded by the host through\n// `{ id: 'durable_work', from: '@fullstackhouse/open-mercato-durable-work' }`. Everything\n// exported here is usable without Open Mercato: `core/` speaks to Postgres through\n// `SqlExecutor` and to a broker through `TransportAdapter`, which is what lets the failure\n// harness run the real mechanism with no app around it.\n\nexport { metadata } from './modules/durable_work/index'\nexport { features } from './modules/durable_work/acl'\n\nexport type {\n  Delivery,\n  DurableJob,\n  DurableJobStatus,\n  ErrorClass,\n  Lease,\n  LeaseSettings,\n  BudgetSettings,\n  RetrySettings,\n  OrphanPolicy,\n  ParkReason,\n  Scope,\n  SliceOutcome,\n  SliceVerdict,\n  SqlExecutor,\n  SqlTransactor,\n  StartJobInput,\n} from './core/types'\n\nexport {\n  TransientError,\n  TerminalError,\n  UnrecoverableError,\n  LeaseLostError,\n  LockKeyHeldError,\n  NoFurtherAttempts,\n  UnknownKindError,\n  classifyError,\n} from './core/errors'\n\nexport {\n  DEFAULT_BUDGET,\n  DEFAULT_LEASE,\n  DEFAULT_RETRY,\n  KindRegistry,\n  nextAttemptDelayMs,\n  registry,\n  resolveKind,\n} from './core/registry'\nexport type { KindDefinition, ResolvedKind, SliceContext } from './core/registry'\n\nexport {\n  CREATE_INDEXES,\n  CREATE_TABLE,\n  DROP_INDEXES,\n  DROP_TABLE,\n  NO_ORG,\n  SCHEMA_STATEMENTS,\n  TABLE,\n} from './core/schema'\n\nexport * as store from './core/store'\nexport { runSlice } from './core/run-slice'\nexport type { RunSliceDeps, RunSliceResult } from './core/run-slice'\nexport { DomainMirrorMismatchError, runAfterTransition, runTerminalTransition } from './core/terminal'\nexport type { TerminalResult, Transition } from './core/terminal'\nexport { DurableWorkService } from './core/service'\nexport type { DurableWorkServiceDeps, RedriveRefusal, StartResult } from './core/service'\nexport { reconcileOnce } from './core/reconciler'\nexport type { ReconcileReport, ReconcilerDeps } from './core/reconciler'\nexport { RECONCILE_QUEUE, RECONCILE_TICK_ID, enqueueJob, startWorker } from './core/worker'\nexport type { DurableWorker, WorkerOptions } from './core/worker'\nexport { PORTABLE_QUEUE_NAME, deliveryId, makeOwnerId, parseDeliveryId, queueNameFor, sliceIdempotencyKey } from './core/ids'\n\nexport type {\n  BindOptions,\n  BoundWorker,\n  DeliveryHandler,\n  DeliveryState,\n  EnqueueOptions,\n  HandlerContext,\n  TransportAdapter,\n  TransportName,\n} from './transport/types'\nexport { createTransport, readConfig } from './om/config'\nexport type { DurableWorkConfig } from './om/config'\nexport { mikroExecutor, mikroTx } from './om/sql-executor-mikro'\nexport { createProgressMirror } from './om/progress-mirror'\nexport type { ProgressMirror, ProgressServiceLike } from './om/progress-mirror'\nexport { DurableWorkJob } from './modules/durable_work/data/entities'\n\nexport { MemoryTransport } from './transport/memory'\nexport type { MemoryFaults } from './transport/memory'\nexport { BullMQTransport } from './transport/bullmq'\nexport type { BullMQTransportOptions } from './transport/bullmq'\nexport { PgBossTransport } from './transport/pgboss'\nexport type { PgBossTransportOptions } from './transport/pgboss'\nexport { transportConformance } from './transport/conformance'\nexport type { ConformanceHooks } from './transport/conformance'\n"],
-  "mappings": "AAQA,SAAS,gBAAgB;AACzB,SAAS,gBAAgB;AAqBzB;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAGP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEP,YAAY,WAAW;AACvB,SAAS,gBAAgB;AAEzB,SAAS,2BAA2B,oBAAoB,6BAA6B;AAErF,SAAS,0BAA0B;AAEnC,SAAS,qBAAqB;AAE9B,SAAS,iBAAiB,mBAAmB,YAAY,mBAAmB;AAE5E,SAAS,qBAAqB,YAAY,aAAa,iBAAiB,cAAc,2BAA2B;AAYjH,SAAS,iBAAiB,kBAAkB;AAE5C,SAAS,eAAe,eAAe;AACvC,SAAS,4BAA4B;AAErC,SAAS,sBAAsB;AAE/B,SAAS,uBAAuB;AAEhC,SAAS,uBAAuB;AAEhC,SAAS,uBAAuB;AAEhC,SAAS,4BAA4B;",
+  "sourcesContent": ["// Public API of @fullstackhouse/open-mercato-durable-work.\n//\n// The OM module itself lives at ./modules/durable_work and is loaded by the host through\n// `{ id: 'durable_work', from: '@fullstackhouse/open-mercato-durable-work' }`. Everything\n// exported here is usable without Open Mercato: `core/` speaks to Postgres through\n// `SqlExecutor` and to a broker through `TransportAdapter`, which is what lets the failure\n// harness run the real mechanism with no app around it.\n\nexport { metadata } from './modules/durable_work/index'\nexport { features } from './modules/durable_work/acl'\n\nexport type {\n  Delivery,\n  DurableJob,\n  DurableJobStatus,\n  ErrorClass,\n  Lease,\n  LeaseSettings,\n  BudgetSettings,\n  RetrySettings,\n  OrphanPolicy,\n  ParkReason,\n  Scope,\n  SliceOutcome,\n  SliceVerdict,\n  SqlExecutor,\n  SqlTransactor,\n  StartJobInput,\n} from './core/types'\n\nexport {\n  TransientError,\n  TerminalError,\n  UnrecoverableError,\n  LeaseLostError,\n  LockKeyHeldError,\n  NoFurtherAttempts,\n  UnknownKindError,\n  classifyError,\n} from './core/errors'\n\nexport {\n  DEFAULT_BUDGET,\n  DEFAULT_LEASE,\n  DEFAULT_RETRY,\n  KindRegistry,\n  nextAttemptDelayMs,\n  registry,\n  resolveKind,\n} from './core/registry'\nexport type { KindDefinition, ResolvedKind, SliceContext } from './core/registry'\n\nexport {\n  CREATE_INDEXES,\n  CREATE_TABLE,\n  DROP_INDEXES,\n  DROP_TABLE,\n  NO_ORG,\n  SCHEMA_STATEMENTS,\n  TABLE,\n} from './core/schema'\n\nexport * as store from './core/store'\nexport { runSlice } from './core/run-slice'\nexport type { RunSliceDeps, RunSliceResult } from './core/run-slice'\nexport { DomainMirrorMismatchError, runAfterTransition, runTerminalTransition } from './core/terminal'\nexport type { TerminalResult, Transition } from './core/terminal'\nexport { DurableWorkService } from './core/service'\nexport type { DurableWorkServiceDeps, RedriveRefusal, StartResult } from './core/service'\nexport { reconcileOnce } from './core/reconciler'\nexport type { ReconcileReport, ReconcilerDeps } from './core/reconciler'\nexport { RECONCILE_QUEUE, RECONCILE_TICK_ID, enqueueJob, startWorker } from './core/worker'\nexport type { DurableWorker, WorkerOptions } from './core/worker'\nexport { PORTABLE_QUEUE_NAME, deliveryId, makeOwnerId, parseDeliveryId, queueNameFor, sliceIdempotencyKey } from './core/ids'\n\nexport type {\n  BindOptions,\n  BoundWorker,\n  DeliveryHandler,\n  DeliveryState,\n  EnqueueOptions,\n  HandlerContext,\n  TransportAdapter,\n  TransportName,\n} from './transport/types'\nexport { createTransport, readConfig } from './om/config'\nexport type { DurableWorkConfig } from './om/config'\nexport { resetInProcessWorker, startInProcessWorker } from './om/in-process-worker'\nexport type { InProcessWorkerOptions } from './om/in-process-worker'\nexport { mikroExecutor, mikroTx } from './om/sql-executor-mikro'\nexport { createProgressMirror } from './om/progress-mirror'\nexport type { ProgressMirror, ProgressServiceLike } from './om/progress-mirror'\nexport { DurableWorkJob } from './modules/durable_work/data/entities'\n\nexport { MemoryTransport } from './transport/memory'\nexport type { MemoryFaults } from './transport/memory'\nexport { BullMQTransport } from './transport/bullmq'\nexport type { BullMQTransportOptions } from './transport/bullmq'\nexport { PgBossTransport } from './transport/pgboss'\nexport type { PgBossTransportOptions } from './transport/pgboss'\nexport { transportConformance } from './transport/conformance'\nexport type { ConformanceHooks } from './transport/conformance'\n"],
+  "mappings": "AAQA,SAAS,gBAAgB;AACzB,SAAS,gBAAgB;AAqBzB;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAGP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEP,YAAY,WAAW;AACvB,SAAS,gBAAgB;AAEzB,SAAS,2BAA2B,oBAAoB,6BAA6B;AAErF,SAAS,0BAA0B;AAEnC,SAAS,qBAAqB;AAE9B,SAAS,iBAAiB,mBAAmB,YAAY,mBAAmB;AAE5E,SAAS,qBAAqB,YAAY,aAAa,iBAAiB,cAAc,2BAA2B;AAYjH,SAAS,iBAAiB,kBAAkB;AAE5C,SAAS,sBAAsB,4BAA4B;AAE3D,SAAS,eAAe,eAAe;AACvC,SAAS,4BAA4B;AAErC,SAAS,sBAAsB;AAE/B,SAAS,uBAAuB;AAEhC,SAAS,uBAAuB;AAEhC,SAAS,uBAAuB;AAEhC,SAAS,4BAA4B;",
   "names": []
 }

package/dist/om/in-process-worker.js

@@ -0,0 +1,56 @@
+import { registry } from "../core/registry.js";
+import { startWorker } from "../core/worker.js";
+import { readConfig } from "./config.js";
+let started = null;
+async function startInProcessWorker(options = {}) {
+  const config = readConfig(options.env ?? process.env);
+  if (!config.inProcessWorker) return null;
+  if (started) return started;
+  started = (async () => {
+    const log = options.log ?? (() => void 0);
+    const resolveContainer = options.resolveContainer ?? (async () => {
+      const { createRequestContainer } = await import("@open-mercato/shared/lib/di/container");
+      return createRequestContainer();
+    });
+    const container = await resolveContainer();
+    const sql = container.resolve("durableWorkSql");
+    const transport = container.resolve("durableWorkTransport");
+    const worker = await startWorker({
+      sql,
+      transport,
+      registry,
+      kinds: options.kinds,
+      concurrency: options.concurrency,
+      tickMs: config.tickMs,
+      reconcilerGraceMs: config.reconcilerGraceMs,
+      drainTimeoutMs: config.drainTimeoutMs,
+      log
+    });
+    log("durable_work.worker_started", {
+      owner: worker.owner,
+      transport: transport.name,
+      inProcess: true,
+      kinds: registry.list().map((kind) => kind.kind)
+    });
+    let stopping = false;
+    const stop = async (signal) => {
+      if (stopping) return;
+      stopping = true;
+      log("durable_work.worker_draining", { signal, timeoutMs: config.drainTimeoutMs });
+      await worker.stop().catch(() => void 0);
+      log("durable_work.worker_stopped", {});
+    };
+    process.once("SIGTERM", () => void stop("SIGTERM"));
+    process.once("SIGINT", () => void stop("SIGINT"));
+    return { owner: worker.owner };
+  })();
+  return started;
+}
+function resetInProcessWorker() {
+  started = null;
+}
+export {
+  resetInProcessWorker,
+  startInProcessWorker
+};
+//# sourceMappingURL=in-process-worker.js.map

package/dist/om/in-process-worker.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/om/in-process-worker.ts"],
+  "sourcesContent": ["// Running the worker inside the app's server process, rather than beside it.\n//\n// The worker has to be *a* process; it does not have to be its own. `mercato server start`\n// already brings up the queue workers an app declares, and an operator reasonably expects\n// durable work to arrive the same way \u2014 install the package, register the module, done. A\n// deployment that also requires a second container or Deployment is a step every host must get\n// right, and one that is silently fatal when missed: runs are created, adopted, leased by\n// nobody, and parked by the reconciler much later.\n//\n// Coupling the worker to the web process costs less here than it would elsewhere, because the\n// mechanism is built for exactly the failure that coupling introduces. A deploy stops the web\n// process mid-slice; the lease expires, the reconciler takes the job, and another replica\n// resumes from the committed cursor. That is the same path a killed worker takes, and it is\n// tested. Scaling is a benefit rather than a hazard: N web replicas mean N workers, and the\n// lock key still allows only one live run per subject.\n//\n// What it does cost, stated plainly so a host can weigh it:\n//\n//   - the worker shares the pod's memory and database pool with request handling, so a host\n//     that sizes pods tightly must account for a third consumer\n//   - slice work is I/O-bound (SQL, HTTP, a source database), so it interleaves with requests\n//     rather than blocking them \u2014 but a CPU-heavy kind would not, and belongs in its own process\n//   - autoscaling on CPU sees worker load as web load\n//\n// A host that would rather keep them apart sets nothing and runs `mercato durable_work worker`\n// as its own process; that path is unchanged and remains the right one for heavy kinds.\n\nimport { registry } from '../core/registry'\nimport { startWorker } from '../core/worker'\nimport type { SqlTransactor } from '../core/types'\nimport type { TransportAdapter } from '../transport/types'\nimport { readConfig } from './config'\n\nexport type InProcessWorkerOptions = {\n  /** Resolves the app's container. Defaults to Open Mercato's request container. */\n  resolveContainer?: () => Promise<{ resolve(name: string): unknown }>\n  /** Restrict to a subset of registered kinds. */\n  kinds?: string[]\n  concurrency?: number\n  log?: (event: string, fields: Record<string, unknown>) => void\n  env?: NodeJS.ProcessEnv\n}\n\n/** Started once per process, however many times a host's bootstrap runs. Next calls\n *  `register()` per runtime, and a container may be built per request. */\nlet started: Promise<{ owner: string } | null> | null = null\n\n/**\n * Starts the durable worker in this process, if the host asked for one.\n *\n * A no-op unless `DURABLE_WORK_INPROCESS_WORKER` is set, so importing this is safe from a\n * bootstrap that also runs in a CLI, a migration, or a build.\n *\n * Returns the worker's owner id, or null when it did not start.\n */\nexport async function startInProcessWorker(options: InProcessWorkerOptions = {}): Promise<{ owner: string } | null> {\n  const config = readConfig(options.env ?? process.env)\n  if (!config.inProcessWorker) return null\n  if (started) return started\n\n  started = (async () => {\n    const log = options.log ?? (() => undefined)\n    const resolveContainer =\n      options.resolveContainer ??\n      (async () => {\n        const { createRequestContainer } = await import('@open-mercato/shared/lib/di/container')\n        return createRequestContainer()\n      })\n\n    const container = await resolveContainer()\n    const sql = container.resolve('durableWorkSql') as SqlTransactor\n    const transport = container.resolve('durableWorkTransport') as TransportAdapter\n\n    const worker = await startWorker({\n      sql,\n      transport,\n      registry,\n      kinds: options.kinds,\n      concurrency: options.concurrency,\n      tickMs: config.tickMs,\n      reconcilerGraceMs: config.reconcilerGraceMs,\n      drainTimeoutMs: config.drainTimeoutMs,\n      log,\n    })\n\n    log('durable_work.worker_started', {\n      owner: worker.owner,\n      transport: transport.name,\n      inProcess: true,\n      kinds: registry.list().map((kind) => kind.kind),\n    })\n\n    // SIGTERM is what a deploy sends. Draining rather than exiting is the difference between a\n    // slice handing its remaining work back and a slice being cut off between two writes.\n    //\n    // The listeners do not call `process.exit`: this process is the web server, and it owns\n    // when to leave. Draining the worker first is all that is wanted here.\n    let stopping = false\n    const stop = async (signal: string) => {\n      if (stopping) return\n      stopping = true\n      log('durable_work.worker_draining', { signal, timeoutMs: config.drainTimeoutMs })\n      await worker.stop().catch(() => undefined)\n      log('durable_work.worker_stopped', {})\n    }\n    process.once('SIGTERM', () => void stop('SIGTERM'))\n    process.once('SIGINT', () => void stop('SIGINT'))\n\n    return { owner: worker.owner }\n  })()\n\n  return started\n}\n\n/** Test seam: forget that a worker was started in this process. */\nexport function resetInProcessWorker(): void {\n  started = null\n}\n"],
+  "mappings": "AA2BA,SAAS,gBAAgB;AACzB,SAAS,mBAAmB;AAG5B,SAAS,kBAAkB;AAc3B,IAAI,UAAoD;AAUxD,eAAsB,qBAAqB,UAAkC,CAAC,GAAsC;AAClH,QAAM,SAAS,WAAW,QAAQ,OAAO,QAAQ,GAAG;AACpD,MAAI,CAAC,OAAO,gBAAiB,QAAO;AACpC,MAAI,QAAS,QAAO;AAEpB,aAAW,YAAY;AACrB,UAAM,MAAM,QAAQ,QAAQ,MAAM;AAClC,UAAM,mBACJ,QAAQ,qBACP,YAAY;AACX,YAAM,EAAE,uBAAuB,IAAI,MAAM,OAAO,uCAAuC;AACvF,aAAO,uBAAuB;AAAA,IAChC;AAEF,UAAM,YAAY,MAAM,iBAAiB;AACzC,UAAM,MAAM,UAAU,QAAQ,gBAAgB;AAC9C,UAAM,YAAY,UAAU,QAAQ,sBAAsB;AAE1D,UAAM,SAAS,MAAM,YAAY;AAAA,MAC/B;AAAA,MACA;AAAA,MACA;AAAA,MACA,OAAO,QAAQ;AAAA,MACf,aAAa,QAAQ;AAAA,MACrB,QAAQ,OAAO;AAAA,MACf,mBAAmB,OAAO;AAAA,MAC1B,gBAAgB,OAAO;AAAA,MACvB;AAAA,IACF,CAAC;AAED,QAAI,+BAA+B;AAAA,MACjC,OAAO,OAAO;AAAA,MACd,WAAW,UAAU;AAAA,MACrB,WAAW;AAAA,MACX,OAAO,SAAS,KAAK,EAAE,IAAI,CAAC,SAAS,KAAK,IAAI;AAAA,IAChD,CAAC;AAOD,QAAI,WAAW;AACf,UAAM,OAAO,OAAO,WAAmB;AACrC,UAAI,SAAU;AACd,iBAAW;AACX,UAAI,gCAAgC,EAAE,QAAQ,WAAW,OAAO,eAAe,CAAC;AAChF,YAAM,OAAO,KAAK,EAAE,MAAM,MAAM,MAAS;AACzC,UAAI,+BAA+B,CAAC,CAAC;AAAA,IACvC;AACA,YAAQ,KAAK,WAAW,MAAM,KAAK,KAAK,SAAS,CAAC;AAClD,YAAQ,KAAK,UAAU,MAAM,KAAK,KAAK,QAAQ,CAAC;AAEhD,WAAO,EAAE,OAAO,OAAO,MAAM;AAAA,EAC/B,GAAG;AAEH,SAAO;AACT;AAGO,SAAS,uBAA6B;AAC3C,YAAU;AACZ;",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullstackhouse/open-mercato-durable-work",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Durable at-least-once background work for Open Mercato apps: a leased job record in Postgres with epoch fencing, bounded resumable slices, a server-side reconciler, fenced cancel and an operator API. Pluggable transport (BullMQ or pg-boss).",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -85,6 +85,8 @@ export type {
 } from './transport/types'
 export { createTransport, readConfig } from './om/config'
 export type { DurableWorkConfig } from './om/config'
+export { resetInProcessWorker, startInProcessWorker } from './om/in-process-worker'
+export type { InProcessWorkerOptions } from './om/in-process-worker'
 export { mikroExecutor, mikroTx } from './om/sql-executor-mikro'
 export { createProgressMirror } from './om/progress-mirror'
 export type { ProgressMirror, ProgressServiceLike } from './om/progress-mirror'

package/src/om/in-process-worker.test.ts

@@ -0,0 +1,76 @@
+// The worker running inside the host's server process.
+//
+// The behaviour that matters here is not "does it start" but "does it start exactly once, and
+// stay out of the way when it was not asked for". A host's bootstrap runs in places that are
+// not a server — a migration, a CLI command, a build — and Next calls `register()` once per
+// runtime, so a helper that started a worker per call would put several on one process.
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+const stop = vi.fn().mockResolvedValue(undefined)
+const startWorker = vi.fn().mockResolvedValue({ owner: 'dw-test-owner', stop })
+
+vi.mock('../core/worker', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('../core/worker')>()),
+  startWorker: (...args: unknown[]) => startWorker(...args),
+}))
+
+const { resetInProcessWorker, startInProcessWorker } = await import('./in-process-worker')
+
+const container = { resolve: (name: string) => ({ name }) }
+const run = (env: Record<string, string | undefined>) =>
+  startInProcessWorker({ resolveContainer: async () => container, env: env as NodeJS.ProcessEnv })
+
+afterEach(() => {
+  resetInProcessWorker()
+  startWorker.mockClear()
+})
+
+describe('startInProcessWorker', () => {
+  it('does nothing unless the host asked for it', async () => {
+    // Safe to call from a bootstrap shared with migrations and CLI commands.
+    await expect(run({ DURABLE_WORK_TRANSPORT: 'pgboss' })).resolves.toBeNull()
+    expect(startWorker).not.toHaveBeenCalled()
+  })
+
+  it('starts a worker when the flag is set, and reports its owner', async () => {
+    await expect(run({ DURABLE_WORK_TRANSPORT: 'pgboss', DURABLE_WORK_INPROCESS_WORKER: 'true' })).resolves.toEqual({
+      owner: 'dw-test-owner',
+    })
+    expect(startWorker).toHaveBeenCalledTimes(1)
+  })
+
+  it('starts once per process however many times a bootstrap runs', async () => {
+    const env = { DURABLE_WORK_TRANSPORT: 'pgboss', DURABLE_WORK_INPROCESS_WORKER: '1' }
+    const [first, second, third] = await Promise.all([run(env), run(env), run(env)])
+
+    expect(startWorker).toHaveBeenCalledTimes(1)
+    expect(first).toEqual(second)
+    expect(second).toEqual(third)
+  })
+
+  it("passes the host's timing configuration through rather than re-deriving it", async () => {
+    await run({
+      DURABLE_WORK_TRANSPORT: 'pgboss',
+      DURABLE_WORK_INPROCESS_WORKER: 'true',
+      DURABLE_WORK_TICK_MS: '5000',
+      DURABLE_WORK_GRACE_MS: '7000',
+      DURABLE_WORK_DRAIN_TIMEOUT_MS: '9000',
+    })
+
+    expect(startWorker).toHaveBeenCalledWith(
+      expect.objectContaining({ tickMs: 5000, reconcilerGraceMs: 7000, drainTimeoutMs: 9000 }),
+    )
+  })
+
+  it('drains on SIGTERM instead of leaving the process, which the server owns', async () => {
+    await run({ DURABLE_WORK_TRANSPORT: 'pgboss', DURABLE_WORK_INPROCESS_WORKER: 'true' })
+    const exit = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as never)
+
+    process.emit('SIGTERM')
+    await vi.waitFor(() => expect(stop).toHaveBeenCalled())
+
+    expect(exit).not.toHaveBeenCalled()
+    exit.mockRestore()
+  })
+})

package/src/om/in-process-worker.ts

@@ -0,0 +1,118 @@
+// Running the worker inside the app's server process, rather than beside it.
+//
+// The worker has to be *a* process; it does not have to be its own. `mercato server start`
+// already brings up the queue workers an app declares, and an operator reasonably expects
+// durable work to arrive the same way — install the package, register the module, done. A
+// deployment that also requires a second container or Deployment is a step every host must get
+// right, and one that is silently fatal when missed: runs are created, adopted, leased by
+// nobody, and parked by the reconciler much later.
+//
+// Coupling the worker to the web process costs less here than it would elsewhere, because the
+// mechanism is built for exactly the failure that coupling introduces. A deploy stops the web
+// process mid-slice; the lease expires, the reconciler takes the job, and another replica
+// resumes from the committed cursor. That is the same path a killed worker takes, and it is
+// tested. Scaling is a benefit rather than a hazard: N web replicas mean N workers, and the
+// lock key still allows only one live run per subject.
+//
+// What it does cost, stated plainly so a host can weigh it:
+//
+//   - the worker shares the pod's memory and database pool with request handling, so a host
+//     that sizes pods tightly must account for a third consumer
+//   - slice work is I/O-bound (SQL, HTTP, a source database), so it interleaves with requests
+//     rather than blocking them — but a CPU-heavy kind would not, and belongs in its own process
+//   - autoscaling on CPU sees worker load as web load
+//
+// A host that would rather keep them apart sets nothing and runs `mercato durable_work worker`
+// as its own process; that path is unchanged and remains the right one for heavy kinds.
+
+import { registry } from '../core/registry'
+import { startWorker } from '../core/worker'
+import type { SqlTransactor } from '../core/types'
+import type { TransportAdapter } from '../transport/types'
+import { readConfig } from './config'
+
+export type InProcessWorkerOptions = {
+  /** Resolves the app's container. Defaults to Open Mercato's request container. */
+  resolveContainer?: () => Promise<{ resolve(name: string): unknown }>
+  /** Restrict to a subset of registered kinds. */
+  kinds?: string[]
+  concurrency?: number
+  log?: (event: string, fields: Record<string, unknown>) => void
+  env?: NodeJS.ProcessEnv
+}
+
+/** Started once per process, however many times a host's bootstrap runs. Next calls
+ *  `register()` per runtime, and a container may be built per request. */
+let started: Promise<{ owner: string } | null> | null = null
+
+/**
+ * Starts the durable worker in this process, if the host asked for one.
+ *
+ * A no-op unless `DURABLE_WORK_INPROCESS_WORKER` is set, so importing this is safe from a
+ * bootstrap that also runs in a CLI, a migration, or a build.
+ *
+ * Returns the worker's owner id, or null when it did not start.
+ */
+export async function startInProcessWorker(options: InProcessWorkerOptions = {}): Promise<{ owner: string } | null> {
+  const config = readConfig(options.env ?? process.env)
+  if (!config.inProcessWorker) return null
+  if (started) return started
+
+  started = (async () => {
+    const log = options.log ?? (() => undefined)
+    const resolveContainer =
+      options.resolveContainer ??
+      (async () => {
+        const { createRequestContainer } = await import('@open-mercato/shared/lib/di/container')
+        return createRequestContainer()
+      })
+
+    const container = await resolveContainer()
+    const sql = container.resolve('durableWorkSql') as SqlTransactor
+    const transport = container.resolve('durableWorkTransport') as TransportAdapter
+
+    const worker = await startWorker({
+      sql,
+      transport,
+      registry,
+      kinds: options.kinds,
+      concurrency: options.concurrency,
+      tickMs: config.tickMs,
+      reconcilerGraceMs: config.reconcilerGraceMs,
+      drainTimeoutMs: config.drainTimeoutMs,
+      log,
+    })
+
+    log('durable_work.worker_started', {
+      owner: worker.owner,
+      transport: transport.name,
+      inProcess: true,
+      kinds: registry.list().map((kind) => kind.kind),
+    })
+
+    // SIGTERM is what a deploy sends. Draining rather than exiting is the difference between a
+    // slice handing its remaining work back and a slice being cut off between two writes.
+    //
+    // The listeners do not call `process.exit`: this process is the web server, and it owns
+    // when to leave. Draining the worker first is all that is wanted here.
+    let stopping = false
+    const stop = async (signal: string) => {
+      if (stopping) return
+      stopping = true
+      log('durable_work.worker_draining', { signal, timeoutMs: config.drainTimeoutMs })
+      await worker.stop().catch(() => undefined)
+      log('durable_work.worker_stopped', {})
+    }
+    process.once('SIGTERM', () => void stop('SIGTERM'))
+    process.once('SIGINT', () => void stop('SIGINT'))
+
+    return { owner: worker.owner }
+  })()
+
+  return started
+}
+
+/** Test seam: forget that a worker was started in this process. */
+export function resetInProcessWorker(): void {
+  started = null
+}