@pepys/ingest 0.3.1 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pepys/ingest",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "pepys ingest: the receive routes, the fact log and the blob store",
   "license": "MIT",
   "repository": {
@@ -22,8 +22,8 @@
   },
   "dependencies": {
     "@impz/client": "6.12.0",
-    "@pepys/kit": "0.3.1",
-    "@pepys/schema": "0.3.1",
+    "@pepys/kit": "0.4.1",
+    "@pepys/schema": "0.4.1",
     "@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,11 +1,14 @@
-import type { FactEnvelope, Result, StreamName, StreamOffset } from '@pepys/kit';
-import { toTagged } from '@zgeoff/std';
-import { P, match } from 'ts-pattern';
-import type { FactLog, StoredFact } from './fact-log.ts';
-import { pickSettlement } from './pick-settlement.ts';
+import type { FactEnvelope, Logger, Result, StreamName, StreamOffset } from '@pepys/kit';
+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;
+  logger: Logger;
   maxAttempts: number;
   retryDelayMs: number;
 }
@@ -31,100 +34,59 @@ export function makeBatchAppender(options: BatchAppenderOptions): BatchAppender
     for (let attempt = 1; ; attempt += 1) {
       const result = await runAttempt(options, stream, facts, pendingTail);
 
-      if (result.kind === 'stored') {
-        return { ok: true, value: result.stored };
-      }
+      const step = pickRetryStep(result, attempt, options);
 
-      if (result.kind === 'refused') {
-        return { ok: false, failure: result.failure };
+      if (step.kind === 'answer') {
+        return step.answer;
       }
 
-      pendingTail = result.pendingTail;
-
-      if (attempt >= options.maxAttempts) {
-        return { ok: false, failure: { kind: 'not-stored', attempts: attempt } };
-      }
+      pendingTail = step.pendingTail;
 
-      await Bun.sleep(options.retryDelayMs * attempt);
+      await Bun.sleep(step.delayMs);
     }
   };
 }
 
-interface Stored {
-  firstOffset: StreamOffset;
-  count: number;
-}
-
-type StopFailure = Extract<AppendFailure, { kind: 'refused' }>;
-
-// What one attempt leaves: the answer, or the tail that earlier attempts with an unknown outcome
-// aimed at, which a later attempt can still land on. `null` when no such attempt is open.
-type AttemptResult =
-  | { kind: 'stored'; stored: Stored }
-  | { kind: 'refused'; failure: StopFailure }
-  | { kind: 'again'; pendingTail: StreamOffset | null };
-
+// Every attempt that is still open aimed at the same tail: a new tail comes only after the offsets
+// there are known to hold another writer's records.
 async function runAttempt(
-  options: BatchAppenderOptions,
+  options: Pick<BatchAppenderOptions, 'log' | 'logger'>,
   stream: StreamName,
   facts: readonly FactEnvelope<unknown>[],
   pendingTail: StreamOffset | null,
 ): Promise<AttemptResult> {
-  // Every attempt that is still open aimed at the same tail: a new tail comes only after the
-  // offsets there are known to hold another writer's records.
-  const read =
+  const aim =
     pendingTail === null
-      ? await readTail(options.log, stream)
-      : { ok: true as const, value: pendingTail };
+      ? await readAimedTail(options, stream)
+      : { kind: 'aim' as const, tail: pendingTail };
 
-  if (read === null) {
-    return { kind: 'again', pendingTail };
+  if (aim.kind !== 'aim') {
+    return aim;
   }
 
-  if (!read.ok) {
-    return { kind: 'refused', failure: read.failure };
-  }
+  const outcome = await options.log.appendBatch(stream, facts, aim.tail);
+
+  const step = pickAttemptStep(outcome, aim.tail, pendingTail);
 
-  const aimed = read.value;
-
-  const outcome = await options.log.appendBatch(stream, facts, aimed);
-
-  return match(outcome)
-    .with({ kind: 'acknowledged' }, (acknowledged) => ({
-      kind: 'stored' as const,
-      stored: { firstOffset: acknowledged.firstOffset, count: acknowledged.count },
-    }))
-    .with({ kind: 'rejected', reason: 'tail-mismatch' }, () =>
-      pendingTail === null
-        ? { kind: 'again' as const, pendingTail }
-        : settleAttempt(options, stream, facts, aimed),
-    )
-    .with(
-      { kind: 'rejected', reason: P.union('unknown-stream', 'invalid-envelope', 'too-large') },
-      (rejected) => ({
-        kind: 'refused' as const,
-        failure: { kind: 'refused' as const, reason: rejected.reason },
-      }),
-    )
-    .with({ kind: 'unknown' }, () => settleAttempt(options, stream, facts, aimed))
-    .exhaustive();
+  return step.kind === 'settle' ? settleAttempt(options, stream, facts, step.tail) : step;
 }
 
-// A failed read stored nothing, so the next attempt repeats it. Returns `null` for a failed read,
-// and the failure for a stream the log lacks. An error the append throws is a refusal the log gives
-// no outcome for, such as a bad token, and a retry cannot change it.
-async function readTail(
-  log: FactLog,
+// A failed read stored nothing, so the next attempt repeats it. An error the append throws is a
+// refusal the log gives no outcome for, such as a bad token, and a retry cannot change it.
+async function readAimedTail(
+  options: Pick<BatchAppenderOptions, 'log' | 'logger'>,
   stream: StreamName,
-): Promise<Result<StreamOffset, StopFailure> | null> {
+): Promise<{ kind: 'aim'; tail: StreamOffset } | AttemptResult> {
   try {
-    const tail = await log.readTail(stream);
+    const tail = await options.log.readTail(stream);
 
-    return tail.ok ? tail : { ok: false, failure: { kind: 'refused', reason: 'unknown-stream' } };
+    return tail.ok
+      ? { kind: 'aim', tail: tail.value }
+      : { kind: 'refused', failure: { kind: 'refused', reason: 'unknown-stream' } };
   } catch (error: unknown) {
-    console.error('a read before an append failed', error);
+    options.logger.error('a read before an append failed', error);
 
-    return null;
+    return { kind: 'again', pendingTail: null };
   }
 }
 
@@ -132,67 +94,20 @@ async function readTail(
 // with the run's, in order. A search for the first ID anywhere after the tail would take another
 // writer's copy of it for the whole run.
 async function settleAttempt(
-  options: BatchAppenderOptions,
+  options: Pick<BatchAppenderOptions, 'log' | 'logger'>,
   stream: StreamName,
   facts: readonly FactEnvelope<unknown>[],
   tail: StreamOffset,
 ): Promise<AttemptResult> {
   const stored = await readRun(options.log, stream, tail, facts.length).catch((error: unknown) => {
-    console.error('a read that settles an append failed', error);
+    options.logger.error('a read that settles an append failed', error);
 
     return null;
   });
 
-  if (stored === null) {
-    return { kind: 'again', pendingTail: tail };
-  }
-
-  if (!stored.ok) {
-    return { kind: 'refused', failure: { kind: 'refused', reason: 'unknown-stream' } };
-  }
-
-  return match(
-    pickSettlement(
-      facts.map((fact) => fact.id),
-      stored.value,
-    ),
-  )
-    .with('landed', () => ({
-      kind: 'stored' as const,
-      stored: { firstOffset: tail, count: facts.length },
-    }))
-    .with('not-landed', () => ({ kind: 'again' as const, pendingTail: tail }))
-    .with('taken', () => ({ kind: 'again' as const, pendingTail: null }))
-    .exhaustive();
-}
-
-// 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 };
+  return pickSettledAttempt(
+    stored,
+    facts.map((fact) => fact.id),
+    tail,
+  );
 }

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/pick-attempt-step.ts

@@ -0,0 +1,53 @@
+import type { StreamOffset } from '@pepys/kit';
+import { P, match } from 'ts-pattern';
+import type { AppendBatchOutcome } from './fact-log.ts';
+
+export interface StoredRun {
+  firstOffset: StreamOffset;
+  count: number;
+}
+
+// a reason the log gives that no retry changes
+export interface StopFailure {
+  kind: 'refused';
+  reason: 'unknown-stream' | 'invalid-envelope' | 'too-large';
+}
+
+// What one attempt leaves: the answer, or the tail that earlier attempts with an unknown outcome
+// aimed at, which a later attempt can still land on. `null` when no such attempt is open.
+export type AttemptResult =
+  | { kind: 'stored'; stored: StoredRun }
+  | { kind: 'refused'; failure: StopFailure }
+  | { kind: 'again'; pendingTail: StreamOffset | null };
+
+// `settle`: read the offsets from `tail` to learn whether the run is there.
+export type AttemptStep = AttemptResult | { kind: 'settle'; tail: StreamOffset };
+
+// What follows an append that aimed at `aimed`. A tail mismatch with no attempt open means another
+// writer moved the tail, so the next attempt reads it again. With an attempt open, the mismatch may
+// be that attempt landing late, so the offsets it aimed at are read.
+export function pickAttemptStep(
+  outcome: AppendBatchOutcome,
+  aimed: StreamOffset,
+  pendingTail: StreamOffset | null,
+): AttemptStep {
+  return match(outcome)
+    .with({ kind: 'acknowledged' }, (acknowledged) => ({
+      kind: 'stored' as const,
+      stored: { firstOffset: acknowledged.firstOffset, count: acknowledged.count },
+    }))
+    .with({ kind: 'rejected', reason: 'tail-mismatch' }, () =>
+      pendingTail === null
+        ? { kind: 'again' as const, pendingTail }
+        : { kind: 'settle' as const, tail: aimed },
+    )
+    .with(
+      { kind: 'rejected', reason: P.union('unknown-stream', 'invalid-envelope', 'too-large') },
+      (rejected) => ({
+        kind: 'refused' as const,
+        failure: { kind: 'refused' as const, reason: rejected.reason },
+      }),
+    )
+    .with({ kind: 'unknown' }, () => ({ kind: 'settle' as const, tail: aimed }))
+    .exhaustive();
+}

package/src/fact-log/pick-retry-step.ts

@@ -0,0 +1,47 @@
+import type { Result, StreamOffset } from '@pepys/kit';
+import { match } from 'ts-pattern';
+import type { AttemptResult, StopFailure, StoredRun } from './pick-attempt-step.ts';
+
+interface RetryLimits {
+  maxAttempts: number;
+  retryDelayMs: number;
+}
+
+export type RetryStep =
+  | {
+      kind: 'answer';
+      answer: Result<StoredRun, StopFailure | { kind: 'not-stored'; attempts: number }>;
+    }
+  | { kind: 'retry'; pendingTail: StreamOffset | null; delayMs: number };
+
+// The wait before attempt `attempt + 1` grows by `retryDelayMs` with each attempt.
+export function pickRetryStep(
+  result: AttemptResult,
+  attempt: number,
+  limits: RetryLimits,
+): RetryStep {
+  return match(result)
+    .with({ kind: 'stored' }, (stored) => ({
+      kind: 'answer' as const,
+      answer: { ok: true as const, value: stored.stored },
+    }))
+    .with({ kind: 'refused' }, (refused) => ({
+      kind: 'answer' as const,
+      answer: { ok: false as const, failure: refused.failure },
+    }))
+    .with({ kind: 'again' }, (again): RetryStep => {
+      if (attempt >= limits.maxAttempts) {
+        return {
+          kind: 'answer',
+          answer: { ok: false, failure: { kind: 'not-stored', attempts: attempt } },
+        };
+      }
+
+      return {
+        kind: 'retry',
+        pendingTail: again.pendingTail,
+        delayMs: limits.retryDelayMs * attempt,
+      };
+    })
+    .exhaustive();
+}

package/src/fact-log/pick-settled-attempt.ts

@@ -0,0 +1,30 @@
+import type { FactID, Result, StreamOffset } from '@pepys/kit';
+import { match } from 'ts-pattern';
+import type { StoredFact } from './fact-log.ts';
+import type { AttemptResult } from './pick-attempt-step.ts';
+import { pickSettlement } from './pick-settlement.ts';
+
+// `stored` is the read of the offsets `[tail, tail + n)` that an attempt aimed at, or `null` when
+// the read failed, which leaves the attempt open.
+export function pickSettledAttempt(
+  stored: Result<readonly StoredFact[], { reason: 'unknown-stream' }> | null,
+  ids: readonly FactID[],
+  tail: StreamOffset,
+): AttemptResult {
+  if (stored === null) {
+    return { kind: 'again', pendingTail: tail };
+  }
+
+  if (!stored.ok) {
+    return { kind: 'refused', failure: { kind: 'refused', reason: 'unknown-stream' } };
+  }
+
+  return match(pickSettlement(ids, stored.value))
+    .with('landed', () => ({
+      kind: 'stored' as const,
+      stored: { firstOffset: tail, count: ids.length },
+    }))
+    .with('not-landed', () => ({ kind: 'again' as const, pendingTail: tail }))
+    .with('taken', () => ({ kind: 'again' as const, pendingTail: null }))
+    .exhaustive();
+}

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

@@ -1,4 +1,5 @@
-import type { FactEnvelope, Result, StreamName, StreamOffset } from '@pepys/kit';
+import { createLogger } from '@pepys/kit';
+import type { FactEnvelope, Logger, Result, StreamName, StreamOffset } from '@pepys/kit';
 import {
   AppendInput,
   AppendRecord,
@@ -8,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';
@@ -18,6 +19,9 @@ interface S2FactLogParameters {
   accessToken: string;
   basin: string;
   streams: readonly StreamName[];
+
+  // defaults to a logger that writes to stderr
+  logger?: Logger | undefined;
 }
 
 // Creates the basin and the streams when they are missing. A stream that exists keeps its records
@@ -29,6 +33,8 @@ export async function createS2FactLog(parameters: S2FactLogParameters): Promise<
     requestTimeoutMillis: 5000,
   };
 
+  const logger = parameters.logger ?? createLogger(process.stderr);
+
   const client = new S2(options);
 
   // A client retry could store a record twice before the writer knows; the writer owns retries.
@@ -45,7 +51,7 @@ export async function createS2FactLog(parameters: S2FactLogParameters): Promise<
 
   return {
     appendBatch: (stream, facts, expectedTail) =>
-      appendBatch(appendBasin, stream, facts, expectedTail),
+      appendBatch({ basin: appendBasin, logger }, stream, facts, expectedTail),
     read: (stream, from, count) => readFacts(basin, stream, from, count),
     readTail: (stream) => readTail(basin, stream),
   };
@@ -78,8 +84,13 @@ async function createInfiniteStream(basin: S2Basin, stream: StreamName): Promise
   }
 }
 
+interface S2Writer {
+  basin: S2Basin;
+  logger: Logger;
+}
+
 async function appendBatch(
-  basin: S2Basin,
+  writer: S2Writer,
   stream: StreamName,
   facts: readonly FactEnvelope<unknown>[],
   expectedTail: StreamOffset,
@@ -97,7 +108,7 @@ async function appendBatch(
   );
 
   try {
-    const ack = await basin.stream(stream).append(input);
+    const ack = await writer.basin.stream(stream).append(input);
 
     return {
       kind: 'acknowledged',
@@ -112,7 +123,7 @@ async function appendBatch(
     }
 
     if (outcome.kind === 'unknown') {
-      console.error('an s2 append has an unknown outcome', error);
+      writer.logger.error('an s2 append has an unknown outcome', error);
     }
 
     return outcome;

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';
@@ -20,4 +21,3 @@ export { readImpIdentityTrust } from './sender-proof/imp-identity/read-imp-ident
 export type { ImpIdentityTrust } from './sender-proof/imp-identity/types.ts';
 export { noSenderProof } from './sender-proof/none/no-sender-proof.ts';
 export { serveIngest } from './serve/serve-ingest.ts';
-export type * from './source-port/types.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,
+  }));
+}