@boxxy/dispatch 0.1.0 → 0.1.3

package/src/test-utils/create-fake-forge.ts

@@ -0,0 +1,117 @@
+import type { Forge, PullRequestReading, PullRequestRef, RepoName } from '@boxxy/model';
+
+// A pull request as a test puts it on a forge. The url is the one GitHub gives.
+export interface SeededPullRequest {
+  readonly ref: PullRequestRef;
+  readonly githubId: number;
+  readonly reading: Omit<PullRequestReading, 'githubId' | 'url'>;
+}
+
+export interface ReadHold {
+  readonly entered: Promise<void>;
+  readonly release: () => void;
+}
+
+export interface FakeForge extends Forge {
+  // every call, in order
+  readonly calls: readonly string[];
+  seed: (pullRequest: SeededPullRequest) => void;
+
+  // while down, every call rejects, as a forge that does not answer
+  setDown: (isDown: boolean) => void;
+
+  // the next `readPullRequest` waits until the test calls `release`; `entered` resolves once that
+  // read has started, so a test can change the store while the read is in flight
+  holdNextRead: () => ReadHold;
+}
+
+// A forge that keeps the pull requests a test seeds and answers as the `Forge` contract says.
+export function createFakeForge(): FakeForge {
+  const pullRequests = new Map<string, SeededPullRequest>();
+
+  const calls: string[] = [];
+  let isDown = false;
+  let hold: { readonly entered: () => void; readonly released: Promise<void> } | null = null;
+
+  const answerRead = (ref: PullRequestRef): Promise<PullRequestReading | 'not-found'> => {
+    if (isDown) {
+      return Promise.reject(new Error('the fake forge is down'));
+    }
+
+    const found = pullRequests.get(toKey(ref));
+
+    if (found === undefined) {
+      return Promise.resolve('not-found');
+    }
+
+    return Promise.resolve({
+      ...found.reading,
+      githubId: found.githubId,
+      url: `https://github.com/${ref.repo}/pull/${ref.number}`,
+    });
+  };
+
+  return {
+    calls,
+    seed: (pullRequest) => {
+      pullRequests.set(toKey(pullRequest.ref), pullRequest);
+    },
+    setDown: (down) => {
+      isDown = down;
+    },
+    holdNextRead: () => {
+      const entered = Promise.withResolvers<undefined>();
+      const released = Promise.withResolvers<undefined>();
+
+      hold = {
+        entered: () => {
+          entered.resolve(undefined);
+        },
+        released: released.promise,
+      };
+
+      return {
+        entered: entered.promise,
+        release: () => {
+          released.resolve(undefined);
+        },
+      };
+    },
+    readPullRequest: async (ref) => {
+      calls.push(`readPullRequest ${toKey(ref)}`);
+
+      const held = hold;
+
+      hold = null;
+
+      if (held !== null) {
+        held.entered();
+
+        await held.released;
+      }
+
+      return answerRead(ref);
+    },
+    listOpenPullRequests: (repo: RepoName) => {
+      calls.push(`listOpenPullRequests ${repo}`);
+
+      if (isDown) {
+        return Promise.reject(new Error('the fake forge is down'));
+      }
+
+      const open = [...pullRequests.values()].filter(
+        (pullRequest) => pullRequest.ref.repo === repo && pullRequest.reading.state === 'open',
+      );
+
+      return Promise.resolve(
+        open
+          .map((pullRequest) => pullRequest.ref)
+          .toSorted((first, second) => first.number - second.number),
+      );
+    },
+  };
+}
+
+function toKey(ref: PullRequestRef): string {
+  return `${ref.repo}#${ref.number}`;
+}

package/src/test-utils/create-fake-worker.ts

@@ -0,0 +1,303 @@
+import type {
+  AgentSessionId,
+  AtcSessionId,
+  AttemptId,
+  AttemptRow,
+  Attention,
+  Clock,
+  Instant,
+  SessionReading,
+  StartOutcome,
+  WorkerKind,
+} from '@boxxy/model';
+import { brandSchemas } from '@boxxy/model';
+import { match } from 'ts-pattern';
+
+type FailableMethod = 'start' | 'suspend' | 'resume' | 'stop' | 'forget' | 'resumeKept';
+
+export type FakeFailure =
+  | { readonly kind: 'refused'; readonly cause: 'capacity' | 'other'; readonly reason: string }
+  | { readonly kind: 'unknown'; readonly reason: string };
+
+// What a test sets a session to. A field left out keeps the session's value.
+export type FakeSession =
+  | {
+      readonly state: 'running';
+      readonly attention?: Attention;
+      readonly lastActivityAt?: Instant;
+      readonly lastOwnerAt?: Instant;
+      readonly agentSession?: AgentSessionId | null;
+      readonly usageLimitResetsAt?: Instant | null;
+    }
+  | {
+      readonly state: 'suspended';
+      readonly asked?: boolean;
+      readonly agentSession?: AgentSessionId | null;
+    }
+  | { readonly state: 'ended'; readonly agentSession?: AgentSessionId | null }
+  | { readonly state: 'absent' };
+
+export interface FakeWorkerCall {
+  readonly method: keyof WorkerKind;
+
+  // the attempt the call was for, or the forgotten session
+  readonly subject: string;
+}
+
+export interface FakeWorker extends WorkerKind {
+  readonly calls: readonly FakeWorkerCall[];
+
+  // the session that the worker gave the attempt, or that its spawn name finds
+  setSession: (attempt: AttemptId, session: FakeSession) => void;
+  failNext: (method: FailableMethod, failure: FakeFailure) => void;
+  failAlways: (method: FailableMethod, failure: FakeFailure) => void;
+}
+
+interface Session {
+  id: AtcSessionId;
+  state: 'running' | 'suspended' | 'ended';
+  attention: Attention;
+  lastActivityAt: Instant;
+  lastOwnerAt: Instant;
+  agentSession: AgentSessionId | null;
+  usageLimitResetsAt: Instant | null;
+  asked: boolean;
+}
+
+// A worker host in memory. A started session runs and works, a stop suspends it as an imp
+// target does, and every session gives the caller `fake-worker` with its own ID, as a host's
+// issuer name and a machine ID.
+interface FakeWorkerInput {
+  readonly clock: Clock;
+}
+
+export function createFakeWorker(input: FakeWorkerInput): FakeWorker {
+  const sessions = new Map<AtcSessionId, Session>();
+  const byAttempt = new Map<AttemptId, AtcSessionId>();
+
+  const calls: FakeWorkerCall[] = [];
+
+  const once = new Map<FailableMethod, FakeFailure>();
+  const always = new Map<FailableMethod, FakeFailure>();
+
+  let count = 0;
+
+  const takeFailure = (method: FailableMethod): FakeFailure | null => {
+    const failure = once.get(method) ?? always.get(method) ?? null;
+
+    once.delete(method);
+
+    return failure;
+  };
+
+  const findSession = (attempt: AttemptRow): Session | null => {
+    const id = attempt.atcSession ?? byAttempt.get(attempt.id) ?? null;
+
+    return id === null ? null : (sessions.get(id) ?? null);
+  };
+
+  const createSession = (): Session => {
+    count += 1;
+
+    const session: Session = {
+      id: brandSchemas.atcSessionId.parse(`atc-${count}`),
+      state: 'running',
+      attention: 'working',
+      lastActivityAt: input.clock.now(),
+      lastOwnerAt: input.clock.now(),
+      agentSession: brandSchemas.agentSessionId.parse(`agent-${count}`),
+      usageLimitResetsAt: null,
+      asked: false,
+    };
+
+    sessions.set(session.id, session);
+
+    return session;
+  };
+
+  const runSession = (session: Session): StartOutcome => {
+    Object.assign(session, {
+      state: 'running',
+      attention: 'working',
+      lastActivityAt: input.clock.now(),
+    });
+
+    return {
+      kind: 'started',
+      atcSession: session.id,
+      agentSession: session.agentSession,
+      caller: { issuer: 'fake-worker', subject: session.id },
+    };
+  };
+
+  return {
+    calls,
+    start: (request) => {
+      calls.push({ method: 'start', subject: request.idempotencyKey });
+
+      const failure = takeFailure('start');
+
+      if (failure !== null) {
+        return Promise.resolve(failure);
+      }
+
+      const known = byAttempt.get(request.idempotencyKey);
+      const session = (known === undefined ? null : sessions.get(known)) ?? createSession();
+
+      byAttempt.set(request.idempotencyKey, session.id);
+
+      return Promise.resolve(runSession(session));
+    },
+    reconcile: (attempt) => {
+      calls.push({ method: 'reconcile', subject: attempt.id });
+
+      return Promise.resolve(toReading(findSession(attempt)));
+    },
+    suspend: (attempt, ifIdleSince) => {
+      calls.push({ method: 'suspend', subject: attempt.id });
+
+      const failure = takeFailure('suspend');
+      const session = findSession(attempt);
+
+      if (failure !== null) {
+        return Promise.resolve({ kind: failure.kind, reason: failure.reason });
+      }
+
+      if (session === null) {
+        return Promise.resolve({ kind: 'refused', reason: 'no such session' });
+      }
+
+      if (ifIdleSince !== null && session.lastActivityAt > ifIdleSince) {
+        return Promise.resolve({ kind: 'active' });
+      }
+
+      Object.assign(session, { state: 'suspended', asked: true });
+
+      return Promise.resolve({ kind: 'suspended' });
+    },
+    resume: (attempt) => {
+      calls.push({ method: 'resume', subject: attempt.id });
+
+      const failure = takeFailure('resume');
+      const session = findSession(attempt);
+
+      if (failure !== null) {
+        return Promise.resolve(failure);
+      }
+
+      const outcome: StartOutcome =
+        session === null
+          ? { kind: 'refused', cause: 'other', reason: 'no such session' }
+          : runSession(session);
+
+      return Promise.resolve(outcome);
+    },
+    stop: (attempt) => {
+      calls.push({ method: 'stop', subject: attempt.id });
+
+      const failure = takeFailure('stop');
+      const session = findSession(attempt);
+
+      if (failure !== null) {
+        return Promise.resolve({ kind: failure.kind, reason: failure.reason });
+      }
+
+      if (session === null) {
+        return Promise.resolve({ kind: 'absent' });
+      }
+
+      if (session.state === 'running') {
+        Object.assign(session, { state: 'suspended', asked: true });
+      }
+
+      return Promise.resolve({ kind: 'stopped' });
+    },
+    forget: (id) => {
+      calls.push({ method: 'forget', subject: id });
+
+      const failure = takeFailure('forget');
+
+      if (failure !== null) {
+        return Promise.resolve({ kind: failure.kind, reason: failure.reason });
+      }
+
+      return Promise.resolve({ kind: sessions.delete(id) ? 'forgotten' : 'absent' });
+    },
+    resumeKept: (kept, request) => {
+      calls.push({ method: 'resumeKept', subject: request.idempotencyKey });
+
+      const failure = takeFailure('resumeKept');
+      const session = sessions.get(kept.atcSession) ?? null;
+
+      if (failure !== null) {
+        return Promise.resolve(failure);
+      }
+
+      if (session === null) {
+        return Promise.resolve({ kind: 'refused', cause: 'other', reason: 'no such session' });
+      }
+
+      byAttempt.set(request.idempotencyKey, session.id);
+
+      return Promise.resolve(runSession(session));
+    },
+    setSession: (attempt, update) => {
+      const id = byAttempt.get(attempt);
+      const session = (id === undefined ? null : sessions.get(id)) ?? createSession();
+
+      byAttempt.set(attempt, session.id);
+
+      match(update)
+        .with({ state: 'absent' }, () => {
+          sessions.delete(session.id);
+        })
+        .with({ state: 'running' }, (running) => {
+          Object.assign(session, { ...running, state: 'running' });
+        })
+        .with({ state: 'suspended' }, (suspended) => {
+          Object.assign(session, { asked: false, ...suspended, state: 'suspended' });
+        })
+        .with({ state: 'ended' }, (ended) => {
+          Object.assign(session, { ...ended, state: 'ended' });
+        })
+        .exhaustive();
+    },
+    failNext: (method, failure) => {
+      once.set(method, failure);
+    },
+    failAlways: (method, failure) => {
+      always.set(method, failure);
+    },
+  };
+}
+
+function toReading(session: Session | null): SessionReading {
+  if (session === null) {
+    return { kind: 'absent' };
+  }
+
+  return match(session.state)
+    .returnType<SessionReading>()
+    .with('running', () => ({
+      kind: 'running',
+      atcSession: session.id,
+      agentSession: session.agentSession,
+      caller: { issuer: 'fake-worker', subject: session.id },
+      attention: session.attention,
+      lastActivityAt: session.lastActivityAt,
+      lastOwnerAt: session.lastOwnerAt,
+      usageLimitResetsAt: session.usageLimitResetsAt,
+    }))
+    .with('suspended', () => ({
+      kind: 'suspended',
+      atcSession: session.id,
+      agentSession: session.agentSession,
+      asked: session.asked,
+    }))
+    .with('ended', () => ({
+      kind: 'ended',
+      atcSession: session.id,
+      agentSession: session.agentSession,
+    }))
+    .exhaustive();
+}

package/src/test-utils/create-memory-claim-store.ts

@@ -0,0 +1,163 @@
+import { collectSeatSync } from '@boxxy/model';
+import type { StoreTx } from '@boxxy/model';
+import { applyMemoryChange } from './apply-memory-change.ts';
+import { buildMemoryReader } from './build-memory-reader.ts';
+import { isSameHeldSeat } from './is-same-held-seat.ts';
+import type { ClosableClaimStore, MemoryTables } from './types.ts';
+
+export function createMemoryClaimStore(): ClosableClaimStore {
+  let committed = buildEmptyTables();
+  let turn: Promise<void> = Promise.resolve();
+  let isClosed = false;
+  let reads: Promise<unknown> = Promise.resolve();
+
+  return {
+    exclusive: async (work) => {
+      if (isClosed) {
+        throw new Error('the store is closed');
+      }
+
+      const previous = turn;
+      const next = Promise.withResolvers<void>();
+
+      turn = next.promise;
+
+      await previous;
+
+      try {
+        const draft = structuredClone(committed);
+
+        const result = await work(buildMemoryTx(draft));
+
+        committed = draft;
+
+        return result;
+      } finally {
+        next.resolve();
+      }
+    },
+    read: (work) => {
+      const snapshot = committed;
+
+      const reading = Promise.try(() => {
+        if (isClosed) {
+          throw new Error('the store is closed');
+        }
+
+        return work(buildMemoryReader(() => snapshot));
+      });
+
+      reads = Promise.allSettled([reads, reading]);
+
+      return reading;
+    },
+    close: async () => {
+      isClosed = true;
+
+      await Promise.all([reads, turn]);
+    },
+  };
+}
+
+function buildEmptyTables(): MemoryTables {
+  return {
+    items: [],
+    relations: [],
+    levers: [],
+    attempts: [],
+    attempt_sessions: [],
+    leases: [],
+    decisions: [],
+    evidence: [],
+    pull_requests: [],
+    runners: [],
+    notes: [],
+    notices: [],
+    outbox: [],
+    limits: [],
+    limit_seats: [],
+  };
+}
+
+function buildMemoryTx(tables: MemoryTables): StoreTx {
+  return {
+    ...buildMemoryReader(() => tables),
+    applyChange: (change) => Promise.try(() => applyMemoryChange(tables, change)),
+    markFactsSent: (ids, at) => {
+      for (const fact of tables.outbox) {
+        if (ids.includes(fact.factId) && fact.sentAt === null && fact.parkedAt === null) {
+          Object.assign(fact, { sentAt: at });
+        }
+      }
+
+      return Promise.resolve();
+    },
+    parkFacts: (ids, reason, at) => {
+      for (const fact of tables.outbox) {
+        if (ids.includes(fact.factId) && fact.sentAt === null) {
+          Object.assign(fact, { parkedAt: at, parkedReason: reason });
+        }
+      }
+
+      return Promise.resolve();
+    },
+    unparkFacts: () => {
+      const parked = tables.outbox.filter((fact) => fact.sentAt === null && fact.parkedAt !== null);
+
+      for (const fact of parked) {
+        Object.assign(fact, { parkedAt: null, parkedReason: null });
+      }
+
+      return Promise.resolve(parked.length);
+    },
+    writeHeartbeat: (runner, at) => {
+      const row = tables.runners.find((candidate) => candidate.id === runner);
+
+      if (row === undefined) {
+        tables.runners.push({ id: runner, heartbeatAt: at, paused: false });
+      } else {
+        Object.assign(row, { heartbeatAt: at });
+      }
+
+      return Promise.resolve();
+    },
+    syncLimits: (limits, at) => {
+      const sync = collectSeatSync({
+        limits,
+        held: tables.limit_seats.filter((seat) => seat.releasedAt === null),
+        attempts: tables.attempts,
+        at,
+      });
+
+      tables.limits = structuredClone([...limits]);
+
+      for (const seat of tables.limit_seats) {
+        if (sync.release.some((released) => isSameHeldSeat(released, seat))) {
+          Object.assign(seat, { releasedAt: at });
+        }
+      }
+
+      tables.limit_seats.push(...structuredClone([...sync.take]));
+
+      return Promise.resolve();
+    },
+    markPullRequestChecked: (ref, at) => {
+      for (const row of tables.pull_requests) {
+        if (row.repo === ref.repo && row.number === ref.number) {
+          Object.assign(row, { checkedAt: at });
+        }
+      }
+
+      return Promise.resolve();
+    },
+    markNoticeTried: (id, at, sent) => {
+      const row = tables.notices.find((candidate) => candidate.id === id);
+
+      if (row !== undefined) {
+        Object.assign(row, { tries: row.tries + 1, sentAt: sent ? at : row.sentAt });
+      }
+
+      return Promise.resolve();
+    },
+  };
+}