@pepys/ingest 0.4.0 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pepys/ingest",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "pepys ingest: the receive routes, the fact log and the blob store",
   "license": "MIT",
   "repository": {
@@ -21,9 +21,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@impz/client": "6.12.0",
-    "@pepys/kit": "0.4.0",
-    "@pepys/schema": "0.4.0",
+    "@impz/client": "7.0.0",
+    "@pepys/kit": "0.4.2",
+    "@pepys/schema": "0.4.2",
     "@s2-dev/streamstore": "0.30.0",
     "@zgeoff/std": "0.4.3",
     "tiny-invariant": "1.3.3",

package/src/fact-log/make-batch-appender.ts

@@ -1,10 +1,10 @@
 import type { FactEnvelope, Logger, Result, StreamName, StreamOffset } from '@pepys/kit';
-import { toTagged } from '@zgeoff/std';
-import type { FactLog, StoredFact } from './fact-log.ts';
+import type { FactLog } from './fact-log.ts';
 import { pickAttemptStep } from './pick-attempt-step.ts';
 import type { AttemptResult } from './pick-attempt-step.ts';
 import { pickRetryStep } from './pick-retry-step.ts';
 import { pickSettledAttempt } from './pick-settled-attempt.ts';
+import { readRun } from './read-run.ts';
 
 interface BatchAppenderOptions {
   log: FactLog;
@@ -111,34 +111,3 @@ async function settleAttempt(
     tail,
   );
 }
-
-// A read can end before `count` records, so it repeats from the next offset until it has them all
-// or the stream ends.
-async function readRun(
-  log: FactLog,
-  stream: StreamName,
-  from: StreamOffset,
-  count: number,
-): Promise<Result<readonly StoredFact[], { reason: 'unknown-stream' }>> {
-  const records: StoredFact[] = [];
-
-  while (records.length < count) {
-    const read = await log.read(
-      stream,
-      toTagged<StreamOffset>(from + records.length),
-      count - records.length,
-    );
-
-    if (!read.ok) {
-      return read;
-    }
-
-    if (read.value.length === 0) {
-      break;
-    }
-
-    records.push(...read.value);
-  }
-
-  return { ok: true, value: records };
-}

package/src/fact-log/memory/create-memory-fact-log.ts

@@ -1,7 +1,7 @@
 import type { FactEnvelope, Result, StreamName, StreamOffset } from '@pepys/kit';
 import { toTagged } from '@zgeoff/std';
 import invariant from 'tiny-invariant';
-import { checkAppendBatch } from '../check-append-batch.ts';
+import { checkAppendBatch } from '../../utils/check-append-batch.ts';
 import type { AppendBatchOutcome, FactLog, StoredFact } from '../fact-log.ts';
 import { parseStoredFact } from '../parse-stored-fact.ts';
 

package/src/fact-log/read-run.ts

@@ -0,0 +1,34 @@
+import type { Result, StreamName, StreamOffset } from '@pepys/kit';
+import { toTagged } from '@zgeoff/std';
+import type { FactLog, StoredFact } from './fact-log.ts';
+
+// A read can end before `count` records, so it repeats from the next offset until it has them all
+// or the stream ends.
+export async function readRun(
+  log: FactLog,
+  stream: StreamName,
+  from: StreamOffset,
+  count: number,
+): Promise<Result<readonly StoredFact[], { reason: 'unknown-stream' }>> {
+  const records: StoredFact[] = [];
+
+  while (records.length < count) {
+    const read = await log.read(
+      stream,
+      toTagged<StreamOffset>(from + records.length),
+      count - records.length,
+    );
+
+    if (!read.ok) {
+      return read;
+    }
+
+    if (read.value.length === 0) {
+      break;
+    }
+
+    records.push(...read.value);
+  }
+
+  return { ok: true, value: records };
+}

package/src/fact-log/s2/create-s2-fact-log.ts

@@ -9,7 +9,7 @@ import {
 } from '@s2-dev/streamstore';
 import type { S2Basin, StreamConfig } from '@s2-dev/streamstore';
 import { toTagged } from '@zgeoff/std';
-import { checkAppendBatch } from '../check-append-batch.ts';
+import { checkAppendBatch } from '../../utils/check-append-batch.ts';
 import type { AppendBatchOutcome, FactLog, StoredFact } from '../fact-log.ts';
 import { parseStoredFact } from '../parse-stored-fact.ts';
 import { findAppendOutcome, isUnknownStream } from './find-append-outcome.ts';

package/src/index.ts

@@ -2,15 +2,16 @@ export type * from './blob-store/blob-store.ts';
 export { createGarageBlobStore } from './blob-store/garage/create-garage-blob-store.ts';
 export { createLocalFolderBlobStore } from './blob-store/local-folder/create-local-folder-blob-store.ts';
 export type * from './fact-log/fact-log.ts';
-export { appendLimits } from './fact-log/check-append-batch.ts';
+export { appendLimits } from './utils/check-append-batch.ts';
 export { makeBatchAppender } from './fact-log/make-batch-appender.ts';
 export type { AppendFailure, BatchAppender } from './fact-log/make-batch-appender.ts';
 export { createMemoryFactLog } from './fact-log/memory/create-memory-fact-log.ts';
 export type { MemoryFactLog } from './fact-log/memory/create-memory-fact-log.ts';
-export { planAppends } from './fact-log/plan-appends.ts';
+export { planAppends } from './utils/plan-appends.ts';
 export { createS2FactLog } from './fact-log/s2/create-s2-fact-log.ts';
 export { createIngest } from './receive/create-ingest.ts';
 export type { Ingest, IngestOptions } from './receive/create-ingest.ts';
+export { cursorStream } from './pull/cursors/cursor-stream.ts';
 export type { PullPathName, PullRun, PullRunner } from './pull/make-pull-runner.ts';
 export type { ResyncMarks } from './receive/resync-marks/create-resync-marks.ts';
 export { createFakeSenderProof } from './sender-proof/fake/create-fake-sender-proof.ts';

package/src/pull/collect-timed-pulls.ts

@@ -0,0 +1,23 @@
+import type { SourceDefinition } from '@pepys/kit';
+import type { PullPathName } from './make-pull-runner.ts';
+
+export interface TimedPull {
+  source: string;
+  path: PullPathName;
+  intervalMs: number;
+}
+
+const pullPathNames: readonly PullPathName[] = ['live', 'recovery', 'backfill', 'resync'];
+
+// Every pull path that sets an interval, in the order of the sources and then of the slots.
+export function collectTimedPulls(sources: readonly SourceDefinition[]): TimedPull[] {
+  return sources.flatMap((source) =>
+    pullPathNames.flatMap((pathName) => {
+      const path = source[pathName];
+
+      return path?.kind === 'pull' && path.intervalMs !== null
+        ? [{ source: source.name, path: pathName, intervalMs: path.intervalMs }]
+        : [];
+    }),
+  );
+}

package/src/pull/cursors/build-cursor-entity.ts

@@ -0,0 +1,8 @@
+import type { EntityID } from '@pepys/kit';
+import { toTagged } from '@zgeoff/std';
+import type { PullPathName } from '../make-pull-runner.ts';
+
+// The entity of a pull path's cursor records, such as `github:pull_path:recovery`.
+export function buildCursorEntity(source: string, path: PullPathName): EntityID {
+  return toTagged<EntityID>(`${source}:pull_path:${path}`);
+}

package/src/pull/cursors/build-cursor-record.ts

@@ -0,0 +1,32 @@
+import { buildObservationFactID } from '@pepys/kit';
+import type { FactEnvelope } from '@pepys/kit';
+import type { PullPathName } from '../make-pull-runner.ts';
+import { buildCursorEntity } from './build-cursor-entity.ts';
+
+interface CursorPosition {
+  source: string;
+  path: PullPathName;
+  cursor: string;
+  nowMs: number;
+}
+
+// The record of one pull path's position, in the envelope of a fact so that the log takes it. The
+// ID comes from the position alone, so a retry of the append is settled as the same record.
+export function buildCursorRecord(position: CursorPosition): FactEnvelope<Record<string, never>> {
+  const entity = buildCursorEntity(position.source, position.path);
+
+  return {
+    id: buildObservationFactID({
+      source: position.source,
+      entity,
+      sourceUpdateTime: position.cursor,
+    }),
+    type: 'ingest.cursor.saved',
+    v: 1,
+    api: 'ingest/1',
+    entity,
+    at: new Date(position.nowMs).toISOString(),
+    cursor: position.cursor,
+    payload: {},
+  };
+}

package/src/pull/cursors/cursor-stream.ts

@@ -0,0 +1,6 @@
+import type { StreamName } from '@pepys/kit';
+import { toTagged } from '@zgeoff/std';
+
+// The one stream that belongs to no fact family. Its name has two parts, where a family's stream
+// has three, so no family and no consumer can name it.
+export const cursorStream = toTagged<StreamName>('facts.cursors');

package/src/pull/cursors/format-pull-start.ts

@@ -0,0 +1,13 @@
+import type { ResumedPull } from './read-saved-cursors.ts';
+
+// The start line of one pull timer. It says only whether a cursor was saved: a source chooses what
+// its cursor holds, so the value stays out of the output.
+export function formatPullStart(pull: ResumedPull): string {
+  const detail = {
+    source: pull.source,
+    path: pull.path,
+    cursor: pull.cursor === null ? 'none' : 'saved',
+  };
+
+  return `pull ${pull.source} ${pull.path} ${JSON.stringify(detail)}`;
+}

package/src/pull/cursors/read-saved-cursors.ts

@@ -0,0 +1,55 @@
+import type { EntityID, StreamOffset } from '@pepys/kit';
+import { toTagged } from '@zgeoff/std';
+import invariant from 'tiny-invariant';
+import type { FactLog } from '../../fact-log/fact-log.ts';
+import { readRun } from '../../fact-log/read-run.ts';
+import type { TimedPull } from '../collect-timed-pulls.ts';
+import { buildCursorEntity } from './build-cursor-entity.ts';
+import { cursorStream } from './cursor-stream.ts';
+
+export interface ResumedPull extends TimedPull {
+  // the last cursor that the log holds for the pull path, or null when it holds none
+  cursor: string | null;
+}
+
+const pageSize = 1000;
+
+// Gives each pull the cursor of its newest record in the cursor stream. Reads the stream from its
+// tail towards its start, one page at a time, and stops once every pull has its cursor.
+export async function readSavedCursors(
+  log: FactLog,
+  pulls: readonly TimedPull[],
+): Promise<ResumedPull[]> {
+  const tail = await log.readTail(cursorStream);
+
+  invariant(tail.ok, 'the log holds the cursor stream');
+
+  const wanted = new Set(pulls.map((pull) => buildCursorEntity(pull.source, pull.path)));
+  const saved = new Map<EntityID, string>();
+
+  let end: number = tail.value;
+
+  while (end > 0 && saved.size < wanted.size) {
+    const from = Math.max(0, end - pageSize);
+
+    const page = await readRun(log, cursorStream, toTagged<StreamOffset>(from), end - from);
+
+    invariant(page.ok, 'the log holds the cursor stream');
+
+    for (const stored of page.value.toReversed()) {
+      const entity = stored.fact.entity;
+      const cursor = stored.fact.cursor;
+
+      if (cursor !== undefined && wanted.has(entity) && !saved.has(entity)) {
+        saved.set(entity, cursor);
+      }
+    }
+
+    end = from;
+  }
+
+  return pulls.map((pull) => ({
+    ...pull,
+    cursor: saved.get(buildCursorEntity(pull.source, pull.path)) ?? null,
+  }));
+}

package/src/pull/make-pull-runner.ts

@@ -1,14 +1,19 @@
 import type { CheckedDeployment, Logger, PullPath, Pulled, SourceDefinition } from '@pepys/kit';
 import type { BatchAppender } from '../fact-log/make-batch-appender.ts';
-import { pickBatchPlan } from '../receive/pick-batch-plan.ts';
 import type { ResyncMarks } from '../receive/resync-marks/create-resync-marks.ts';
 import { writeBatch } from '../receive/write-batch.ts';
 import type { StreamTurns } from '../receive/write-batch.ts';
+import { pickBatchPlan } from '../utils/pick-batch-plan.ts';
+import { buildCursorRecord } from './cursors/build-cursor-record.ts';
+import { cursorStream } from './cursors/cursor-stream.ts';
+import { withSourceLock } from './with-source-lock.ts';
+import type { SourceLocks } from './with-source-lock.ts';
 
 export type PullPathName = 'live' | 'recovery' | 'backfill' | 'resync';
 
-// `stored`: the batch is in the log, and the next run starts from `cursor`. `not-stored`: an append
-// failed, so the next run starts from the same cursor. Any other answer is the pull's own.
+// `stored`: the batch and then the cursor record are in the log, and the next run starts from
+// `cursor`. `not-stored`: an append failed, so the next run starts from the same cursor. Any other
+// answer is the pull's own.
 export type PullRun =
   | { kind: 'stored'; stored: number; cursor: string; isDone: boolean }
   | { kind: 'not-stored' }
@@ -34,10 +39,12 @@ interface PullRunnerDependencies {
   logger: Logger;
 }
 
-// For a resync pull, removes each mark it was given that no tie set again since. A pull's fact is
-// noted in no mark: a resynced fact ties with the body it replaces, and would mark its entity again
-// on every run.
+// The pull paths of one source run one after the other, in the order they were asked for, and the
+// pull paths of two sources run at the same time. A run that waits for its source ends as refused
+// when its signal aborts, and its pull never starts.
 export function makePullRunner(dependencies: PullRunnerDependencies): PullRunner {
+  const locks: SourceLocks = new Map();
+
   return async (sourceName, pathName, cursor, signal) => {
     const source = dependencies.deployment.sources.find(
       (candidate) => candidate.name === sourceName,
@@ -49,54 +56,97 @@ export function makePullRunner(dependencies: PullRunnerDependencies): PullRunner
       return { kind: 'refused', reason: `the source ${sourceName} has no ${pathName} pull` };
     }
 
-    const marks = pathName === 'resync' ? dependencies.resyncMarks.list(source.name) : [];
-    const env: Record<string, string> = {};
+    const run = await withSourceLock(locks, source.name, signal, () =>
+      runPull(dependencies, { source, path, pathName, cursor, signal }),
+    );
 
-    for (const name of path.env ?? []) {
-      env[name] = dependencies.secrets[name] ?? '';
-    }
+    return run === 'stopped'
+      ? { kind: 'refused', reason: `the ${pathName} pull of ${sourceName} stopped before its turn` }
+      : run;
+  };
+}
 
-    const pulled = await path.pull(cursor, {
-      env,
-      marks,
-      now: dependencies.now,
-      log: dependencies.logger,
-      signal,
-    });
+function findPullPath(source: SourceDefinition, pathName: PullPathName): PullPath | undefined {
+  const path = source[pathName];
 
-    if (pulled.kind !== 'batch') {
-      return pulled;
-    }
+  return path?.kind === 'pull' ? path : undefined;
+}
 
-    const plan = pickBatchPlan(source, pulled.batch);
+interface PullRequest {
+  source: SourceDefinition;
+  path: PullPath;
+  pathName: PullPathName;
+  cursor: string | null;
+  signal: AbortSignal;
+}
 
-    if (!plan.ok) {
-      return { kind: 'refused', reason: plan.failure.reason };
-    }
+// For a resync pull, removes each mark it was given that no tie set again since. A pull's fact is
+// noted in no mark: a resynced fact ties with the body it replaces, and would mark its entity again
+// on every run.
+async function runPull(
+  dependencies: PullRunnerDependencies,
+  request: PullRequest,
+): Promise<PullRun> {
+  const source = request.source;
+  const marks = request.pathName === 'resync' ? dependencies.resyncMarks.list(source.name) : [];
+  const env: Record<string, string> = {};
+
+  for (const name of request.path.env ?? []) {
+    env[name] = dependencies.secrets[name] ?? '';
+  }
+
+  const pulled = await request.path.pull(request.cursor, {
+    env,
+    marks,
+    now: dependencies.now,
+    log: dependencies.logger,
+    signal: request.signal,
+  });
+
+  if (pulled.kind !== 'batch') {
+    return pulled;
+  }
+
+  const plan = pickBatchPlan(source, pulled.batch);
+
+  if (!plan.ok) {
+    return { kind: 'refused', reason: plan.failure.reason };
+  }
+
+  const outcome = await writeBatch(plan.value, dependencies);
+
+  if (outcome !== 'stored') {
+    return outcome === 'not-stored'
+      ? { kind: 'not-stored' }
+      : { kind: 'refused', reason: 'the log refused the batch' };
+  }
+
+  // A run that leaves the cursor where it was has nothing to save.
+  if (pulled.cursor !== request.cursor) {
+    const record = buildCursorRecord({
+      source: source.name,
+      path: request.pathName,
+      cursor: pulled.cursor,
+      nowMs: dependencies.now(),
+    });
 
-    const outcome = await writeBatch(plan.value, dependencies);
+    const saved = await writeBatch(new Map([[cursorStream, [[record]]]]), dependencies);
 
-    if (outcome !== 'stored') {
-      return outcome === 'not-stored'
+    if (saved !== 'stored') {
+      return saved === 'not-stored'
         ? { kind: 'not-stored' }
-        : { kind: 'refused', reason: 'the log refused the batch' };
+        : { kind: 'refused', reason: 'the log refused the cursor record' };
     }
+  }
 
-    for (const mark of marks) {
-      dependencies.resyncMarks.remove(source.name, mark);
-    }
+  for (const mark of marks) {
+    dependencies.resyncMarks.remove(source.name, mark);
+  }
 
-    return {
-      kind: 'stored',
-      stored: pulled.batch.facts.length,
-      cursor: pulled.cursor,
-      isDone: pulled.isDone,
-    };
+  return {
+    kind: 'stored',
+    stored: pulled.batch.facts.length,
+    cursor: pulled.cursor,
+    isDone: pulled.isDone,
   };
 }
-
-function findPullPath(source: SourceDefinition, pathName: PullPathName): PullPath | undefined {
-  const path = source[pathName];
-
-  return path?.kind === 'pull' ? path : undefined;
-}

package/src/pull/with-source-lock.ts

@@ -0,0 +1,76 @@
+// One chain of turns per source, for the whole process: the promise that settles when every run
+// that asked for the source's lock so far has ended.
+export type SourceLocks = Map<string, Promise<void>>;
+
+// Runs `work` once every earlier run of the source has ended, so the runs of one source go one
+// after the other in the order they asked. Returns `stopped`, and never calls `work`, when the
+// signal aborts before the turn comes.
+export async function withSourceLock<Value>(
+  locks: SourceLocks,
+  source: string,
+  signal: AbortSignal,
+  work: () => Promise<Value>,
+): Promise<Value | 'stopped'> {
+  const previous = locks.get(source) ?? Promise.resolve();
+  const done = Promise.withResolvers<void>();
+
+  // A run that stops while it waits ends early, and the runs behind it still wait for the runs
+  // ahead of it.
+  const turn = waitForBoth(previous, done.promise);
+
+  locks.set(source, turn);
+
+  try {
+    const waited = await waitForTurn(previous, signal);
+
+    return waited === 'stopped' ? 'stopped' : await work();
+  } finally {
+    done.resolve();
+
+    // A run that stops while it waits ends before the runs ahead of it, so the entry stays until
+    // those runs end too.
+    void removeEndedTurn(locks, source, turn);
+  }
+}
+
+async function waitForBoth(first: Promise<void>, second: Promise<void>): Promise<void> {
+  await first;
+  await second;
+}
+
+async function waitForTurn(
+  previous: Promise<void>,
+  signal: AbortSignal,
+): Promise<'turn' | 'stopped'> {
+  if (signal.aborted) {
+    return 'stopped';
+  }
+
+  const stopped = Promise.withResolvers<void>();
+
+  const stop = (): void => {
+    stopped.resolve();
+  };
+
+  signal.addEventListener('abort', stop);
+
+  try {
+    await Promise.race([previous, stopped.promise]);
+
+    return signal.aborted ? 'stopped' : 'turn';
+  } finally {
+    signal.removeEventListener('abort', stop);
+  }
+}
+
+async function removeEndedTurn(
+  locks: SourceLocks,
+  source: string,
+  turn: Promise<void>,
+): Promise<void> {
+  await turn;
+
+  if (locks.get(source) === turn) {
+    locks.delete(source);
+  }
+}

package/src/receive/answers/build-failure-answer.ts

@@ -3,7 +3,8 @@ export function buildFailureAnswer(status: number, reason: string): Response {
   return Response.json({ error: reason }, { status });
 }
 
-// 503 means "send the same delivery again, unchanged": every sender of v1 does that.
+// 503 means "send the same delivery again, unchanged". A sender that never sends a batch twice,
+// such as Codex's exporter, loses the batch.
 export function buildRetryAnswer(): Response {
   return Response.json(
     { error: 'the batch is not stored, send it again' },

package/src/receive/pick-received-step.ts

@@ -1,7 +1,7 @@
 import type { PendingFact, Received, SourceContext } from '@pepys/kit';
 import { match } from 'ts-pattern';
-import { pickBatchPlan } from './pick-batch-plan.ts';
-import type { BatchPlan } from './plan-batch.ts';
+import { pickBatchPlan } from '../utils/pick-batch-plan.ts';
+import type { BatchPlan } from '../utils/plan-batch.ts';
 
 // `has-blob`: the source read a fact with a blob, a fault of the deployment that ingest answers 500.
 export type ReceivedStep =

package/src/receive/write-batch.ts

@@ -1,6 +1,6 @@
 import type { Logger, StreamName } from '@pepys/kit';
 import type { BatchAppender } from '../fact-log/make-batch-appender.ts';
-import type { BatchPlan } from './plan-batch.ts';
+import type { BatchPlan } from '../utils/plan-batch.ts';
 
 export type BatchOutcome = 'stored' | 'refused' | 'not-stored';
 

package/src/serve/serve-ingest.ts

@@ -4,6 +4,10 @@ import { makeShutdownHandler } from '@pepys/schema';
 import { toTagged } from '@zgeoff/std';
 import { readIngestConfig } from '../config/read-ingest-config.ts';
 import { createS2FactLog } from '../fact-log/s2/create-s2-fact-log.ts';
+import { collectTimedPulls } from '../pull/collect-timed-pulls.ts';
+import { cursorStream } from '../pull/cursors/cursor-stream.ts';
+import { formatPullStart } from '../pull/cursors/format-pull-start.ts';
+import { readSavedCursors } from '../pull/cursors/read-saved-cursors.ts';
 import { createIngest } from '../receive/create-ingest.ts';
 import { readImpIdentitySenderProof } from '../sender-proof/imp-identity/read-imp-identity-sender-proof.ts';
 import { startPullTimers } from './start-pull-timers.ts';
@@ -51,10 +55,12 @@ export async function serveIngest(options: ServeIngestOptions): Promise<() => Pr
   // The S2 adapter creates the basin and each missing stream, so no setup command creates streams.
   const log = await createS2FactLog({
     ...config.value.s2,
-    streams: collectStreams(sources),
+    streams: [...collectStreams(sources), cursorStream],
     logger,
   });
 
+  const pulls = await readSavedCursors(log, collectTimedPulls(sources));
+
   const ingest = createIngest({
     deployment: checked.value,
     secrets: config.value.secrets,
@@ -76,7 +82,11 @@ export async function serveIngest(options: ServeIngestOptions): Promise<() => Pr
     fetch: ingest.handleRequest,
   });
 
-  const stopPulls = startPullTimers(sources, ingest.runPull, logger);
+  for (const pull of pulls) {
+    console.log(formatPullStart(pull));
+  }
+
+  const stopPulls = startPullTimers(pulls, ingest.runPull, logger);
 
   console.log(`ingest listening on ${server.hostname}:${server.port}`);
 

package/src/serve/start-pull-timers.ts

@@ -1,70 +1,59 @@
-import type { Logger, SourceDefinition } from '@pepys/kit';
+import type { Logger } from '@pepys/kit';
 import { match } from 'ts-pattern';
-import type { PullPathName, PullRun, PullRunner } from '../pull/make-pull-runner.ts';
+import type { ResumedPull } from '../pull/cursors/read-saved-cursors.ts';
+import type { PullRun, PullRunner } from '../pull/make-pull-runner.ts';
 
-const pullPathNames: readonly PullPathName[] = ['live', 'recovery', 'backfill', 'resync'];
-
-// One timer per pull path with an interval. The cursor lives in memory, so a restart starts each
-// pull from no cursor. A run never overlaps the one before it. Returns the function that stops them:
-// it aborts each run in flight and settles once every run has ended.
+// One timer per pull, whose first run starts from the pull's saved cursor. A timer starts no run
+// while its last one waits for its source or runs. Returns the function that stops the timers: it
+// aborts each run, waiting or in flight, and settles once every run has ended.
 export function startPullTimers(
-  sources: readonly SourceDefinition[],
+  pulls: readonly ResumedPull[],
   runPull: PullRunner,
   logger: Logger,
 ): () => Promise<void> {
   const controller = new AbortController();
   const activeRuns = new Set<Promise<void>>();
 
-  const timers = sources.flatMap((source) =>
-    pullPathNames.flatMap((pathName) => {
-      const path = source[pathName];
+  const timers = pulls.map((pull) => {
+    let cursor = pull.cursor;
+    let isRunning = false;
 
-      if (path?.kind !== 'pull' || path.intervalMs === null) {
-        return [];
+    const runOnce = async (): Promise<void> => {
+      if (isRunning || controller.signal.aborted) {
+        return;
       }
 
-      let cursor: string | null = null;
-      let isRunning = false;
-
-      const runOnce = async (): Promise<void> => {
-        if (isRunning || controller.signal.aborted) {
-          return;
-        }
-
-        isRunning = true;
+      isRunning = true;
 
-        const ended = Promise.withResolvers<void>();
+      const ended = Promise.withResolvers<void>();
 
-        activeRuns.add(ended.promise);
+      activeRuns.add(ended.promise);
 
-        try {
-          const run = await runPull(source.name, pathName, cursor, controller.signal);
+      try {
+        const run = await runPull(pull.source, pull.path, cursor, controller.signal);
 
-          cursor = pickNextCursor(run, cursor);
+        cursor = pickNextCursor(run, cursor);
 
-          // a run that the stop cut short is no failure
-          if (run.kind !== 'stored' && !controller.signal.aborted) {
-            logger.error(`the ${pathName} pull of ${source.name} did not store`, run);
-          }
-        } catch (error: unknown) {
-          if (!controller.signal.aborted) {
-            logger.error(`the ${pathName} pull of ${source.name} threw`, error);
-          }
-        } finally {
-          isRunning = false;
-
-          activeRuns.delete(ended.promise);
-          ended.resolve();
+        // a run that the stop cut short is no failure
+        if (run.kind !== 'stored' && !controller.signal.aborted) {
+          logger.error(`the ${pull.path} pull of ${pull.source} did not store`, run);
+        }
+      } catch (error: unknown) {
+        if (!controller.signal.aborted) {
+          logger.error(`the ${pull.path} pull of ${pull.source} threw`, error);
         }
-      };
+      } finally {
+        isRunning = false;
+
+        activeRuns.delete(ended.promise);
+        ended.resolve();
+      }
+    };
 
-      return [
-        setInterval(() => {
-          void runOnce();
-        }, path.intervalMs),
-      ];
-    }),
-  );
+    return setInterval(() => {
+      void runOnce();
+    }, pull.intervalMs);
+  });
 
   return async () => {
     for (const timer of timers) {

package/src/{receive → utils}/plan-batch.ts

@@ -1,5 +1,5 @@
 import type { Batch, FactEnvelope, Result, StreamName } from '@pepys/kit';
-import { planAppends } from '../fact-log/plan-appends.ts';
+import { planAppends } from './plan-appends.ts';
 
 export type BatchPlan = ReadonlyMap<StreamName, readonly (readonly FactEnvelope<unknown>[])[]>;