@boxxy/model 0.1.1 → 0.1.2

package/dist/actor-ref-schema.d.ts

@@ -0,0 +1,2 @@
+import { z } from 'zod';
+export declare const actorRefSchema: z.ZodUnion<readonly [z.ZodLiteral<"boxxy:owner:local">, z.ZodTemplateLiteral<`boxxy:runner:${string & z.$brand<"RunnerId">}`>, z.ZodTemplateLiteral<`boxxy:attempt:${string & z.$brand<"AttemptId">}`>, z.ZodTemplateLiteral<`boxxy:hook:${string & z.$brand<"AttemptId">}`>]>;

package/dist/build-applied-change.d.ts

@@ -0,0 +1,13 @@
+import type { AttemptId, PoolName } from './types/core.ts';
+import type { StoreChange } from './types/ports.ts';
+export interface TakenSlot {
+    readonly holder: AttemptId;
+    readonly pool: PoolName;
+    readonly slot: number;
+    readonly gen: number;
+}
+export interface ChangeAssignments {
+    readonly taken: TakenSlot | null;
+    readonly lastLeverSeq: number;
+}
+export declare function buildAppliedChange(change: StoreChange, assignments: ChangeAssignments): Pick<StoreChange, 'writes' | 'facts'>;

package/dist/build-item-views.d.ts

@@ -0,0 +1,2 @@
+import type { Instant, ItemSetRows, ItemWithLevers, MaxAttemptsByKind } from './types/core.ts';
+export declare function buildItemViews(rows: ItemSetRows, now: Instant, maxAttemptsByKind: MaxAttemptsByKind): ItemWithLevers[];

package/dist/find-slot-take.d.ts

@@ -0,0 +1,5 @@
+import type { RowWrite } from './types/ports.ts';
+export type SlotTake = Extract<RowWrite, {
+    op: 'take-slot';
+}>;
+export declare function findSlotTake(writes: readonly RowWrite[]): SlotTake | null;

package/dist/format-key-path.d.ts

@@ -0,0 +1 @@
+export declare function formatKeyPath(segments: readonly PropertyKey[]): string;

package/dist/index.d.ts

@@ -1,15 +1,22 @@
 export type { ContentHash, JsonValue } from '@boxxy/content-hash';
 export { brandSchemas } from './brand-schemas.ts';
+export { buildAppliedChange, type ChangeAssignments, type TakenSlot, } from './build-applied-change.ts';
 export { buildCloseOutSchema } from './build-close-out-schema.ts';
+export { buildItemViews } from './build-item-views.ts';
 export { defineAdmission } from './define-admission.ts';
 export { defineGate } from './define-gate.ts';
 export { defineSignal } from './define-signal.ts';
 export { deriveItemState } from './derive-item-state.ts';
 export { factSchemas } from './fact-schemas.ts';
+export { findSlotTake, type SlotTake } from './find-slot-take.ts';
+export { formatKeyPath } from './format-key-path.ts';
 export { frictionSchema } from './friction-schema.ts';
 export { liveLevers } from './live-levers.ts';
+export { outboxFactSchema } from './outbox-fact-schema.ts';
+export { rowSchemas } from './row-schemas.ts';
 export { signalKey } from './signal-key.ts';
-export type { Actor, ActorRef, AgentSessionId, AtcSessionId, AttemptId, AttemptRow, AttemptSessionRow, AttemptState, CommitSha, ConceptPin, Criterion, CriterionId, DecisionId, DecisionRow, DerivedState, Effort, EvidenceKind, EvidenceRow, EvidenceSource, FactId, FaultRecord, ForcedFailure, Instant, ItemId, ItemKindName, ItemRow, ItemRows, ItemState, ItemView, ItemWithLevers, KnownFailure, LeaseRow, LeverKind, LeverRow, LinkRow, LinkTypeName, LiveAttemptState, LoadedRecipe, MaxAttemptsByKind, Minutes, ObservationBoundary, PhaseName, PipelineName, PoolName, PoolSlotRow, PullRequestRef, PullRequestRow, Recipe, RecipeHash, RecipeMaterial, RecipeName, RepoName, ResolvedRecipe, RulesVersion, RunnerId, RunnerRow, SnapshotHash, SourceName, StreamName, WaitingReason, WorkerKindName, } from './types/core.ts';
+export { toJSONValue } from './to-json-value.ts';
+export type { Actor, ActorRef, AgentSessionId, AtcSessionId, AttemptId, AttemptRow, AttemptSessionRow, AttemptState, CommitSha, ConceptPin, Criterion, CriterionId, DecisionId, DecisionRow, DerivedState, Effort, EvidenceKind, EvidenceRow, EvidenceSource, FactId, FaultRecord, ForcedFailure, Instant, ItemId, ItemKindName, ItemRow, ItemRows, ItemSetRows, ItemState, ItemView, ItemWithLevers, KnownFailure, LeaseRow, LeverKind, LeverRow, LinkRow, LinkTypeName, LiveAttemptState, LoadedRecipe, MaxAttemptsByKind, Minutes, ObservationBoundary, PhaseName, PipelineName, PoolName, PoolSlotRow, PullRequestRef, PullRequestRow, Recipe, RecipeHash, RecipeMaterial, RecipeName, RepoName, ResolvedRecipe, RulesVersion, RunnerId, RunnerRow, SnapshotHash, SourceName, StreamName, WaitingReason, WorkerKindName, } from './types/core.ts';
 export type { Claim, CloseOutContext, CloseOutParse, CloseOutParser, CloseOutProblem, ReconcileAction, ReconcileTable, SettleInput, Settlement, SettleRule, SpawnContext, } from './types/dispatch.ts';
 export type { BuildCloseOut, EntityRef, FactEnvelope, FactType, Friction, FrictionTargetKind, LinkPayload, NewFact, OpenItem, OutboxFact, SliceOneFacts, } from './types/facts.ts';
 export type { Admission, AdmissionGrant, AdmissionName, Decision, Fault, Frame, FrameItem, FrameValues, Gate, GateName, Hold, Lift, Pick, PlanContext, Pool, PropagationLine, Signal, SignalKey, SignalName, Snapshot, View, ViewName, Waiver, WaiverName, } from './types/planning.ts';

package/dist/outbox-fact-schema.d.ts

@@ -0,0 +1,3 @@
+import { z } from 'zod';
+import type { OutboxFact } from './types/facts.ts';
+export declare const outboxFactSchema: z.ZodType<OutboxFact>;

package/dist/row-schemas.d.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+import type { TableName, Tables } from './types/ports.ts';
+export declare const rowSchemas: {
+    readonly [T in TableName]: z.ZodType<Tables[T]>;
+};

package/dist/test-utils/build-mock-evidence-row.d.ts

@@ -0,0 +1,2 @@
+import type { EvidenceRow } from '../types/core.ts';
+export declare function buildMockEvidenceRow(overrides?: Partial<EvidenceRow>): EvidenceRow;

package/dist/test-utils/build-mock-fact-id.d.ts

@@ -0,0 +1,2 @@
+import type { FactId } from '../types/core.ts';
+export declare function buildMockFactId(): FactId;

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

@@ -0,0 +1,2 @@
+import type { FrameItem } from '../types/planning.ts';
+export declare function buildMockFrameItem(overrides?: Partial<FrameItem>): FrameItem;

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

@@ -0,0 +1,2 @@
+import type { ItemView } from '../types/core.ts';
+export declare function buildMockItemView(overrides?: Partial<ItemView>): ItemView;

package/dist/test-utils/build-mock-snapshot.d.ts

@@ -0,0 +1,2 @@
+import type { Snapshot } from '../types/planning.ts';
+export declare function buildMockSnapshot(overrides?: Partial<Snapshot>): Snapshot;

package/dist/to-json-value.d.ts

@@ -0,0 +1,2 @@
+import type { JsonValue } from '@boxxy/content-hash';
+export declare function toJSONValue(value: unknown): JsonValue;

package/dist/types/core.d.ts

@@ -88,6 +88,14 @@ export interface ItemRows {
     readonly pullRequests: readonly PullRequestRow[];
     readonly maxAttempts: number;
 }
+export interface ItemSetRows {
+    readonly items: readonly ItemRow[];
+    readonly links: readonly LinkRow[];
+    readonly levers: readonly LeverRow[];
+    readonly attempts: readonly AttemptRow[];
+    readonly liveLeases: readonly LeaseRow[];
+    readonly pullRequests: readonly PullRequestRow[];
+}
 export type MaxAttemptsByKind = ReadonlyMap<ItemKindName, ReadonlyMap<PhaseName, number>>;
 export interface ItemWithLevers extends ItemView {
     readonly levers: readonly LeverRow[];
@@ -175,7 +183,7 @@ export interface DecisionRow {
 }
 export interface FaultRecord {
     readonly plugin: string;
-    readonly kind: 'signal' | 'gate' | 'waiver' | 'admission' | 'propagation';
+    readonly kind: 'signal' | 'gate' | 'waiver' | 'admission' | 'propagation' | 'filter-field';
     readonly item: ItemId | null;
     readonly error: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boxxy/model",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "The types that boxxy's packages share",
   "homepage": "https://github.com/zgeoff/boxxy/tree/main/libs/model#readme",
   "bugs": "https://github.com/zgeoff/boxxy/issues",
@@ -33,6 +33,7 @@
   "dependencies": {
     "@boxxy/content-hash": "0.1.0",
     "@faker-js/faker": "10.6.0",
+    "tiny-invariant": "1.3.3",
     "zod": "4.6.7"
   },
   "engines": {

package/src/actor-ref-schema.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+import { brandSchemas } from './brand-schemas.ts';
+
+export const actorRefSchema = z.union([
+  z.literal('boxxy:owner:local'),
+  z.templateLiteral(['boxxy:runner:', brandSchemas.runnerId]),
+  z.templateLiteral(['boxxy:attempt:', brandSchemas.attemptId]),
+  z.templateLiteral(['boxxy:hook:', brandSchemas.attemptId]),
+]);

package/src/build-applied-change.ts

@@ -0,0 +1,71 @@
+import type { AttemptId, PoolName } from './types/core.ts';
+import type { AnyNewFact, RowWrite, StoreChange } from './types/ports.ts';
+
+export interface TakenSlot {
+  readonly holder: AttemptId;
+  readonly pool: PoolName;
+  readonly slot: number;
+  readonly gen: number;
+}
+
+export interface ChangeAssignments {
+  readonly taken: TakenSlot | null;
+
+  // 0 when the store holds no lever
+  readonly lastLeverSeq: number;
+}
+
+export function buildAppliedChange(
+  change: StoreChange,
+  assignments: ChangeAssignments,
+): Pick<StoreChange, 'writes' | 'facts'> {
+  const leverSeqs: number[] = [];
+
+  const writes = change.writes.map((write): RowWrite => {
+    if (write.op !== 'insert') {
+      return write;
+    }
+
+    if (write.table === 'levers') {
+      const seq = assignments.lastLeverSeq + leverSeqs.length + 1;
+
+      leverSeqs.push(seq);
+
+      return { ...write, row: { ...write.row, seq } };
+    }
+
+    if (write.table === 'attempts' && write.row.id === assignments.taken?.holder) {
+      const taken = assignments.taken;
+
+      return { ...write, row: { ...write.row, slot: taken.slot, slotGen: taken.gen } };
+    }
+
+    return write;
+  });
+
+  let leverFacts = 0;
+
+  const facts = change.facts.map((fact): AnyNewFact => {
+    if (fact.type === 'boxxy.lever.recorded') {
+      const seq = leverSeqs[leverFacts];
+
+      leverFacts += 1;
+
+      return seq === undefined ? fact : { ...fact, payload: { ...fact.payload, seq } };
+    }
+
+    if (
+      fact.type === 'boxxy.attempt.claimed' &&
+      assignments.taken !== null &&
+      fact.entity === `boxxy:attempt:${assignments.taken.holder}`
+    ) {
+      const taken = assignments.taken;
+
+      return { ...fact, payload: { ...fact.payload, slot: taken.slot, gen: taken.gen } };
+    }
+
+    return fact;
+  });
+
+  return { writes, facts };
+}

package/src/build-item-views.ts

@@ -0,0 +1,128 @@
+import { deriveItemState } from './derive-item-state.ts';
+import { liveLevers } from './live-levers.ts';
+import type {
+  AttemptId,
+  AttemptRow,
+  Instant,
+  ItemId,
+  ItemKindName,
+  ItemRow,
+  ItemRows,
+  ItemSetRows,
+  ItemState,
+  ItemWithLevers,
+  LeaseRow,
+  LeverRow,
+  LinkRow,
+  MaxAttemptsByKind,
+  PullRequestRow,
+} from './types/core.ts';
+
+export function buildItemViews(
+  rows: ItemSetRows,
+  now: Instant,
+  maxAttemptsByKind: MaxAttemptsByKind,
+): ItemWithLevers[] {
+  const groups = collectItemGroups(rows, now);
+
+  // A blocking source counts only when it is done or archived, and no link makes an item either,
+  // so each source's state derived without its links settles its targets.
+  const ownStates = new Map<ItemId, ItemState>(
+    rows.items.map((item) => [
+      item.id,
+      deriveItemState(
+        item,
+        buildItemRows(item, groups.get(item.id), maxAttemptsByKind, {
+          links: [],
+          blockerStates: new Map(),
+        }),
+      ).state,
+    ]),
+  );
+
+  return rows.items.map((item) => {
+    const group = groups.get(item.id);
+
+    const itemRows = buildItemRows(item, group, maxAttemptsByKind, {
+      links: group?.links ?? [],
+      blockerStates: ownStates,
+    });
+
+    return { ...item, derived: deriveItemState(item, itemRows), levers: group?.levers ?? [] };
+  });
+}
+
+interface ItemGroup {
+  readonly links: LinkRow[];
+  readonly attempts: AttemptRow[];
+  readonly pullRequests: PullRequestRow[];
+  levers: LeverRow[];
+  liveLease: LeaseRow | null;
+}
+
+function collectItemGroups(rows: ItemSetRows, now: Instant): Map<ItemId, ItemGroup> {
+  const groups = new Map<ItemId, ItemGroup>(
+    rows.items.map((item) => [
+      item.id,
+      { links: [], attempts: [], pullRequests: [], levers: [], liveLease: null },
+    ]),
+  );
+
+  const attemptItems = new Map<AttemptId, ItemId>();
+
+  for (const link of rows.links) {
+    groups.get(link.target)?.links.push(link);
+  }
+
+  for (const attempt of rows.attempts) {
+    attemptItems.set(attempt.id, attempt.item);
+    groups.get(attempt.item)?.attempts.push(attempt);
+  }
+
+  for (const pullRequest of rows.pullRequests) {
+    const item = attemptItems.get(pullRequest.attempt);
+
+    if (item !== undefined) {
+      groups.get(item)?.pullRequests.push(pullRequest);
+    }
+  }
+
+  for (const lease of rows.liveLeases) {
+    const group = groups.get(lease.item);
+
+    if (group !== undefined) {
+      group.liveLease = lease;
+    }
+  }
+
+  for (const [item, group] of groups) {
+    group.levers = liveLevers(
+      rows.levers.filter((lever) => lever.item === item),
+      now,
+    );
+  }
+
+  return groups;
+}
+
+function buildItemRows(
+  item: ItemRow,
+  group: ItemGroup | undefined,
+  maxAttemptsByKind: MaxAttemptsByKind,
+  blocking: Pick<ItemRows, 'links' | 'blockerStates'>,
+): ItemRows {
+  return {
+    ...blocking,
+    levers: group?.levers ?? [],
+    attempts: group?.attempts ?? [],
+    liveLease: group?.liveLease ?? null,
+    pullRequests: group?.pullRequests ?? [],
+    maxAttempts: pickMaxAttempts(item.kind, maxAttemptsByKind),
+  };
+}
+
+function pickMaxAttempts(kind: ItemKindName, maxAttemptsByKind: MaxAttemptsByKind): number {
+  const [first] = maxAttemptsByKind.get(kind)?.values() ?? [];
+
+  return first ?? Number.POSITIVE_INFINITY;
+}

package/src/fact-schemas.ts

@@ -1,16 +1,10 @@
 import { z } from 'zod';
+import { actorRefSchema } from './actor-ref-schema.ts';
 import { brandSchemas } from './brand-schemas.ts';
 import { buildCloseOutSchema } from './build-close-out-schema.ts';
 import { frictionSchema } from './friction-schema.ts';
 import type { FactType, SliceOneFacts } from './types/facts.ts';
 
-const actorRefSchema = z.union([
-  z.literal('boxxy:owner:local'),
-  z.templateLiteral(['boxxy:runner:', brandSchemas.runnerId]),
-  z.templateLiteral(['boxxy:attempt:', brandSchemas.attemptId]),
-  z.templateLiteral(['boxxy:hook:', brandSchemas.attemptId]),
-]);
-
 const criterionSchema = z.object({
   id: brandSchemas.criterionId,
   text: z.string().min(1),
@@ -25,7 +19,7 @@ const linkPayloadSchema = z.object({
 
 const faultSchema = z.object({
   plugin: z.string().min(1),
-  kind: z.enum(['signal', 'gate', 'waiver', 'admission', 'propagation']),
+  kind: z.enum(['signal', 'gate', 'waiver', 'admission', 'propagation', 'filter-field']),
   item: brandSchemas.itemId.nullable(),
   error: z.string(),
 });

package/src/find-slot-take.ts

@@ -0,0 +1,12 @@
+import invariant from 'tiny-invariant';
+import type { RowWrite } from './types/ports.ts';
+
+export type SlotTake = Extract<RowWrite, { op: 'take-slot' }>;
+
+export function findSlotTake(writes: readonly RowWrite[]): SlotTake | null {
+  const takes = writes.filter((write): write is SlotTake => write.op === 'take-slot');
+
+  invariant(takes.length <= 1, 'a change takes one slot at most');
+
+  return takes.at(0) ?? null;
+}

package/src/format-key-path.ts

@@ -0,0 +1,19 @@
+export function formatKeyPath(segments: readonly PropertyKey[]): string {
+  return segments.map((segment, index) => formatSegment(segment, index === 0)).join('');
+}
+
+const plainKeyPattern = /^[A-Za-z_][\w-]*$/u;
+
+function formatSegment(segment: PropertyKey, isFirst: boolean): string {
+  if (typeof segment === 'number') {
+    return `[${segment}]`;
+  }
+
+  const key = String(segment);
+
+  if (!plainKeyPattern.test(key)) {
+    return `[${JSON.stringify(key)}]`;
+  }
+
+  return isFirst ? key : `.${key}`;
+}

package/src/index.ts

@@ -1,14 +1,27 @@
 export type { ContentHash, JsonValue } from '@boxxy/content-hash';
 export { brandSchemas } from './brand-schemas.ts';
+
+export {
+  buildAppliedChange,
+  type ChangeAssignments,
+  type TakenSlot,
+} from './build-applied-change.ts';
+
 export { buildCloseOutSchema } from './build-close-out-schema.ts';
+export { buildItemViews } from './build-item-views.ts';
 export { defineAdmission } from './define-admission.ts';
 export { defineGate } from './define-gate.ts';
 export { defineSignal } from './define-signal.ts';
 export { deriveItemState } from './derive-item-state.ts';
 export { factSchemas } from './fact-schemas.ts';
+export { findSlotTake, type SlotTake } from './find-slot-take.ts';
+export { formatKeyPath } from './format-key-path.ts';
 export { frictionSchema } from './friction-schema.ts';
 export { liveLevers } from './live-levers.ts';
+export { outboxFactSchema } from './outbox-fact-schema.ts';
+export { rowSchemas } from './row-schemas.ts';
 export { signalKey } from './signal-key.ts';
+export { toJSONValue } from './to-json-value.ts';
 
 export type {
   Actor,
@@ -38,6 +51,7 @@ export type {
   ItemKindName,
   ItemRow,
   ItemRows,
+  ItemSetRows,
   ItemState,
   ItemView,
   ItemWithLevers,

package/src/outbox-fact-schema.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import { actorRefSchema } from './actor-ref-schema.ts';
+import { brandSchemas } from './brand-schemas.ts';
+import type { OutboxFact } from './types/facts.ts';
+
+const idSchema = z.string();
+
+const entityRefSchema = z.union([
+  z.templateLiteral(['boxxy:item:', idSchema]),
+  z.templateLiteral(['boxxy:link:', idSchema, ':', idSchema, ':', idSchema]),
+  z.templateLiteral(['boxxy:attempt:', idSchema]),
+  z.templateLiteral(['boxxy:decision:', idSchema]),
+  z.templateLiteral(['boxxy:runner:', idSchema]),
+]);
+
+export const outboxFactSchema: z.ZodType<OutboxFact> = z.object({
+  seq: z.number().int().positive(),
+  factId: brandSchemas.factId,
+  type: z.string().min(1),
+  entity: entityRefSchema,
+  actor: actorRefSchema,
+  at: brandSchemas.instant,
+  payload: z.json(),
+  sentAt: brandSchemas.instant.nullable(),
+});

package/src/row-schemas.ts

@@ -0,0 +1,89 @@
+import { contentHashSchema } from '@boxxy/content-hash';
+import { z } from 'zod';
+import { actorRefSchema } from './actor-ref-schema.ts';
+import { brandSchemas } from './brand-schemas.ts';
+import { buildCloseOutSchema } from './build-close-out-schema.ts';
+import { factSchemas } from './fact-schemas.ts';
+import type { TableName, Tables } from './types/ports.ts';
+
+const countSchema = z.number().int().nonnegative();
+
+export const rowSchemas: { readonly [T in TableName]: z.ZodType<Tables[T]> } = {
+  items: factSchemas['boxxy.item.filed'],
+  links: z.object({
+    source: brandSchemas.itemId,
+    target: brandSchemas.itemId,
+    type: brandSchemas.linkTypeName,
+    addedBy: actorRefSchema,
+    addedAt: brandSchemas.instant,
+    removedAt: brandSchemas.instant.nullable(),
+  }),
+  levers: factSchemas['boxxy.lever.recorded'],
+  attempts: z.object({
+    id: brandSchemas.attemptId,
+    item: brandSchemas.itemId,
+    phase: brandSchemas.phaseName,
+    number: z.number().int().positive(),
+    runner: brandSchemas.runnerId,
+    recipeHash: brandSchemas.recipeHash,
+    rulesVersion: brandSchemas.rulesVersion,
+    pool: brandSchemas.poolName,
+    slot: countSchema,
+    slotGen: countSchema,
+    leaseGen: countSchema,
+    spawnRequest: z.json(),
+    spawnRequestHash: contentHashSchema,
+    state: z.enum(['starting', 'running', 'reconciling', 'succeeded', 'failed']),
+    failure: z.string().nullable(),
+    atcSession: brandSchemas.atcSessionId.nullable(),
+    closeOut: buildCloseOutSchema.nullable(),
+    claimedAt: brandSchemas.instant,
+    startedAt: brandSchemas.instant.nullable(),
+    endedAt: brandSchemas.instant.nullable(),
+  }),
+  attempt_sessions: z.object({
+    attempt: brandSchemas.attemptId,
+    agentSession: brandSchemas.agentSessionId,
+    atcSession: brandSchemas.atcSessionId,
+    seenAt: brandSchemas.instant,
+  }),
+  leases: z.object({
+    item: brandSchemas.itemId,
+    phase: brandSchemas.phaseName,
+    attempt: brandSchemas.attemptId,
+    gen: countSchema,
+    takenAt: brandSchemas.instant,
+    releasedAt: brandSchemas.instant.nullable(),
+  }),
+  pool_slots: z.object({
+    pool: brandSchemas.poolName,
+    slot: countSchema,
+    holder: brandSchemas.attemptId.nullable(),
+    gen: countSchema,
+    retired: z.boolean(),
+  }),
+  decisions: factSchemas['boxxy.decision.recorded'],
+  evidence: z.object({
+    factId: brandSchemas.factId,
+    attempt: brandSchemas.attemptId,
+    kind: z.enum(['pr', 'commit', 'test', 'ci-run', 'live-check']),
+    ref: z.string().min(1),
+    observed: z.string().nullable(),
+    source: z.enum(['hook', 'trailer', 'agent', 'watch']),
+    at: brandSchemas.instant,
+  }),
+  pull_requests: z.object({
+    repo: brandSchemas.repoName,
+    number: z.number().int().positive(),
+    attempt: brandSchemas.attemptId,
+    state: z.enum(['open', 'closed', 'merged']),
+    mergedAt: brandSchemas.instant.nullable(),
+    mergeCommit: brandSchemas.commitSha.nullable(),
+    checkedAt: brandSchemas.instant,
+  }),
+  runners: z.object({
+    id: brandSchemas.runnerId,
+    heartbeatAt: brandSchemas.instant,
+    paused: z.boolean(),
+  }),
+};

package/src/test-utils/build-mock-evidence-row.ts

@@ -0,0 +1,17 @@
+import { faker } from '@faker-js/faker';
+import { brandSchemas } from '../brand-schemas.ts';
+import type { EvidenceRow } from '../types/core.ts';
+import { buildMockFactId } from './build-mock-fact-id.ts';
+
+export function buildMockEvidenceRow(overrides: Partial<EvidenceRow> = {}): EvidenceRow {
+  return {
+    factId: buildMockFactId(),
+    attempt: brandSchemas.attemptId.parse(faker.string.uuid({ version: 7 })),
+    kind: 'test',
+    ref: faker.system.filePath(),
+    observed: null,
+    source: 'agent',
+    at: brandSchemas.instant.parse(faker.number.int({ max: 1_800_000_000_000 })),
+    ...overrides,
+  };
+}

package/src/test-utils/build-mock-fact-id.ts

@@ -0,0 +1,7 @@
+import { faker } from '@faker-js/faker';
+import { brandSchemas } from '../brand-schemas.ts';
+import type { FactId } from '../types/core.ts';
+
+export function buildMockFactId(): FactId {
+  return brandSchemas.factId.parse(`manual:${faker.string.uuid({ version: 7 })}`);
+}

package/src/test-utils/build-mock-frame-item.ts

@@ -0,0 +1,9 @@
+import { brandSchemas } from '../brand-schemas.ts';
+import type { FrameItem } from '../types/planning.ts';
+import { buildMockItemView } from './build-mock-item-view.ts';
+
+export function buildMockFrameItem(overrides: Partial<FrameItem> = {}): FrameItem {
+  const { phase, ...view } = overrides;
+
+  return { ...buildMockItemView(view), phase: phase ?? brandSchemas.phaseName.parse('build') };
+}

package/src/test-utils/build-mock-item-view.ts

@@ -0,0 +1,8 @@
+import type { ItemView } from '../types/core.ts';
+import { buildMockItemRow } from './build-mock-item-row.ts';
+
+export function buildMockItemView(overrides: Partial<ItemView> = {}): ItemView {
+  const { derived, ...row } = overrides;
+
+  return { ...buildMockItemRow(row), derived: derived ?? { state: 'ready' } };
+}

package/src/test-utils/build-mock-snapshot.ts

@@ -0,0 +1,5 @@
+import type { Snapshot } from '../types/planning.ts';
+
+export function buildMockSnapshot(overrides: Partial<Snapshot> = {}): Snapshot {
+  return { storeVersion: 1, items: [], links: [], levers: [], freeSlots: {}, ...overrides };
+}

package/src/to-json-value.ts

@@ -0,0 +1,25 @@
+import type { JsonValue } from '@boxxy/content-hash';
+import invariant from 'tiny-invariant';
+
+export function toJSONValue(value: unknown): JsonValue {
+  if (
+    value === null ||
+    typeof value === 'boolean' ||
+    typeof value === 'number' ||
+    typeof value === 'string'
+  ) {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((entry: unknown) => toJSONValue(entry));
+  }
+
+  invariant(typeof value === 'object', `a ${typeof value} has no JSON form`);
+
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([, entry]: [string, unknown]) => entry !== undefined)
+      .map(([key, entry]: [string, unknown]) => [key, toJSONValue(entry)]),
+  );
+}

package/src/types/core.ts

@@ -124,6 +124,18 @@ export interface ItemRows {
   readonly maxAttempts: number;
 }
 
+// the rows a store reads to derive the state of a set of items, with each blocking source item
+export interface ItemSetRows {
+  readonly items: readonly ItemRow[];
+
+  // live links only
+  readonly links: readonly LinkRow[];
+  readonly levers: readonly LeverRow[];
+  readonly attempts: readonly AttemptRow[];
+  readonly liveLeases: readonly LeaseRow[];
+  readonly pullRequests: readonly PullRequestRow[];
+}
+
 export type MaxAttemptsByKind = ReadonlyMap<ItemKindName, ReadonlyMap<PhaseName, number>>;
 
 export interface ItemWithLevers extends ItemView {
@@ -224,9 +236,9 @@ export interface DecisionRow {
 }
 
 export interface FaultRecord {
-  // the signal, gate or waiver name, or `propagation:<signal>:<link>`
+  // the signal, gate, waiver or filter field name, or `propagation:<signal>:<link>`
   readonly plugin: string;
-  readonly kind: 'signal' | 'gate' | 'waiver' | 'admission' | 'propagation';
+  readonly kind: 'signal' | 'gate' | 'waiver' | 'admission' | 'propagation' | 'filter-field';
   readonly item: ItemId | null;
   readonly error: string;
 }