@boxxy/dispatch 0.1.0 → 0.1.3

package/src/test-utils/apply-memory-change.ts

@@ -0,0 +1,252 @@
+import { isDeepStrictEqual } from 'node:util';
+import { buildAppliedChange, parseNewFact, pickSeatTake, toJSONValue } from '@boxxy/model';
+import type {
+  ApplyResult,
+  Instant,
+  RowWrite,
+  SeatRelease,
+  SeatTake,
+  StoreChange,
+  TableName,
+} from '@boxxy/model';
+import { match } from 'ts-pattern';
+import { collectMemoryLimitFills } from './collect-memory-limit-fills.ts';
+import { isSameHeldSeat } from './is-same-held-seat.ts';
+import type { MemoryTables } from './types.ts';
+
+// all or none: a refusal or a throw puts every table back as it was
+export function applyMemoryChange(tables: MemoryTables, change: StoreChange): ApplyResult {
+  const before = structuredClone(tables);
+
+  try {
+    const result = writeMemoryChange(tables, change);
+
+    if (result.kind !== 'applied') {
+      Object.assign(tables, before);
+    }
+
+    return result;
+  } catch (error) {
+    Object.assign(tables, before);
+    throw error;
+  }
+}
+
+function writeMemoryChange(tables: MemoryTables, change: StoreChange): ApplyResult {
+  const facts = change.facts.map((fact) => parseNewFact(fact));
+
+  if (!hasLiveUnder(tables, change.under)) {
+    return { kind: 'stale-generation' };
+  }
+
+  const leverSeqs = tables.levers.map((lever) => lever.seq);
+  const noticeIds = tables.notices.map((notice) => notice.id);
+
+  const applied = buildAppliedChange(
+    { ...change, facts },
+    { lastLeverSeq: Math.max(0, ...leverSeqs), lastNoticeId: Math.max(0, ...noticeIds) },
+  );
+
+  for (const write of applied.writes) {
+    const refusal = applyMemoryWrite(tables, write, change.at);
+
+    if (refusal !== null) {
+      return refusal;
+    }
+  }
+
+  for (const fact of applied.facts) {
+    if (tables.outbox.some((row) => row.factId === fact.id)) {
+      throw new Error('UNIQUE constraint failed: outbox (factId)');
+    }
+
+    tables.outbox.push({
+      seq: tables.outbox.length + 1,
+      factId: fact.id,
+      type: fact.type,
+      entity: fact.entity,
+      actor: fact.actor,
+      at: change.at,
+      payload: toJSONValue(fact.payload),
+      sentAt: null,
+      parkedAt: null,
+      parkedReason: null,
+    });
+  }
+
+  return { kind: 'applied' };
+}
+
+function hasLiveUnder(tables: MemoryTables, under: StoreChange['under']): boolean {
+  if (under === undefined || under === null) {
+    return true;
+  }
+
+  const lease = tables.leases.find(
+    (row) =>
+      row.item === under.item &&
+      row.phase === under.phase &&
+      row.gen === under.gen &&
+      row.releasedAt === null,
+  );
+
+  if (lease === undefined) {
+    return false;
+  }
+
+  return (
+    under.holdGen === undefined ||
+    tables.attempts.some(
+      (attempt) => attempt.id === lease.attempt && attempt.holdGen === under.holdGen,
+    )
+  );
+}
+
+function applyMemoryWrite(tables: MemoryTables, write: RowWrite, at: Instant): ApplyResult | null {
+  return match(write)
+    .with({ op: 'take-seats' }, (seats) => takeMemorySeats(tables, seats.take, at))
+    .with({ op: 'release-seats' }, (seats) => {
+      releaseMemorySeats(tables, seats.release, at);
+
+      return null;
+    })
+    .with({ op: 'insert', table: 'leases' }, (insert) => {
+      const isHeld = tables.leases.some(
+        (row) =>
+          row.item === insert.row.item && row.phase === insert.row.phase && row.releasedAt === null,
+      );
+
+      if (isHeld) {
+        return { kind: 'lease-held' } as const;
+      }
+
+      insertMemoryRow(tables, insert.table, insert.row);
+
+      return null;
+    })
+    .with({ op: 'insert' }, (insert) => {
+      insertMemoryRow(tables, insert.table, insert.row);
+
+      return null;
+    })
+    .with({ op: 'update' }, (update) => {
+      const rows: object[] = tables[update.table];
+
+      const matched = rows.filter(
+        (row) => hasFields(row, update.key) && hasFields(row, update.expect),
+      );
+
+      if (matched.length === 0) {
+        const key = toJSONValue(update.key);
+
+        return { kind: 'guard-mismatch', table: update.table, key } as const;
+      }
+
+      for (const row of matched) {
+        Object.assign(row, structuredClone(update.set));
+
+        assertMemoryUnique(update.table, rows, row);
+      }
+
+      return null;
+    })
+    .exhaustive();
+}
+
+function takeMemorySeats(tables: MemoryTables, take: SeatTake, at: Instant): ApplyResult | null {
+  const answer = pickSeatTake(take, collectMemoryLimitFills(tables), at);
+
+  if (answer.kind !== 'take') {
+    return { kind: answer.kind, limit: answer.limit };
+  }
+
+  for (const seat of answer.seats) {
+    if (tables.limit_seats.some((held) => isSameHeldSeat(seat, held))) {
+      throw new Error('UNIQUE constraint failed: limit_seats (limit, attempt, holdGen)');
+    }
+
+    tables.limit_seats.push(seat);
+  }
+
+  return null;
+}
+
+function releaseMemorySeats(tables: MemoryTables, release: SeatRelease, at: Instant): void {
+  for (const seat of tables.limit_seats) {
+    if (
+      seat.attempt === release.attempt &&
+      seat.holdGen === release.holdGen &&
+      seat.releasedAt === null
+    ) {
+      Object.assign(seat, { releasedAt: at });
+    }
+  }
+}
+
+function insertMemoryRow(tables: MemoryTables, table: TableName, row: object): void {
+  const rows: object[] = tables[table];
+  const copy = structuredClone(row);
+
+  rows.push(copy);
+
+  assertMemoryUnique(table, rows, copy);
+}
+
+interface UniqueKey {
+  readonly fields: readonly string[];
+
+  // a partial unique index covers only the rows where this field is null
+  readonly live?: string;
+}
+
+// A kept session binds one agent session to a later attempt, so the agent session alone is no key.
+const uniqueKeys: Readonly<Record<TableName, readonly UniqueKey[]>> = {
+  items: [{ fields: ['id'] }],
+  relations: [
+    { fields: ['source', 'target', 'type', 'addedAt'] },
+    { fields: ['source', 'target', 'type'], live: 'removedAt' },
+  ],
+  levers: [{ fields: ['seq'] }],
+  attempts: [{ fields: ['id'] }, { fields: ['item', 'phase', 'number'] }],
+  attempt_sessions: [{ fields: ['attempt', 'agentSession'] }],
+  leases: [{ fields: ['item', 'phase', 'gen'] }, { fields: ['item', 'phase'], live: 'releasedAt' }],
+  decisions: [{ fields: ['id'] }],
+  evidence: [{ fields: ['factId'] }, { fields: ['attempt', 'kind', 'ref'] }],
+  pull_requests: [{ fields: ['repo', 'number'] }],
+  runners: [{ fields: ['id'] }],
+  notes: [{ fields: ['item', 'seq'] }],
+  notices: [{ fields: ['id'] }],
+};
+
+function assertMemoryUnique(table: TableName, rows: readonly object[], row: object): void {
+  const fields = toFieldMap(row);
+
+  for (const key of uniqueKeys[table]) {
+    const hasClash = rows.some((other) => {
+      const otherFields = toFieldMap(other);
+
+      return (
+        other !== row &&
+        (key.live === undefined ||
+          (fields.get(key.live) === null && otherFields.get(key.live) === null)) &&
+        key.fields.every((field) => isDeepStrictEqual(otherFields.get(field), fields.get(field)))
+      );
+    });
+
+    if (hasClash) {
+      throw new Error(`UNIQUE constraint failed: ${table} (${key.fields.join(', ')})`);
+    }
+  }
+}
+
+function toFieldMap(row: object): Map<string, unknown> {
+  return new Map<string, unknown>(Object.entries(row));
+}
+
+function hasFields(row: object, fields: object): boolean {
+  const rowFields = toFieldMap(row);
+
+  return Object.entries(fields).every(([field, value]: [string, unknown]) =>
+    isDeepStrictEqual(rowFields.get(field), value),
+  );
+}

package/src/test-utils/build-memory-reader.ts

@@ -0,0 +1,364 @@
+import { isDeepStrictEqual } from 'node:util';
+import { buildItemViews } from '@boxxy/model';
+import type {
+  AtcSessionId,
+  AttemptRow,
+  EvidenceRow,
+  Instant,
+  ItemDetailRows,
+  ItemRow,
+  ItemRules,
+  ItemSetRows,
+  ItemView,
+  ItemWithLevers,
+  OutboxFact,
+  PullRequestRow,
+  RelationRow,
+  StoreReader,
+  Wake,
+} from '@boxxy/model';
+import { collectMemoryLimitFills } from './collect-memory-limit-fills.ts';
+import { compareText } from './compare-text.ts';
+import type { MemoryTables } from './types.ts';
+
+// SQLite hands out new objects on each read, so a caller that keeps or edits a row never touches
+// the store's own rows; each read here works on a copy to match.
+export function buildMemoryReader(getLiveTables: () => MemoryTables): StoreReader {
+  const getTables = () => structuredClone(getLiveTables());
+
+  const buildViews = (now: Instant, rules: ItemRules): ItemWithLevers[] =>
+    buildItemViews(toItemSetRows(getTables()), now, rules);
+
+  return {
+    readSnapshot: (now, rules) => {
+      const tables = getTables();
+      const open = buildViews(now, rules).filter((item) => isOpen(item));
+
+      return Promise.resolve({
+        storeVersion: tables.outbox.length,
+        items: open.map((item) => toItemView(item)),
+        relations: sortRelations(tables.relations.filter((row) => row.removedAt === null)),
+        levers: open
+          .flatMap((item) => item.levers)
+          .toSorted((first, second) => first.seq - second.seq),
+        limits: collectMemoryLimitFills(tables),
+        wakes: collectWakes(tables.attempts),
+      });
+    },
+    readItem: (id, now, rules) => {
+      const item = buildViews(now, rules).find((view) => view.id === id);
+      const view = item === undefined ? null : toItemView(item);
+
+      return Promise.resolve(view);
+    },
+    readItemDetail: (id, now, rules) => {
+      const tables = getTables();
+      const item = buildViews(now, rules).find((view) => view.id === id);
+
+      if (item === undefined) {
+        return Promise.resolve(null);
+      }
+
+      const attempts = sortAttempts(tables.attempts.filter((attempt) => attempt.item === id));
+
+      const attemptIds = new Set(attempts.map((attempt) => attempt.id));
+
+      const relations = sortRelations(
+        tables.relations.filter(
+          (row) => row.removedAt === null && (row.source === id || row.target === id),
+        ),
+      );
+
+      const detail: ItemDetailRows = {
+        item,
+        attempts,
+        relations,
+        evidence: sortEvidence(tables.evidence.filter((row) => attemptIds.has(row.attempt))),
+        pullRequests: sortPullRequests(
+          tables.pull_requests.filter((row) => attemptIds.has(row.attempt)),
+        ),
+        notes: tables.notes
+          .filter((note) => note.item === id)
+          .toSorted((first, second) => first.seq - second.seq),
+      };
+
+      return Promise.resolve(detail);
+    },
+    listItems: (filter, now, rules) =>
+      Promise.resolve(
+        buildViews(now, rules).filter(
+          (item) =>
+            (filter.state === undefined || item.derived.state === filter.state) &&
+            (filter.repo === undefined || item.repo === filter.repo),
+        ),
+      ),
+    listOpenIssues: (repo, now, rules) =>
+      Promise.resolve(
+        buildViews(now, rules)
+          .filter((item) => item.kind === 'core.issue' && item.repo === repo && isOpen(item))
+          .map((item) => toItemView(item)),
+      ),
+    readLastLeaseGen: (item, phase) => {
+      const gens = getTables()
+        .leases.filter((lease) => lease.item === item && lease.phase === phase)
+        .map((lease) => lease.gen);
+
+      return Promise.resolve(Math.max(0, ...gens));
+    },
+    readAttempt: (id) =>
+      Promise.resolve(getTables().attempts.find((attempt) => attempt.id === id) ?? null),
+    listEvidence: (attempt) =>
+      Promise.resolve(sortEvidence(getTables().evidence.filter((row) => row.attempt === attempt))),
+    listItemAttempts: (item) =>
+      Promise.resolve(
+        sortAttempts(getTables().attempts.filter((attempt) => attempt.item === item)),
+      ),
+    listLiveAttempts: () =>
+      Promise.resolve(sortAttempts(getTables().attempts.filter((attempt) => !isSettled(attempt)))),
+    listStrayAttempts: (since) =>
+      Promise.resolve(
+        sortAttempts(
+          getTables().attempts.filter(
+            (attempt) =>
+              attempt.strayedAt !== null &&
+              attempt.strayedAt >= since &&
+              attempt.sessionStoppedAt === null,
+          ),
+        ),
+      ),
+    listSucceededAttemptsWithoutPullRequest: () => {
+      const tables = getTables();
+
+      const linked = new Set(tables.pull_requests.map((row) => row.attempt));
+
+      return Promise.resolve(
+        sortAttempts(
+          tables.attempts.filter(
+            (attempt) => attempt.state === 'succeeded' && !linked.has(attempt.id),
+          ),
+        ),
+      );
+    },
+    findAttemptBySession: (session) =>
+      Promise.resolve(
+        sortAttempts(getTables().attempts).findLast((attempt) => attempt.atcSession === session) ??
+          null,
+      ),
+    findAttemptByAgentSession: (session) => {
+      const tables = getTables();
+
+      const bound = new Set(
+        tables.attempt_sessions
+          .filter((row) => row.agentSession === session)
+          .map((row) => row.attempt),
+      );
+
+      return Promise.resolve(
+        sortAttempts(tables.attempts).findLast((attempt) => bound.has(attempt.id))?.id ?? null,
+      );
+    },
+    findSessionByCaller: (caller) => {
+      const sessions = collectLatestBySession(getTables().attempts)
+        .filter((latest) => isDeepStrictEqual(latest.attempt.caller, caller))
+        .map((latest) => latest.session);
+
+      if (sessions.length > 1) {
+        return Promise.resolve('ambiguous');
+      }
+
+      return Promise.resolve(sessions[0] ?? null);
+    },
+    readPullRequestRow: (ref) =>
+      Promise.resolve(
+        getTables().pull_requests.find(
+          (row) => row.repo === ref.repo && row.number === ref.number,
+        ) ?? null,
+      ),
+    listWatchedPullRequests: () =>
+      Promise.resolve(
+        sortPullRequests(getTables().pull_requests.filter((row) => row.state === 'open')),
+      ),
+    listLimits: () => Promise.resolve(collectMemoryLimitFills(getTables())),
+    listLimitSeats: () => {
+      const held = getTables().limit_seats.filter((seat) => seat.releasedAt === null);
+
+      return Promise.resolve(
+        held.toSorted(
+          (first, second) =>
+            compareText(first.limit, second.limit) || compareText(first.attempt, second.attempt),
+        ),
+      );
+    },
+    listItemNotes: (item) =>
+      Promise.resolve(
+        getTables()
+          .notes.filter((note) => note.item === item)
+          .toSorted((first, second) => first.seq - second.seq),
+      ),
+    listUnsentNotices: (limit) =>
+      Promise.resolve(
+        getTables()
+          .notices.filter((notice) => notice.sentAt === null)
+          .toSorted((first, second) => first.id - second.id)
+          .slice(0, limit),
+      ),
+    listKeptSessions: () => {
+      const kept = sortItems(getTables().items).flatMap((item) =>
+        item.keptSession === null ? [] : [{ item: item.id, kept: item.keptSession }],
+      );
+
+      return Promise.resolve(
+        kept.toSorted((first, second) => first.kept.keptAt - second.kept.keptAt),
+      );
+    },
+    listSessionsToForget: (failedEndedBefore) => {
+      const tables = getTables();
+
+      const kept = new Set(
+        tables.items.flatMap((item) =>
+          item.keptSession === null ? [] : [item.keptSession.atcSession],
+        ),
+      );
+
+      return Promise.resolve(
+        collectLatestBySession(tables.attempts)
+          .filter((latest) => !kept.has(latest.session))
+          .map((latest) => latest.attempt)
+          .filter(
+            (attempt) =>
+              attempt.sessionForgottenAt === null &&
+              (attempt.strayedAt === null || attempt.sessionStoppedAt !== null) &&
+              (attempt.state === 'succeeded' ||
+                (attempt.state === 'failed' &&
+                  attempt.endedAt !== null &&
+                  attempt.endedAt <= failedEndedBefore)),
+          ),
+      );
+    },
+    readRunner: (id) => Promise.resolve(getTables().runners.find((row) => row.id === id) ?? null),
+    readUnsentFacts: (limit) =>
+      Promise.resolve(
+        getTables()
+          .outbox.filter((fact) => fact.sentAt === null && fact.parkedAt === null)
+          .slice(0, limit),
+      ),
+    readOutboxCounts: () => {
+      const waiting = getTables().outbox.filter((fact) => fact.sentAt === null);
+      const unsent = waiting.filter((fact) => fact.parkedAt === null);
+
+      return Promise.resolve({
+        unsent: unsent.length,
+        parked: waiting.length - unsent.length,
+        oldestUnsentAt: findOldestAt(unsent),
+      });
+    },
+    readItemBehind: (item) => {
+      const behind = getTables().outbox.filter(
+        (fact) => fact.sentAt === null && fact.entity === `boxxy:item:${item}`,
+      );
+
+      return Promise.resolve({ facts: behind.length, oldestAt: findOldestAt(behind) });
+    },
+  };
+}
+
+function toItemSetRows(tables: MemoryTables): ItemSetRows {
+  return {
+    items: sortItems(tables.items),
+    relations: tables.relations.filter((relation) => relation.removedAt === null),
+    levers: tables.levers.toSorted((first, second) => first.seq - second.seq),
+    attempts: sortAttempts(tables.attempts),
+    liveLeases: tables.leases.filter((lease) => lease.releasedAt === null),
+    pullRequests: tables.pull_requests,
+  };
+}
+
+function sortItems(items: readonly ItemRow[]): ItemRow[] {
+  return items.toSorted(
+    (first, second) => first.filedAt - second.filedAt || compareText(first.id, second.id),
+  );
+}
+
+function sortAttempts(attempts: readonly AttemptRow[]): AttemptRow[] {
+  return attempts.toSorted(
+    (first, second) => first.claimedAt - second.claimedAt || compareText(first.id, second.id),
+  );
+}
+
+function isOpen(item: ItemView): boolean {
+  return item.derived.state !== 'done' && item.derived.state !== 'archived';
+}
+
+function toItemView(item: ItemWithLevers): ItemView {
+  const { levers: _levers, ...view } = item;
+
+  return view;
+}
+
+function sortRelations(relations: readonly RelationRow[]): RelationRow[] {
+  return relations.toSorted(
+    (first, second) =>
+      first.addedAt - second.addedAt ||
+      compareText(first.source, second.source) ||
+      compareText(first.target, second.target),
+  );
+}
+
+function collectWakes(attempts: readonly AttemptRow[]): Wake[] {
+  const wakes = sortAttempts(attempts).flatMap((attempt) =>
+    attempt.state === 'sleeping' && attempt.wakeRequestedAt !== null
+      ? [
+          {
+            attempt: attempt.id,
+            item: attempt.item,
+            phase: attempt.phase,
+            pool: attempt.pool,
+            fields: attempt.fields,
+            requestedAt: attempt.wakeRequestedAt,
+          },
+        ]
+      : [],
+  );
+
+  return wakes.toSorted((first, second) => first.requestedAt - second.requestedAt);
+}
+
+function sortEvidence(rows: readonly EvidenceRow[]): EvidenceRow[] {
+  return rows.toSorted(
+    (first, second) => first.at - second.at || compareText(first.factId, second.factId),
+  );
+}
+
+function sortPullRequests(rows: readonly PullRequestRow[]): PullRequestRow[] {
+  return rows.toSorted(
+    (first, second) => compareText(first.repo, second.repo) || first.number - second.number,
+  );
+}
+
+function isSettled(attempt: AttemptRow): boolean {
+  return attempt.state === 'succeeded' || attempt.state === 'failed';
+}
+
+interface LatestOfSession {
+  readonly session: AtcSessionId;
+  readonly attempt: AttemptRow;
+}
+
+// the latest attempt of each atc session, in the order of those attempts
+function collectLatestBySession(attempts: readonly AttemptRow[]): LatestOfSession[] {
+  const latest = new Map<AtcSessionId, AttemptRow>();
+
+  for (const attempt of sortAttempts(attempts)) {
+    if (attempt.atcSession !== null) {
+      latest.set(attempt.atcSession, attempt);
+    }
+  }
+
+  return sortAttempts([...latest.values()]).flatMap((attempt) =>
+    attempt.atcSession === null ? [] : [{ session: attempt.atcSession, attempt }],
+  );
+}
+
+function findOldestAt(facts: readonly OutboxFact[]): Instant | null {
+  return facts.toSorted((first, second) => first.at - second.at).at(0)?.at ?? null;
+}

package/src/test-utils/build-mock-bind-change.ts

@@ -0,0 +1,43 @@
+import { brandSchemas } from '@boxxy/model';
+import type { AgentSessionId, AttemptRow, StoreChange } from '@boxxy/model';
+import { buildMockFactId } from '@boxxy/model/test-utils/build-mock-fact-id';
+import invariant from 'tiny-invariant';
+
+interface BindInput {
+  readonly attempt: AttemptRow;
+  readonly agentSession: AgentSessionId;
+}
+
+// The session-start hook binds a Claude agent session to the attempt's atc session.
+export function buildMockBindChange(input: BindInput): StoreChange {
+  const attempt = input.attempt;
+  const agentSession = input.agentSession;
+  const atcSession = attempt.atcSession;
+  const seenAt = brandSchemas.instant.parse(2500);
+
+  invariant(atcSession !== null, 'a bound attempt names its atc session');
+
+  const row = {
+    attempt: attempt.id,
+    agentSession,
+    atcSession,
+    product: 'claude_code',
+    source: 'hook',
+    seenAt,
+  } as const;
+
+  return {
+    at: seenAt,
+    under: { item: attempt.item, phase: attempt.phase, gen: attempt.leaseGen },
+    writes: [{ op: 'insert', table: 'attempt_sessions', row }],
+    facts: [
+      {
+        id: buildMockFactId(),
+        type: 'boxxy.attempt.session_bound',
+        entity: `boxxy:item:${attempt.item}`,
+        actor: `boxxy:hook:${attempt.id}`,
+        payload: row,
+      },
+    ],
+  };
+}

package/src/test-utils/build-mock-claim-change.ts

@@ -0,0 +1,52 @@
+import type { AttemptRow, LimitName, StoreChange } from '@boxxy/model';
+import { buildMockFactId } from '@boxxy/model/test-utils/build-mock-fact-id';
+
+// A claim that takes the lease and a seat in each named limit, and inserts the attempt as given.
+export function buildMockClaimChange(
+  attempt: AttemptRow,
+  limits: readonly LimitName[] = [],
+): StoreChange {
+  return {
+    at: attempt.claimedAt,
+    writes: [
+      {
+        op: 'take-seats',
+        take: { limits, attempt: attempt.id, holdGen: attempt.holdGen, overCap: false },
+      },
+      {
+        op: 'insert',
+        table: 'leases',
+        row: {
+          item: attempt.item,
+          phase: attempt.phase,
+          attempt: attempt.id,
+          gen: attempt.leaseGen,
+          takenAt: attempt.claimedAt,
+          releasedAt: null,
+        },
+      },
+      { op: 'insert', table: 'attempts', row: attempt },
+    ],
+    facts: [
+      {
+        id: buildMockFactId(),
+        type: 'boxxy.attempt.claimed',
+        entity: `boxxy:item:${attempt.item}`,
+        actor: `boxxy:runner:${attempt.runner}`,
+        payload: {
+          attempt: attempt.id,
+          phase: attempt.phase,
+          number: attempt.number,
+          round: attempt.round,
+          mode: attempt.mode,
+          pool: attempt.pool,
+          fields: attempt.fields,
+          seats: limits.map((limit) => ({ limit })),
+          recipeHash: attempt.recipeHash,
+          skillsRef: null,
+          rulesVersion: attempt.rulesVersion,
+        },
+      },
+    ],
+  };
+}