@boxxy/dispatch 0.0.0 → 0.1.1

package/README.md

@@ -9,11 +9,16 @@
 
 boxxy's dispatch module, which claims the next task for an agent and settles each attempt.
 
-This version is a placeholder that exports only its package name, as `packageName`. The
+This version exports only its package name, as `packageName`, from its main entry. Its
+`./test-utils/*` entry holds `createMemoryClaimStore`, the memory fake of the `ClaimStore` port, and
+`claimStoreContract`, the cases that every `ClaimStore` passes
+([ports and adapters](../../docs/design/boxxy/slice-1.md#ports-and-adapters)). The
 [boxxy README](https://github.com/zgeoff/boxxy#workspace) lists the workspace's packages.
 
 ## Install
 
+Install the package from [npm](https://www.npmjs.com/package/@boxxy/dispatch) with Bun:
+
 ```bash
 bun add @boxxy/dispatch
 ```

package/dist/test-utils/build-mock-bind-change.d.ts

@@ -0,0 +1,7 @@
+import type { AgentSessionId, AttemptRow, StoreChange } from '@boxxy/model';
+interface BindInput {
+    readonly attempt: AttemptRow;
+    readonly agentSession: AgentSessionId;
+}
+export declare function buildMockBindChange(input: BindInput): StoreChange;
+export {};

package/dist/test-utils/build-mock-claim-change.d.ts

@@ -0,0 +1,2 @@
+import type { AttemptRow, StoreChange } from '@boxxy/model';
+export declare function buildMockClaimChange(attempt: AttemptRow): StoreChange;

package/dist/test-utils/build-mock-file-item-change.d.ts

@@ -0,0 +1,2 @@
+import type { ItemRow, StoreChange } from '@boxxy/model';
+export declare function buildMockFileItemChange(item: ItemRow): StoreChange;

package/dist/test-utils/build-mock-lever-change.d.ts

@@ -0,0 +1,2 @@
+import type { LeverRow, StoreChange } from '@boxxy/model';
+export declare function buildMockLeverChange(lever: LeverRow): StoreChange;

package/dist/test-utils/build-mock-link-change.d.ts

@@ -0,0 +1,7 @@
+import type { ItemId, StoreChange } from '@boxxy/model';
+interface LinkInput {
+    readonly source: ItemId;
+    readonly target: ItemId;
+}
+export declare function buildMockLinkChange(input: LinkInput): StoreChange;
+export {};

package/dist/test-utils/build-mock-pause-change.d.ts

@@ -0,0 +1,2 @@
+import type { RunnerId, StoreChange } from '@boxxy/model';
+export declare function buildMockPauseChange(runner: RunnerId): StoreChange;

package/dist/test-utils/build-mock-pull-request-change.d.ts

@@ -0,0 +1,7 @@
+import type { AttemptRow, PullRequestRow, StoreChange } from '@boxxy/model';
+interface PullRequestInput {
+    readonly attempt: AttemptRow;
+    readonly state: PullRequestRow['state'];
+}
+export declare function buildMockPullRequestChange(input: PullRequestInput): StoreChange;
+export {};

package/dist/test-utils/build-mock-settle-change.d.ts

@@ -0,0 +1,7 @@
+import type { AttemptRow, StoreChange } from '@boxxy/model';
+interface SettleInput {
+    readonly attempt: AttemptRow;
+    readonly state: 'succeeded' | 'failed';
+}
+export declare function buildMockSettleChange(input: SettleInput): StoreChange;
+export {};

package/dist/test-utils/build-mock-start-change.d.ts

@@ -0,0 +1,2 @@
+import type { AttemptRow, StoreChange } from '@boxxy/model';
+export declare function buildMockStartChange(attempt: AttemptRow): StoreChange;

package/dist/test-utils/claim-store-attempt-reader-cases.d.ts

@@ -0,0 +1,2 @@
+import type { ClaimStoreCase } from './types.ts';
+export declare const claimStoreAttemptReaderCases: readonly ClaimStoreCase[];

package/dist/test-utils/claim-store-claim-cases.d.ts

@@ -0,0 +1,2 @@
+import type { ClaimStoreCase } from './types.ts';
+export declare const claimStoreClaimCases: readonly ClaimStoreCase[];

package/dist/test-utils/claim-store-contract.d.ts

@@ -0,0 +1,2 @@
+import type { ClaimStoreCase } from './types.ts';
+export declare const claimStoreContract: readonly ClaimStoreCase[];

package/dist/test-utils/claim-store-exclusive-cases.d.ts

@@ -0,0 +1,2 @@
+import type { ClaimStoreCase } from './types.ts';
+export declare const claimStoreExclusiveCases: readonly ClaimStoreCase[];

package/dist/test-utils/claim-store-guard-cases.d.ts

@@ -0,0 +1,2 @@
+import type { ClaimStoreCase } from './types.ts';
+export declare const claimStoreGuardCases: readonly ClaimStoreCase[];

package/dist/test-utils/claim-store-item-reader-cases.d.ts

@@ -0,0 +1,2 @@
+import type { ClaimStoreCase } from './types.ts';
+export declare const claimStoreItemReaderCases: readonly ClaimStoreCase[];

package/dist/test-utils/claim-store-pool-cases.d.ts

@@ -0,0 +1,2 @@
+import type { ClaimStoreCase } from './types.ts';
+export declare const claimStorePoolCases: readonly ClaimStoreCase[];

package/dist/test-utils/claim-store-rollback-cases.d.ts

@@ -0,0 +1,2 @@
+import type { ClaimStoreCase } from './types.ts';
+export declare const claimStoreRollbackCases: readonly ClaimStoreCase[];

package/dist/test-utils/create-memory-claim-store.d.ts

@@ -0,0 +1,2 @@
+import type { ClaimStore } from '@boxxy/model';
+export declare function createMemoryClaimStore(): ClaimStore;

package/dist/test-utils/types.d.ts

@@ -0,0 +1,9 @@
+import type { ClaimStore } from '@boxxy/model';
+export interface ClaimStoreOutcome {
+    readonly received: unknown;
+    readonly expected: unknown;
+}
+export type ClaimStoreCase = readonly [
+    title: string,
+    check: (store: ClaimStore) => Promise<ClaimStoreOutcome>
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boxxy/dispatch",
-  "version": "0.0.0",
+  "version": "0.1.1",
   "description": "boxxy's dispatch: claims the next task for an agent",
   "homepage": "https://github.com/zgeoff/boxxy/tree/main/modules/dispatch#readme",
   "bugs": "https://github.com/zgeoff/boxxy/issues",
@@ -20,7 +20,8 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./src/index.ts"
-    }
+    },
+    "./test-utils/*": "./src/test-utils/*.ts"
   },
   "publishConfig": {
     "access": "public"
@@ -29,6 +30,11 @@
     "build": "rm -rf dist && tsrs -p tsconfig.build.json",
     "typecheck": "tsrs --noEmit"
   },
+  "dependencies": {
+    "@boxxy/model": "0.1.2",
+    "tiny-invariant": "1.3.3",
+    "ts-pattern": "5.9.2"
+  },
   "engines": {
     "bun": ">=1.3",
     "node": ">=24"

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

@@ -0,0 +1,36 @@
+import { brandSchemas } from '@boxxy/model';
+import type { AgentSessionId, AttemptRow, StoreChange } from '@boxxy/model';
+import { buildMockFactId } from '@boxxy/model/test-utils/build-mock-fact-id';
+
+interface BindInput {
+  readonly attempt: AttemptRow;
+  readonly agentSession: AgentSessionId;
+}
+
+export function buildMockBindChange(input: BindInput): StoreChange {
+  const attempt = input.attempt;
+  const agentSession = input.agentSession;
+  const atcSession = brandSchemas.atcSessionId.parse('atc-session-1');
+  const seenAt = brandSchemas.instant.parse(2500);
+
+  return {
+    at: seenAt,
+    under: { item: attempt.item, phase: attempt.phase, gen: attempt.leaseGen },
+    writes: [
+      {
+        op: 'insert',
+        table: 'attempt_sessions',
+        row: { attempt: attempt.id, agentSession, atcSession, seenAt },
+      },
+    ],
+    facts: [
+      {
+        id: buildMockFactId(),
+        type: 'boxxy.attempt.session_bound',
+        entity: `boxxy:attempt:${attempt.id}`,
+        actor: `boxxy:runner:${attempt.runner}`,
+        payload: { atcSession, agentSession, seenAt },
+      },
+    ],
+  };
+}

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

@@ -0,0 +1,42 @@
+import type { AttemptRow, StoreChange } from '@boxxy/model';
+import { buildMockFactId } from '@boxxy/model/test-utils/build-mock-fact-id';
+
+export function buildMockClaimChange(attempt: AttemptRow): StoreChange {
+  return {
+    at: attempt.claimedAt,
+    writes: [
+      { op: 'take-slot', pool: attempt.pool, holder: attempt.id },
+      {
+        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, slot: 0, slotGen: 0 } },
+    ],
+    facts: [
+      {
+        id: buildMockFactId(),
+        type: 'boxxy.attempt.claimed',
+        entity: `boxxy:attempt:${attempt.id}`,
+        actor: `boxxy:runner:${attempt.runner}`,
+        payload: {
+          item: attempt.item,
+          phase: attempt.phase,
+          number: attempt.number,
+          pool: attempt.pool,
+          slot: 0,
+          gen: 0,
+          recipeHash: attempt.recipeHash,
+          rulesVersion: attempt.rulesVersion,
+        },
+      },
+    ],
+  };
+}

package/src/test-utils/build-mock-file-item-change.ts

@@ -0,0 +1,18 @@
+import type { ItemRow, StoreChange } from '@boxxy/model';
+import { buildMockFactId } from '@boxxy/model/test-utils/build-mock-fact-id';
+
+export function buildMockFileItemChange(item: ItemRow): StoreChange {
+  return {
+    at: item.filedAt,
+    writes: [{ op: 'insert', table: 'items', row: item }],
+    facts: [
+      {
+        id: buildMockFactId(),
+        type: 'boxxy.item.filed',
+        entity: `boxxy:item:${item.id}`,
+        actor: 'boxxy:owner:local',
+        payload: item,
+      },
+    ],
+  };
+}

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

@@ -0,0 +1,18 @@
+import type { LeverRow, StoreChange } from '@boxxy/model';
+import { buildMockFactId } from '@boxxy/model/test-utils/build-mock-fact-id';
+
+export function buildMockLeverChange(lever: LeverRow): StoreChange {
+  return {
+    at: lever.at,
+    writes: [{ op: 'insert', table: 'levers', row: lever }],
+    facts: [
+      {
+        id: buildMockFactId(),
+        type: 'boxxy.lever.recorded',
+        entity: `boxxy:item:${lever.item}`,
+        actor: lever.actor,
+        payload: lever,
+      },
+    ],
+  };
+}

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

@@ -0,0 +1,40 @@
+import { brandSchemas } from '@boxxy/model';
+import type { ItemId, StoreChange } from '@boxxy/model';
+import { buildMockFactId } from '@boxxy/model/test-utils/build-mock-fact-id';
+
+interface LinkInput {
+  readonly source: ItemId;
+  readonly target: ItemId;
+}
+
+export function buildMockLinkChange(input: LinkInput): StoreChange {
+  const type = brandSchemas.linkTypeName.parse('blocks');
+  const addedAt = brandSchemas.instant.parse(3500);
+
+  return {
+    at: addedAt,
+    writes: [
+      {
+        op: 'insert',
+        table: 'links',
+        row: {
+          source: input.source,
+          target: input.target,
+          type,
+          addedBy: 'boxxy:owner:local',
+          addedAt,
+          removedAt: null,
+        },
+      },
+    ],
+    facts: [
+      {
+        id: buildMockFactId(),
+        type: 'boxxy.link.added',
+        entity: `boxxy:link:${input.source}:${type}:${input.target}`,
+        actor: 'boxxy:owner:local',
+        payload: { source: input.source, target: input.target, type },
+      },
+    ],
+  };
+}

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

@@ -0,0 +1,27 @@
+import { brandSchemas } from '@boxxy/model';
+import type { RunnerId, StoreChange } from '@boxxy/model';
+import { buildMockFactId } from '@boxxy/model/test-utils/build-mock-fact-id';
+
+export function buildMockPauseChange(runner: RunnerId): StoreChange {
+  return {
+    at: brandSchemas.instant.parse(1500),
+    writes: [
+      {
+        op: 'update',
+        table: 'runners',
+        key: { id: runner },
+        expect: { paused: false },
+        set: { paused: true },
+      },
+    ],
+    facts: [
+      {
+        id: buildMockFactId(),
+        type: 'boxxy.runner.paused',
+        entity: `boxxy:runner:${runner}`,
+        actor: 'boxxy:owner:local',
+        payload: { runner },
+      },
+    ],
+  };
+}

package/src/test-utils/build-mock-pull-request-change.ts

@@ -0,0 +1,53 @@
+import { brandSchemas } from '@boxxy/model';
+import type { AttemptRow, PullRequestRow, StoreChange } from '@boxxy/model';
+import { buildMockFactId } from '@boxxy/model/test-utils/build-mock-fact-id';
+import { buildMockPullRequestRow } from '@boxxy/model/test-utils/build-mock-pull-request-row';
+
+interface PullRequestInput {
+  readonly attempt: AttemptRow;
+  readonly state: PullRequestRow['state'];
+}
+
+export function buildMockPullRequestChange(input: PullRequestInput): StoreChange {
+  const attempt = input.attempt;
+  const linkedAt = brandSchemas.instant.parse(4000);
+  const factId = buildMockFactId();
+  const url = 'https://github.com/acme/lamps/pull/7';
+
+  const pullRequest = buildMockPullRequestRow({
+    repo: brandSchemas.repoName.parse('acme/lamps'),
+    number: 7,
+    attempt: attempt.id,
+    state: input.state,
+    checkedAt: linkedAt,
+  });
+
+  return {
+    at: linkedAt,
+    writes: [
+      { op: 'insert', table: 'pull_requests', row: pullRequest },
+      {
+        op: 'insert',
+        table: 'evidence',
+        row: {
+          factId,
+          attempt: attempt.id,
+          kind: 'pr',
+          ref: url,
+          observed: null,
+          source: 'hook',
+          at: linkedAt,
+        },
+      },
+    ],
+    facts: [
+      {
+        id: factId,
+        type: 'boxxy.evidence.pr_linked',
+        entity: `boxxy:attempt:${attempt.id}`,
+        actor: `boxxy:hook:${attempt.id}`,
+        payload: { repo: pullRequest.repo, number: 7, url },
+      },
+    ],
+  };
+}

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

@@ -0,0 +1,58 @@
+import { brandSchemas } from '@boxxy/model';
+import type { AttemptRow, StoreChange } from '@boxxy/model';
+import { buildMockFactId } from '@boxxy/model/test-utils/build-mock-fact-id';
+
+interface SettleInput {
+  // the attempt as claimed, with the slot and slot gen its take got
+  readonly attempt: AttemptRow;
+  readonly state: 'succeeded' | 'failed';
+}
+
+export function buildMockSettleChange(input: SettleInput): StoreChange {
+  const attempt = input.attempt;
+  const endedAt = brandSchemas.instant.parse(3000);
+  const failure = input.state === 'failed' ? 'closeout-missing' : null;
+
+  return {
+    at: endedAt,
+    under: {
+      item: attempt.item,
+      phase: attempt.phase,
+      gen: attempt.leaseGen,
+      slot: { pool: attempt.pool, slot: attempt.slot, gen: attempt.slotGen },
+    },
+    writes: [
+      {
+        op: 'update',
+        table: 'attempts',
+        key: { id: attempt.id },
+        expect: { state: attempt.state },
+        set: { state: input.state, failure, endedAt },
+      },
+      {
+        op: 'update',
+        table: 'leases',
+        key: { item: attempt.item, phase: attempt.phase, gen: attempt.leaseGen },
+        expect: { releasedAt: null },
+        set: { releasedAt: endedAt },
+      },
+      { op: 'release-slot', pool: attempt.pool, slot: attempt.slot, holder: attempt.id },
+    ],
+    facts: [
+      {
+        id: buildMockFactId(),
+        type: 'boxxy.attempt.settled',
+        entity: `boxxy:attempt:${attempt.id}`,
+        actor: `boxxy:runner:${attempt.runner}`,
+        payload: {
+          state: input.state,
+          failure,
+          endedAt,
+          criteria: [],
+          matched: [],
+          frictionDropped: 0,
+        },
+      },
+    ],
+  };
+}

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

@@ -0,0 +1,31 @@
+import { brandSchemas } from '@boxxy/model';
+import type { AttemptRow, StoreChange } from '@boxxy/model';
+import { buildMockFactId } from '@boxxy/model/test-utils/build-mock-fact-id';
+
+export function buildMockStartChange(attempt: AttemptRow): StoreChange {
+  const atcSession = brandSchemas.atcSessionId.parse('atc-session-1');
+  const startedAt = brandSchemas.instant.parse(2500);
+
+  return {
+    at: startedAt,
+    under: { item: attempt.item, phase: attempt.phase, gen: attempt.leaseGen },
+    writes: [
+      {
+        op: 'update',
+        table: 'attempts',
+        key: { id: attempt.id },
+        expect: { state: 'starting' },
+        set: { state: 'running', atcSession, startedAt },
+      },
+    ],
+    facts: [
+      {
+        id: buildMockFactId(),
+        type: 'boxxy.attempt.started',
+        entity: `boxxy:attempt:${attempt.id}`,
+        actor: `boxxy:runner:${attempt.runner}`,
+        payload: { atcSession },
+      },
+    ],
+  };
+}