@arki/journal 0.1.1 → 0.2.1

package/src/api.ts

@@ -22,6 +22,7 @@ import type {
   EntityTable,
   EventDef,
   EventOptions,
+  HandlerServices,
   IdTable,
   JournalWorker,
   KeyName,
@@ -81,6 +82,27 @@ export type Command<S extends z.ZodType, R, in MetaOut, in Tx extends Transactio
   readonly name: string;
   readonly input: S;
   readonly handler: (input: z.output<S>, context: CommandContext<MetaOut, Tx>) => R;
+  /** The command's `authorize` option, when it has one. See {@link CommandOptions}. */
+  readonly authorize?: CommandAuthorize<z.output<S>, MetaOut, Tx>;
+};
+/**
+ * Decides whether the caller may run a command. It runs inside the command's transaction,
+ * after the input and `meta` are parsed, on every call: a call that replays an idempotency
+ * receipt runs it too, before the stored result is returned. Throw (a `CommandError`
+ * `FORBIDDEN`, usually) to refuse; the run rolls back and nothing is replayed.
+ */
+export type CommandAuthorize<Input, in MetaOut, in Tx extends TransactionSource<Tx> = DbHandle> = (
+  input: Input,
+  context: { readonly tx: Tx; readonly meta: MetaOut },
+) => void | Promise<void>;
+/** Options of `j.command`. */
+export type CommandOptions<Input, MetaOut, Tx extends TransactionSource<Tx> = DbHandle> = {
+  /**
+   * Put the caller's permission check here, not in the handler. A repeat with an idempotency
+   * key does not run the handler, so a check inside it would not run either: the stored result
+   * would go to whoever replays the key. `authorize` runs on the first call and on every replay.
+   */
+  readonly authorize?: CommandAuthorize<Input, MetaOut, Tx>;
 };
 /**
  * What a command handler receives. `write` and `run` are bound to the command's
@@ -295,10 +317,16 @@ export type Journal<
    * covers only its own work, and the lease is renewed every half lease while the effect
    * runs. A lost lease aborts the effect's `ctx.signal`.
    * Once `signal` is aborted no further job is claimed; the running one sees it as `ctx.signal`.
+   * `services`: see `worker`.
    */
   drain(
     db: AppDb & RootDb & TransactionSource<Tx>,
-    opts?: { readonly batchSize?: number; readonly signal?: AbortSignal; readonly leaseSeconds?: number },
+    opts?: {
+      readonly batchSize?: number;
+      readonly signal?: AbortSignal;
+      readonly leaseSeconds?: number;
+      readonly services?: HandlerServices;
+    },
   ): Promise<number>;
   /**
    * A loop around `drain`. The same database as `drain`. `stop()` aborts the running
@@ -318,6 +346,12 @@ export type Journal<
       readonly listen?: WakeListener;
       /** `false`: a jobs-only worker in a journal that has taps. Another process must listen. */
       readonly taps?: boolean;
+      /**
+       * The services of a journal composed with `services: 'worker'`, per effect and tap.
+       * A need without a value throws here, before the worker starts. A journal composed
+       * with its services ignores this.
+       */
+      readonly services?: HandlerServices;
     },
   ): JournalWorker;
   /**
@@ -409,6 +443,7 @@ export type JournalDefinitions<
     name: string,
     input: S,
     handler: (input: z.output<S>, context: CommandContext<z.output<Meta>, Tx>) => R,
+    options?: CommandOptions<z.output<S>, z.output<Meta>, Tx>,
   ): Command<S, R, z.output<Meta>, Tx>;
   /** `on` is `NoInfer` so `E` comes from `entity`; handlers are then contextually typed. */
   projection<E extends AnyEntity<z.output<Meta>>>(
@@ -434,7 +469,7 @@ export type JournalDefinitions<
   ): Effect<z.output<Meta>, AppDb, RootCommandRunner<Meta, Tx>, N>;
   /**
    * Build the runtime journal from the tables and the handlers. `services` holds one
-   * value for every need of every listed effect, by name. A need without a value throws here.
+   * value for every need of every listed effect, by name. A need without a value throws here, unless `services` is `'worker'`.
    * `const`: the list is read as a tuple, so an effect with needs keeps them next to one without.
    */
   /** A tap: in-process, after commit, lossy. See `Tap`. Same shapes as `effect`. */
@@ -461,5 +496,12 @@ export type JournalDefinitions<
     } & ServicesOption<ServicesFor<E> & ServicesFor<T>>,
   ): Journal<Meta, Tx, AppDb>;
 };
-/** `services` is required as soon as one listed effect has a need. */
-type ServicesOption<S> = unknown extends S ? { readonly services?: Services } : { readonly services: S & Services };
+/**
+ * `services` is required as soon as one listed effect has a need. `'worker'` leaves the needs
+ * open: writes never need them, and each `worker` or `drain` gives them (`HandlerServices`).
+ * That is for services that exist only after the journal: the Dot adapter's features boot
+ * after the journal they write through.
+ */
+type ServicesOption<S> = unknown extends S
+  ? { readonly services?: Services | 'worker' }
+  : { readonly services: (S & Services) | 'worker' };

package/src/command.ts

@@ -168,6 +168,9 @@ export function createCommandRunner<Meta extends z.ZodObject, Tx extends Transac
               idempotencyKey: key ?? null,
             },
             async (): Promise<Awaited<R>> => {
+              // Before the receipt: a receipt proves the command ran once, not that this caller
+              // may have its result. A replay is authorized like a first run.
+              if (command.authorize !== undefined) await command.authorize(parsed, { tx, meta });
               if (key === undefined) return await command.handler(parsed, context);
               const held = await claimReceipt(tx, key, command.name, parsed, own);
               if (held !== undefined) {

package/src/dot.ts

@@ -1,19 +1,27 @@
 /**
- * `@arki/dot` adapter.
+ * `@arki/dot` adapter, in two parts:
  *
- * - `journal(...)` is the plugin. It publishes the journal as `services.journal`
- *   and runs one worker per plugin instance between `start` and `stop`.
- * - `journalHandlers(...)` is the feature slice. A feature lists its projections
- *   and effects with it, and `journal({ j, tables, features })` collects them.
+ * - `journal(...)` is the driven part, for `.use()`. It publishes `services.journal`, so
+ *   features can write through it. With `{ j, tables }` it composes the journal from the
+ *   features' `journalHandlers` declarations. It reads them from the feature values, so it
+ *   boots before the features.
+ * - `journalWorker(...)` is the driving part, for `.serve()`. It runs the effects, taps and
+ *   async projections between `start` and `stop`. It gives each effect and tap the services
+ *   of the feature that lists it.
  *
- * The app's `db` plugin must publish the root Drizzle database under the `db` key.
+ * The split works because writes never need an effect's services: a write only queues
+ * the effect's job. Inline projections run inside the write, and they get only the
+ * transaction. So the journal is composed with `services: 'worker'`, and the worker
+ * gives the services when it runs a handler.
  *
+ * The app's `db` plugin must publish the root Drizzle database under the `db` key.
  * `@arki/dot` is an optional peer. Import this module only inside a Dot app.
- * Feature slices are read by shape: this file never imports `@arki/feature`.
  */
 import type { z } from 'zod';
 
-import type { Plugin, Service, Token } from '@arki/dot/plugin';
+import type { AnyFeature, Driven, Driver } from '@arki/dot/feature';
+import type { EmptyShape, Plugin, Service } from '@arki/dot/plugin';
+import { driven, driver, sliceOf } from '@arki/dot/feature';
 import { DotPluginError, plugin, service } from '@arki/dot/plugin';
 
 import type { Journal, JournalDefinitions } from './api.js';
@@ -21,6 +29,7 @@ import type { JournalTables } from './pg.js';
 import type {
   DbHandle,
   Effect,
+  HandlerServices,
   JournalWorker,
   Needs,
   Projection,
@@ -33,11 +42,11 @@ import type {
 } from './types.js';
 import { debugWorker } from './debug.js';
 import { JournalError } from './errors.js';
-import { bindEffect, bindTap } from './handlers.js';
+import { givenServices } from './handlers.js';
 
 export const JOURNAL_ACTION_META_SCHEMA = '@arki/journal/action-meta@1';
 
-export const JOURNAL_PLUGIN_ERROR_CODES = { badSlice: 'JOURNAL_PLUGIN_E001' } as const;
+export const JOURNAL_PLUGIN_ERROR_CODES = { badSlice: 'ARKI_JOURNAL_PLUGIN_E001' } as const;
 
 /** One effect in the app manifest: async work that the journal's job table feeds in. */
 export type JournalDotAction = {
@@ -49,21 +58,27 @@ export type JournalDotAction = {
   readonly meta: { readonly entities: string[]; readonly events: string[] };
 };
 
-/** What one feature hands to the journal. Its effects already hold the feature's services. */
-export type JournalHandlers<Meta = unknown, Tx = DbHandle, AppDb = RootDb> = {
+/** What one feature hands to the journal, as declared: an effect or a tap may still have needs. */
+export type JournalDeclarations<Meta = unknown, Tx = DbHandle, AppDb = RootDb> = {
   readonly projections: readonly Projection<Meta, Tx>[];
-  readonly effects: readonly Effect<Meta, AppDb>[];
-  readonly taps: readonly Tap<Meta, AppDb>[];
+  readonly effects: readonly Effect<Meta, AppDb, unknown, Needs>[];
+  readonly taps: readonly Tap<Meta, AppDb, Needs>[];
 };
 
+/** What a feature's `journal` slice publishes at boot: its services, for its effects and taps. */
+export type JournalSlicePayload = { readonly services: Services };
+
 /**
- * The `@arki/feature` slice contract a `journalHandlers(...)` declaration produces.
- * `TServices` is what the feature's effects need: the feature must declare it in `needs`.
+ * The feature slice a `journalHandlers(...)` declaration produces.
+ * `handlers` is read before the features boot, by `journal({ j, tables })`.
+ * `resolve` runs at the feature's boot. `TServices` is what the feature's effects and
+ * taps need: the feature must declare it in `needs`.
  */
 export type JournalFeatureSlice<Meta = unknown, Tx = DbHandle, AppDb = RootDb, TServices = unknown> = {
   readonly key: 'journal';
   readonly actions: readonly JournalDotAction[];
-  readonly resolve: (services: TServices) => JournalHandlers<Meta, Tx, AppDb>;
+  readonly handlers: JournalDeclarations<Meta, Tx, AppDb>;
+  readonly resolve: (services: TServices) => JournalSlicePayload;
 };
 
 function effectAction(effect: {
@@ -82,14 +97,14 @@ function effectAction(effect: {
 }
 
 /**
- * Declare a feature's projections and effects as a boot-time slice
- * (`defineFeature(..., { use: [journalHandlers({ projections, effects })] })`).
- * The payload lands under `journal` in the feature's slice token, where
- * `journal({ j, tables, features })` collects it.
+ * Declare a feature's projections, effects and taps
+ * (`feature('orders', { use: [journalHandlers({ projections, effects })] })`).
+ * `journal({ j, tables })` reads them from the feature value and composes the journal.
  *
  * An effect with needs (`j.effect(name, entity, { mailer: need<Mailer>() }, on)`) gets
- * them from the booted services of this feature, by name. The feature must declare
- * each one in its own `needs`: the slice's `resolve` does not type-check otherwise.
+ * them from the booted services of this feature, by name, when `journalWorker()` runs it.
+ * The feature must declare each one in its own `needs`: the slice's `resolve` does not
+ * type-check otherwise, and throws at the feature's boot when the types were bypassed.
  * Two features may use the same need name for two different services.
  *
  * Actions: one per effect. Projections add none: they run inside the write, not
@@ -110,53 +125,47 @@ export function journalHandlers<
   return {
     key: 'journal',
     actions: effects.map(effect => effectAction(effect)),
+    handlers: { projections, effects, taps },
     // The kernel hands the feature's services over untyped, so they are read by name here.
-    resolve: (services: unknown) => ({
-      projections,
-      effects: effects.map(effect => bindEffect(effect, isServices(services) ? services : {})),
-      taps: taps.map(tap => bindTap(tap, isServices(services) ? services : {})),
-    }),
+    resolve: (services: unknown) => {
+      const given = isServices(services) ? services : {};
+      // Checked at the feature's boot, so a missing service never waits for the first job.
+      for (const effect of effects) givenServices('effect', effect, given);
+      for (const tap of taps) givenServices('tap', tap, given);
+      return { services: given };
+    },
   };
 }
 
 const isServices = (value: unknown): value is Services => typeof value === 'object' && value !== null;
 
-type WorkerOptions = {
-  /** Run the async lane in this process. Default `true`. */
-  readonly worker?: boolean;
-  readonly pollMs?: number;
-  readonly batchSize?: number;
-  readonly leaseSeconds?: number;
-  /** See `journal.worker`: required when the journal has taps, unless `taps: false`. */
-  readonly listen?: WakeListener;
-  readonly taps?: boolean;
-};
-
 /** Direct mode: the app composed the journal itself. */
-export type JournalDirectOptions<
-  Meta extends z.ZodObject,
-  Tx extends TransactionSource<Tx>,
-  AppDb extends RootDb,
-> = WorkerOptions & { readonly journal: Journal<Meta, Tx, AppDb> };
+export type JournalDirectOptions<Meta extends z.ZodObject, Tx extends TransactionSource<Tx>, AppDb extends RootDb> = {
+  readonly journal: Journal<Meta, Tx, AppDb>;
+};
 
-/** Feature mode: the plugin composes the journal from the features' `journalHandlers` slices. */
-export type JournalFeatureOptions<
-  Meta extends z.ZodObject,
-  Tx extends TransactionSource<Tx>,
-  AppDb extends RootDb,
-> = WorkerOptions & {
+/** Feature mode: the journal is composed from the features' `journalHandlers` declarations. */
+export type JournalFeatureOptions<Meta extends z.ZodObject, Tx extends TransactionSource<Tx>, AppDb extends RootDb> = {
   readonly j: Pick<JournalDefinitions<Meta, Tx, AppDb>, 'compose'>;
   readonly tables: JournalTables;
-  /** `tokens(features)` from `@arki/feature/dot`. A feature without a journal slice adds nothing. */
-  readonly features: readonly Token<object, string>[];
 };
 
 /**
  * `RootDb` again on purpose: a Drizzle transaction fits `AppDb` by shape, and must not fit here.
  * `TransactionSource<Tx>`: the worker's database runs the commands of effects, so it opens `Tx`.
  */
+type JournalNeeds<Tx extends TransactionSource<Tx>, AppDb extends RootDb> = {
+  db: AppDb & RootDb & TransactionSource<Tx>;
+};
+
 export type JournalPlugin<Meta extends z.ZodObject, Tx extends TransactionSource<Tx>, AppDb extends RootDb> = Plugin<
-  { db: AppDb & RootDb & TransactionSource<Tx> },
+  JournalNeeds<Tx, AppDb>,
+  { journal: Journal<Meta, Tx, AppDb> }
+>;
+
+/** Feature mode: bound to the app's features when the app is built. */
+export type JournalDriven<Meta extends z.ZodObject, Tx extends TransactionSource<Tx>, AppDb extends RootDb> = Driven<
+  JournalNeeds<Tx, AppDb>,
   { journal: Journal<Meta, Tx, AppDb> }
 >;
 
@@ -168,101 +177,91 @@ const isHandler = (value: unknown): boolean =>
   'run' in value &&
   typeof value.run === 'function';
 
-/** The kernel hands services over untyped, so the slice shape is checked here, once, at boot. */
-function isJournalHandlers(value: unknown): value is JournalHandlers {
+const isHandlerList = (value: unknown): boolean => Array.isArray(value) && value.every(item => isHandler(item));
+
+/** A slice's static `handlers` are read untyped from the feature, so their shape is checked here. */
+function isJournalDeclarations(value: unknown): value is JournalDeclarations {
   return (
     typeof value === 'object' &&
     value !== null &&
     'projections' in value &&
-    Array.isArray(value.projections) &&
-    value.projections.every(item => isHandler(item)) &&
+    isHandlerList(value.projections) &&
     'effects' in value &&
-    Array.isArray(value.effects) &&
-    value.effects.every(item => isHandler(item)) &&
+    isHandlerList(value.effects) &&
     'taps' in value &&
-    Array.isArray(value.taps) &&
-    value.taps.every(item => isHandler(item))
+    isHandlerList(value.taps)
   );
 }
 
+function badSlice(feature: AnyFeature, what: string): DotPluginError {
+  return new DotPluginError({
+    code: JOURNAL_PLUGIN_ERROR_CODES.badSlice,
+    message: `[journal] feature "${feature.name}" has a \`journal\` slice whose ${what}.`,
+    remediation: 'Declare the slice with journalHandlers({ projections, effects, taps }) from @arki/journal/dot.',
+    docsUrl: 'https://github.com/arki-labs/arki/blob/HEAD/packages/journal/docs/agent-guide.md#dot-boot-errors',
+  });
+}
+
 /**
  * Throws when another handler of this kind already has the name, and names the
- * feature tokens that hold the two. `j.compose` makes the same check, but it gets
+ * features that hold the two. `j.compose` makes the same check, but it gets
  * one flat list and cannot say which feature a handler came from.
  */
 function claimName(
   kind: 'effect' | 'projection' | 'tap',
-  owners: Map<string, string>,
+  owners: Map<string, AnyFeature>,
   name: string,
-  feature: string,
+  feature: AnyFeature,
 ): void {
-  const owner = owners.get(name);
+  const owner = owners.get(`${kind}:${name}`);
   if (owner !== undefined) {
-    const where = owner === feature ? `feature "${feature}", twice` : `features "${owner}" and "${feature}"`;
+    const where =
+      owner === feature ? `feature "${feature.name}", twice` : `features "${owner.name}" and "${feature.name}"`;
     throw new JournalError('BAD_DEFINITION', kind, name, `journal: duplicate ${kind} name "${name}" (${where})`);
   }
-  owners.set(name, feature);
+  owners.set(`${kind}:${name}`, feature);
 }
 
 /**
- * Read each feature's `journal` slice from the booted services, in feature order.
- * Refuses a projection name or an effect name that is listed twice.
+ * Read each feature's `journal` slice declarations, in feature order. Refuses a name
+ * that is listed twice. `owners` maps `effect:<name>` and `tap:<name>` (and
+ * `projection:<name>`) to the feature that lists it.
  */
-function collectHandlers(
-  features: readonly Token<object, string>[],
-  services: Readonly<Record<string, unknown>>,
-): JournalHandlers {
+function readDeclarations(features: readonly AnyFeature[]): {
+  readonly declarations: JournalDeclarations;
+  readonly owners: ReadonlyMap<string, AnyFeature>;
+} {
   const projections: Projection[] = [];
-  const effects: Effect[] = [];
-  const taps: Tap[] = [];
-  const projectionOwners = new Map<string, string>();
-  const effectOwners = new Map<string, string>();
-  const tapOwners = new Map<string, string>();
+  const effects: Effect<unknown, RootDb, unknown, Needs>[] = [];
+  const taps: Tap<unknown, RootDb, Needs>[] = [];
+  const owners = new Map<string, AnyFeature>();
   for (const feature of features) {
-    const slices = services[feature.key];
-    const slice = typeof slices === 'object' && slices !== null && 'journal' in slices ? slices.journal : undefined;
+    const slice = feature.use.find(item => item.key === 'journal');
     if (slice === undefined) {
-      debugWorker.debug('[journal] feature "{featureKey}" did not contribute a journal slice', {
-        featureKey: feature.key,
+      debugWorker.debug('[journal] feature "{featureName}" did not contribute a journal slice', {
+        featureName: feature.name,
       });
       continue;
     }
-    if (!isJournalHandlers(slice)) {
-      throw new DotPluginError({
-        code: JOURNAL_PLUGIN_ERROR_CODES.badSlice,
-        message: `[journal] feature token "${feature.key}" holds a \`journal\` slice that is not lists of projections, effects and taps.`,
-        remediation: 'Declare the slice with journalHandlers({ projections, effects, taps }) from @arki/journal/dot.',
-        docsUrl: 'https://github.com/arki-labs/arki/blob/HEAD/packages/journal/docs/agent-guide.md#dot-boot-errors',
-      });
-    }
-    for (const { name } of slice.projections) claimName('projection', projectionOwners, name, feature.key);
-    for (const { name } of slice.effects) claimName('effect', effectOwners, name, feature.key);
-    for (const { name } of slice.taps) claimName('tap', tapOwners, name, feature.key);
-    projections.push(...slice.projections);
-    effects.push(...slice.effects);
-    taps.push(...slice.taps);
+    const declared: unknown = 'handlers' in slice ? slice.handlers : undefined;
+    if (!isJournalDeclarations(declared))
+      throw badSlice(feature, 'handlers are not lists of projections, effects and taps');
+    for (const { name } of declared.projections) claimName('projection', owners, name, feature);
+    for (const { name } of declared.effects) claimName('effect', owners, name, feature);
+    for (const { name } of declared.taps) claimName('tap', owners, name, feature);
+    projections.push(...declared.projections);
+    effects.push(...declared.effects);
+    taps.push(...declared.taps);
   }
-  return { projections, effects, taps };
+  return { declarations: { projections, effects, taps }, owners };
 }
 
-export function journal<Meta extends z.ZodObject, Tx extends TransactionSource<Tx>, AppDb extends RootDb>(
-  options: JournalDirectOptions<Meta, Tx, AppDb>,
-): JournalPlugin<Meta, Tx, AppDb>;
-export function journal<Meta extends z.ZodObject, Tx extends TransactionSource<Tx>, AppDb extends RootDb>(
-  options: JournalFeatureOptions<Meta, Tx, AppDb>,
-): JournalPlugin<Meta, Tx, AppDb>;
-export function journal<Meta extends z.ZodObject, Tx extends TransactionSource<Tx>, AppDb extends RootDb>(
-  options: JournalDirectOptions<Meta, Tx, AppDb> | JournalFeatureOptions<Meta, Tx, AppDb>,
-) {
-  let composed: Journal<Meta, Tx, AppDb> | undefined;
-  let worker: JournalWorker | undefined;
-  // Each feature token is a need, so the kernel boots the features first and refuses a missing one.
-  const featureNeeds = 'features' in options ? options.features.map(feature => [feature.key, feature]) : [];
+function journalPlugin<Meta extends z.ZodObject, Tx extends TransactionSource<Tx>, AppDb extends RootDb>(
+  build: () => Journal<Meta, Tx, AppDb>,
+): JournalPlugin<Meta, Tx, AppDb> {
   const needs: { readonly db: Service<AppDb & RootDb & TransactionSource<Tx>> } = {
-    ...Object.fromEntries(featureNeeds),
     db: service<AppDb & RootDb & TransactionSource<Tx>>(),
   };
-
   return plugin({
     name: 'journal',
     needs,
@@ -270,27 +269,97 @@ export function journal<Meta extends z.ZodObject, Tx extends TransactionSource<T
       ctx.registerService('journal', 'custom');
       ctx.declareProvides('journal');
     },
-    boot(services) {
-      composed =
-        'journal' in options
-          ? options.journal
-          : options.j.compose({ tables: options.tables, ...collectHandlers(options.features, services) });
-      return { journal: composed };
-    },
-    async start({ db }) {
-      if (options.worker === false) return;
-      worker = composed?.worker(db, {
-        pollMs: options.pollMs,
-        batchSize: options.batchSize,
-        leaseSeconds: options.leaseSeconds,
-        listen: options.listen,
-        taps: options.taps,
-      });
-      await worker?.start();
-    },
-    async stop() {
-      await worker?.stop();
-      worker = undefined;
-    },
+    boot: () => ({ journal: build() }),
+  });
+}
+
+/**
+ * The driven part, for `.use()`: publishes the journal as `services.journal`.
+ * It runs nothing in the background: serve `journalWorker()` for that.
+ *
+ * - `journal({ journal })`: the journal the app composed itself.
+ * - `journal({ j, tables })`: the journal composed from the `journalHandlers` slices of
+ *   the features the app mounts. Effects and taps get their services from `journalWorker()`.
+ */
+export function journal<Meta extends z.ZodObject, Tx extends TransactionSource<Tx>, AppDb extends RootDb>(
+  options: JournalDirectOptions<Meta, Tx, AppDb>,
+): JournalPlugin<Meta, Tx, AppDb>;
+export function journal<Meta extends z.ZodObject, Tx extends TransactionSource<Tx>, AppDb extends RootDb>(
+  options: JournalFeatureOptions<Meta, Tx, AppDb>,
+): JournalDriven<Meta, Tx, AppDb>;
+export function journal<Meta extends z.ZodObject, Tx extends TransactionSource<Tx>, AppDb extends RootDb>(
+  options: JournalDirectOptions<Meta, Tx, AppDb> | JournalFeatureOptions<Meta, Tx, AppDb>,
+): JournalPlugin<Meta, Tx, AppDb> | JournalDriven<Meta, Tx, AppDb> {
+  if ('journal' in options) {
+    const composed = options.journal;
+    return journalPlugin(() => composed);
+  }
+  const { j, tables } = options;
+  return driven(features =>
+    journalPlugin(() =>
+      // `'worker'`: the effects' services exist only once the features boot, after this journal.
+      j.compose({ tables, ...readDeclarations(features).declarations, services: 'worker' }),
+    ),
+  );
+}
+
+export type JournalWorkerOptions = {
+  readonly pollMs?: number;
+  readonly batchSize?: number;
+  readonly leaseSeconds?: number;
+  /** See `journal.worker`: required when the journal has taps, unless `taps: false`. */
+  readonly listen?: WakeListener;
+  readonly taps?: boolean;
+};
+
+/**
+ * What the worker needs of `services.journal`: any journal fits. The database type
+ * is checked where the journal is mounted (`journal(...)` needs the same `db`).
+ */
+type WorkerHost = {
+  worker(db: RootDb, opts?: JournalWorkerOptions & { readonly services?: HandlerServices }): JournalWorker;
+};
+
+/** The services a feature's `journal` slice published at its boot. */
+function sliceServices(ctx: object, feature: AnyFeature): Services {
+  const payload = sliceOf(ctx, feature).journal;
+  if (typeof payload !== 'object' || payload === null || !('services' in payload) || !isServices(payload.services))
+    throw badSlice(feature, 'boot payload holds no services; it was not made by journalHandlers');
+  return payload.services;
+}
+
+/**
+ * The driving part, for `.serve()`: one worker between `start` and `stop`, for the
+ * journal that `journal(...)` published. Each effect and tap of a feature gets the
+ * services of that feature. A process that serves no worker still writes: its jobs
+ * wait for a process that does.
+ */
+export function journalWorker(
+  options: JournalWorkerOptions = {},
+): Driver<{ db: RootDb; journal: WorkerHost }, EmptyShape> {
+  return driver(features => {
+    let worker: JournalWorker | undefined;
+    return plugin({
+      name: 'journal-worker',
+      needs: { db: service<RootDb>(), journal: service<WorkerHost>() },
+      boot(ctx) {
+        const { owners } = readDeclarations(features);
+        const byFeature = new Map<AnyFeature, Services>();
+        // Every owner listed a `journal` slice, so each has a slice record.
+        for (const feature of new Set(owners.values())) byFeature.set(feature, sliceServices(ctx, feature));
+        const services: HandlerServices = ({ kind, name }) => {
+          const owner = owners.get(`${kind}:${name}`);
+          return (owner === undefined ? undefined : byFeature.get(owner)) ?? {};
+        };
+        // Built at boot, not at start: a missing service fails the boot.
+        worker = ctx.journal.worker(ctx.db, { ...options, services });
+      },
+      async start() {
+        await worker?.start();
+      },
+      async stop() {
+        await worker?.stop();
+      },
+    });
   });
 }