@boxxy/model 0.1.1 → 0.1.3

package/src/pipeline/advance.ts

@@ -0,0 +1,78 @@
+import invariant from 'tiny-invariant';
+import type { Edge, Pipeline } from '../rules/types.ts';
+import { countTrailing } from './count-trailing.ts';
+import { findStep } from './find-step.ts';
+import type { Position, Settled } from './types.ts';
+
+interface AdvanceInput {
+  readonly pipeline: Pipeline;
+  readonly settled: Settled;
+
+  // the attempts settled before this one and after the item's latest retry lever
+  readonly counted: readonly Settled[];
+
+  // the item's round before this attempt's edge
+  readonly round: number;
+}
+
+// One step of the engine. `lost` acts as `again`. `unsettleable` has no entry in `on` under any
+// rules file, so it always reaches the `outcome not in rules` hold.
+export function advance(input: AdvanceInput): Position {
+  const step = findStep(input.pipeline, input.settled.phase);
+
+  invariant(step !== undefined, 'the settled attempt must belong to a step of the pipeline');
+
+  const round = input.round;
+
+  const edge: Edge | undefined =
+    input.settled.outcome === 'lost' ? 'again' : step.on[input.settled.outcome];
+
+  if (edge === undefined) {
+    // oxlint-disable-next-line unicorn/no-thenable -- `then` names the phase a hold resumes; the object is never awaited
+    return { kind: 'hold', reason: 'outcome not in rules', then: step.phase, round };
+  }
+
+  if (edge === 'next') {
+    const following = input.pipeline.steps[input.pipeline.steps.indexOf(step) + 1];
+
+    return following === undefined
+      ? { kind: 'end', reason: 'pipeline-done' }
+      : { kind: 'phase', phase: following.phase, round };
+  }
+
+  if (edge === 'again') {
+    const inARow =
+      1 +
+      countTrailing(
+        input.counted,
+        (earlier) =>
+          earlier.outcome === 'lost' ||
+          findStep(input.pipeline, earlier.phase)?.on[earlier.outcome] === 'again',
+      );
+
+    return inARow >= step.maxAttempts
+      ? // oxlint-disable-next-line unicorn/no-thenable -- `then` names the phase a hold resumes; the object is never awaited
+        { kind: 'hold', reason: 'attempts used up', then: step.phase, round }
+      : { kind: 'phase', phase: step.phase, round };
+  }
+
+  if ('end' in edge) {
+    return { kind: 'end', reason: edge.end };
+  }
+
+  if ('hold' in edge) {
+    // oxlint-disable-next-line unicorn/no-thenable -- `then` names the phase a hold resumes; the object is never awaited
+    return { kind: 'hold', reason: edge.hold, then: step.phase, round };
+  }
+
+  const taken =
+    1 +
+    input.counted.filter(
+      (earlier) => earlier.phase === step.phase && earlier.outcome === input.settled.outcome,
+    ).length;
+
+  return edge.max !== undefined && taken > edge.max
+    ? // oxlint-disable-next-line unicorn/no-thenable -- `then` names the phase a hold resumes; the object is never awaited
+      { kind: 'hold', reason: 'rounds used up', then: edge.to, round }
+    : { kind: 'phase', phase: edge.to, round: round + 1 };
+}

package/src/pipeline/constants.ts

@@ -0,0 +1,12 @@
+import type { EngineOutcome } from '../types.ts';
+import type { HoldReason } from './types.ts';
+
+// the outcomes that only the engine writes; a phase kind lists neither
+export const engineOutcomes = ['lost', 'unsettleable'] as const satisfies readonly EngineOutcome[];
+
+// the holds that only the engine gives; the rules name none of them, so a report can tell the two apart
+export const engineHoldReasons = [
+  'attempts used up',
+  'rounds used up',
+  'outcome not in rules',
+] as const satisfies readonly HoldReason[];

package/src/pipeline/count-trailing.ts

@@ -0,0 +1,16 @@
+// how many items at the end of the list pass the test, counting back until one fails
+export function countTrailing<T>(list: readonly T[], test: (item: T) => boolean): number {
+  let count = 0;
+
+  for (let index = list.length - 1; index >= 0; index -= 1) {
+    const item = list[index];
+
+    if (item === undefined || !test(item)) {
+      break;
+    }
+
+    count += 1;
+  }
+
+  return count;
+}

package/src/pipeline/find-position.ts

@@ -0,0 +1,74 @@
+import type { Pipeline } from '../rules/types.ts';
+import type { PhaseName } from '../types.ts';
+import { advance } from './advance.ts';
+import { findStep } from './find-step.ts';
+import { mergeByTime } from './merge-by-time.ts';
+import type { Position, RetryLever, Settled } from './types.ts';
+
+interface FindPositionInput {
+  // the pipeline of the item's kind in the rules loaded now; null when the kind has none
+  readonly pipeline: Pipeline | null;
+
+  // the item's settled attempts, oldest first
+  readonly attempts: readonly Settled[];
+
+  // the item's `item.retry` levers, oldest first
+  readonly retries: readonly RetryLever[];
+}
+
+export function findPosition(input: FindPositionInput): Position {
+  const pipeline = input.pipeline;
+  const first = pipeline?.steps[0];
+
+  if (pipeline === null || first === undefined) {
+    return { kind: 'end', reason: 'no-pipeline' };
+  }
+
+  let position: Position = { kind: 'phase', phase: first.phase, round: 1 };
+  let counted: Settled[] = [];
+  let round = 1;
+
+  for (const event of mergeByTime(input.attempts, input.retries)) {
+    if (event.kind === 'retry') {
+      counted = [];
+
+      const phase: PhaseName | null = event.lever.phase ?? pickResumePhase(position);
+
+      if (phase !== null && findStep(pipeline, phase) !== undefined) {
+        const startsNewRound =
+          event.lever.phase !== null ||
+          (position.kind === 'hold' && position.reason === 'rounds used up');
+
+        round += startsNewRound ? 1 : 0;
+        position = { kind: 'phase', phase, round };
+      }
+
+      continue;
+    }
+
+    const settled = event.settled;
+
+    if (settled.failure === 'no-capacity' || settled.failure === 'usage-limit') {
+      continue;
+    }
+
+    if (findStep(pipeline, settled.phase) === undefined) {
+      continue;
+    }
+
+    position = advance({ pipeline, settled, counted, round });
+    round = position.kind === 'end' ? round : position.round;
+
+    counted.push(settled);
+  }
+
+  return position;
+}
+
+function pickResumePhase(position: Position): PhaseName | null {
+  if (position.kind === 'end') {
+    return null;
+  }
+
+  return position.kind === 'hold' ? position.then : position.phase;
+}

package/src/pipeline/find-step.ts

@@ -0,0 +1,6 @@
+import type { Pipeline, PipelineStep } from '../rules/types.ts';
+import type { PhaseName } from '../types.ts';
+
+export function findStep(pipeline: Pipeline, phase: PhaseName): PipelineStep | undefined {
+  return pipeline.steps.find((step) => step.phase === phase);
+}

package/src/pipeline/merge-by-time.ts

@@ -0,0 +1,33 @@
+import type { RetryLever, Settled } from './types.ts';
+
+export type TimedEvent =
+  | { readonly kind: 'settled'; readonly settled: Settled }
+  | { readonly kind: 'retry'; readonly lever: RetryLever };
+
+// Both inputs are oldest first. At equal times a settled attempt comes before a retry lever, so a
+// lever filed at the instant an attempt ended acts on the position that attempt gave.
+export function mergeByTime(
+  attempts: readonly Settled[],
+  retries: readonly RetryLever[],
+): TimedEvent[] {
+  const events: TimedEvent[] = [];
+  let attemptIndex = 0;
+  let retryIndex = 0;
+
+  while (attemptIndex < attempts.length || retryIndex < retries.length) {
+    const settled = attempts[attemptIndex];
+    const lever = retries[retryIndex];
+
+    if (settled !== undefined && (lever === undefined || settled.endedAt <= lever.at)) {
+      events.push({ kind: 'settled', settled });
+
+      attemptIndex += 1;
+    } else if (lever !== undefined) {
+      events.push({ kind: 'retry', lever });
+
+      retryIndex += 1;
+    }
+  }
+
+  return events;
+}

package/src/pipeline/position-schema.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import type { Position } from './types.ts';
+
+const holdReasonSchema = z.union([
+  z.literal('attempts used up'),
+  z.literal('rounds used up'),
+  z.literal('outcome not in rules'),
+  brandSchemas.rulesHoldReason,
+]);
+
+export const positionSchema: z.ZodType<Position> = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('phase'),
+    phase: brandSchemas.phaseName,
+    round: z.number().int().positive(),
+  }),
+  z.object({ kind: z.literal('end'), reason: z.string() }),
+  z.object({
+    kind: z.literal('hold'),
+    reason: holdReasonSchema,
+
+    // oxlint-disable-next-line unicorn/no-thenable -- `then` names the phase that the hold resumes; the object is never awaited
+    then: brandSchemas.phaseName,
+    round: z.number().int().positive(),
+  }),
+]);

package/src/pipeline/types.ts

@@ -0,0 +1,47 @@
+import type { z } from 'zod';
+import type { brandSchemas } from '../rows/brand-schemas.ts';
+import type { Instant, PhaseName } from '../types.ts';
+
+// Where an item stands. The engine derives it on every read from the item's settled attempts,
+// its retry levers and the rules loaded now; no row stores it. `round` is the item's round: 1,
+// then one higher each time a backward edge or `item.retry --phase` sends the item back.
+export type Position =
+  | { readonly kind: 'phase'; readonly phase: PhaseName; readonly round: number }
+
+  // `reviewed`, `pipeline-done` or `no-pipeline`
+  | { readonly kind: 'end'; readonly reason: string }
+  | {
+      readonly kind: 'hold';
+      readonly reason: HoldReason;
+      readonly then: PhaseName;
+      readonly round: number;
+    };
+
+export type HoldReason =
+  | 'attempts used up'
+  | 'rounds used up'
+  | 'outcome not in rules'
+  | RulesHoldReason;
+
+// the reason that a `{ hold: reason }` edge of the rules names, such as `declined`
+export type RulesHoldReason = z.output<typeof brandSchemas.rulesHoldReason>;
+
+// What the engine reads of one settled attempt.
+export interface Settled {
+  readonly phase: PhaseName;
+
+  // a phase outcome, or an engine outcome (`lost`, `unsettleable`)
+  readonly outcome: string;
+  readonly endedAt: Instant;
+
+  // An attempt that failed with `no-capacity` or `usage-limit` neither moves the item nor
+  // counts. Optional, so that a test's settled attempt may leave it out.
+  readonly failure?: string | null;
+}
+
+export interface RetryLever {
+  readonly at: Instant;
+
+  // `boxxy item retry <item> --phase build`; null: the hold's `then`, or the position as it stands
+  readonly phase: PhaseName | null;
+}

package/src/{define-admission.ts → planning/define-admission.ts}

@@ -1,5 +1,5 @@
-import type { Admission } from './types/planning.ts';
-import type { Registered } from './types/registries.ts';
+import type { Registered } from '../rules/types.ts';
+import type { Admission } from './types.ts';
 
 export function defineAdmission<P>(admission: Admission<P>): Registered<'admission'> {
   return { kind: 'admission', name: admission.name, open: (use) => use(admission) };

package/src/{define-gate.ts → planning/define-gate.ts}

@@ -1,5 +1,5 @@
-import type { Gate } from './types/planning.ts';
-import type { Registered } from './types/registries.ts';
+import type { Registered } from '../rules/types.ts';
+import type { Gate } from './types.ts';
 
 export function defineGate<P>(gate: Gate<P>): Registered<'gate'> {
   return { kind: 'gate', name: gate.name, open: (use) => use(gate) };

package/src/{define-signal.ts → planning/define-signal.ts}

@@ -1,5 +1,5 @@
-import type { Signal } from './types/planning.ts';
-import type { Registered } from './types/registries.ts';
+import type { Registered } from '../rules/types.ts';
+import type { Signal } from './types.ts';
 
 export function defineSignal<P>(signal: Signal<P>): Registered<'signal'> {
   return { kind: 'signal', name: signal.name, open: (use) => use(signal) };

package/src/planning/is-filter-match.ts

@@ -0,0 +1,10 @@
+import type { FieldValues } from '../types.ts';
+import type { Filter } from './types.ts';
+
+// For every field of the filter, one of the values is in the filter's list; an empty filter
+// matches every value set.
+export function isFilterMatch(filter: Filter, fields: FieldValues): boolean {
+  return Object.entries(filter).every(([field, accepted]) =>
+    (fields[field] ?? []).some((value) => accepted.includes(value)),
+  );
+}

package/src/planning/limit-fill-schema.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import type { LimitFill } from './types.ts';
+
+const filterSchema = z.record(z.string(), z.array(z.string()));
+
+export const limitFillSchema: z.ZodType<LimitFill> = z.object({
+  name: brandSchemas.limitName,
+  max: z.number().int().nonnegative(),
+  counts: filterSchema,
+  held: z.number().int().nonnegative(),
+});

package/src/{signal-key.ts → planning/signal-key.ts}

@@ -1,6 +1,6 @@
 import type { JsonValue } from '@boxxy/content-hash';
 import { contentHash } from '@boxxy/content-hash';
-import type { SignalKey, SignalName } from './types/planning.ts';
+import type { SignalKey, SignalName } from './types.ts';
 
 export function signalKey(name: SignalName, params: JsonValue): SignalKey {
   return `${name}#${contentHash(params)}`;

package/src/planning/types.ts

@@ -0,0 +1,216 @@
+import type { Schema } from '../rules/types.ts';
+import type {
+  AttemptId,
+  FaultRecord,
+  FieldValues,
+  Instant,
+  ItemId,
+  ItemView,
+  LeverRow,
+  LimitName,
+  PhaseName,
+  PoolName,
+  RelationRow,
+  RelationTypeName,
+} from '../types.ts';
+
+export type SignalName = string;
+
+export type GateName = string;
+
+export type WaiverName = string;
+
+export type AdmissionName = string;
+
+export type ViewName = string;
+
+export type SignalKey = `${SignalName}#${string}`;
+
+// A field name and the values that match it. An item matches when, for every field, one of its
+// values is in the list.
+export type Filter = Readonly<Record<string, readonly string[]>>;
+
+export interface Limit {
+  readonly name: LimitName;
+  readonly max: number;
+  readonly counts: Filter;
+}
+
+export interface LimitFill extends Limit {
+  readonly held: number;
+}
+
+export interface Pool {
+  readonly name: PoolName;
+  readonly takes: Filter;
+
+  // `lead`, then the pool's own `order`: lower first, no value last, then item id
+  readonly order: readonly SignalKey[];
+}
+
+export interface Snapshot {
+  readonly storeVersion: number;
+
+  // every item not yet done and not archived, with its state and position derived at `now`
+  readonly items: readonly ItemView[];
+  readonly relations: readonly RelationRow[];
+  readonly levers: readonly LeverRow[];
+  readonly limits: readonly LimitFill[];
+
+  // the sleeping attempts whose wake was asked for, oldest request first
+  readonly wakes: readonly Wake[];
+}
+
+export interface Wake {
+  readonly attempt: AttemptId;
+  readonly item: ItemId;
+  readonly phase: PhaseName;
+
+  // the attempt's pool: a pool in backoff holds back its wakes as well as its starts
+  readonly pool: PoolName;
+
+  // the attempt's stored fields, which the limits are matched against again
+  readonly fields: FieldValues;
+  readonly requestedAt: Instant;
+}
+
+// no member stops a running attempt
+export type Pick = StartPick | WakePick;
+
+export interface StartPick {
+  readonly kind: 'start';
+  readonly item: ItemId;
+  readonly phase: PhaseName;
+  readonly round: number;
+  readonly pool: PoolName;
+  readonly fields: FieldValues;
+  readonly limits: readonly LimitName[];
+}
+
+export interface WakePick {
+  readonly kind: 'wake';
+  readonly attempt: AttemptId;
+  readonly limits: readonly LimitName[];
+}
+
+// An item or a wake that `decide` passed over, with the reason.
+export interface Wait {
+  readonly subject:
+    | { readonly kind: 'item'; readonly item: ItemId }
+    | { readonly kind: 'wake'; readonly attempt: AttemptId };
+  readonly reason: WaitReason;
+}
+
+export type WaitReason =
+  | { readonly kind: 'limit-full'; readonly limit: LimitName }
+  | { readonly kind: 'backoff'; readonly pool: PoolName }
+  | { readonly kind: 'no-pool' };
+
+export interface Decision {
+  // wakes first, then in pool order and by each pool's `order`
+  readonly picks: readonly Pick[];
+  readonly waits: readonly Wait[];
+}
+
+// One seat of a limit that an attempt holds. A fact names the seats an attempt took.
+export interface SeatRef {
+  readonly limit: LimitName;
+}
+
+export interface SeatTake {
+  readonly limits: readonly LimitName[];
+  readonly attempt: AttemptId;
+  readonly holdGen: number;
+
+  // take each seat past the limit's `max`, for a wake over the cap
+  readonly overCap: boolean;
+}
+
+export interface SeatRelease {
+  readonly attempt: AttemptId;
+  readonly holdGen: number;
+}
+
+// A ready item whose position is a phase, with that phase and the item's round.
+export interface FrameItem extends ItemView {
+  readonly phase: PhaseName;
+  readonly round: number;
+}
+
+export interface Frame {
+  // the open items in state `ready`, the only items decide picks
+  candidates: FrameItem[];
+  fields: Map<ItemId, Readonly<Record<string, readonly string[]>>>;
+  values: Map<SignalKey, Map<ItemId, number>>;
+  holds: Map<ItemId, Hold[]>;
+  lifted: Map<ItemId, Lift[]>;
+  faults: Fault[];
+}
+
+export type FrameValues = ReadonlyMap<SignalKey, ReadonlyMap<ItemId, number>>;
+
+export interface Hold {
+  readonly gate: GateName;
+  readonly reason: string;
+  readonly until?: Instant;
+}
+
+export interface Lift {
+  readonly waiver: WaiverName;
+  readonly gate: GateName;
+  readonly reason: string;
+}
+
+export type Fault = FaultRecord;
+
+export interface PlanContext {
+  now: Instant;
+  levers: readonly LeverRow[];
+  relations: readonly RelationRow[];
+  values: FrameValues;
+}
+
+export interface Signal<P> {
+  name: SignalName;
+  params: Schema<P>;
+
+  // null is no opinion
+  value: (item: ItemView, ctx: PlanContext, params: P) => number | null;
+  combine?: (left: number, right: number) => number;
+}
+
+export interface Gate<P> {
+  name: GateName;
+  liftable: boolean;
+  params: Schema<P>;
+  hold: (item: FrameItem, ctx: PlanContext, params: P) => Hold | null;
+}
+
+export interface Waiver {
+  name: WaiverName;
+  lifts: GateName;
+  lift: (item: FrameItem, hold: Hold, ctx: PlanContext) => Lift | null;
+}
+
+export interface Admission<P> {
+  name: AdmissionName;
+  params: Schema<P>;
+  admit: (item: FrameItem, ctx: PlanContext, params: P) => AdmissionGrant | null;
+}
+
+export interface AdmissionGrant {
+  readonly admission: AdmissionName;
+  readonly pools: readonly PoolName[] | 'any';
+  readonly reason: string;
+}
+
+export interface View<I = unknown, O = unknown> {
+  name: ViewName;
+  render: (frame: Frame, input: I) => O;
+}
+
+export interface PropagationLine {
+  readonly value: SignalName;
+  readonly over: RelationTypeName;
+  readonly toward: 'source' | 'target';
+}