@boxxy/model 0.1.0 → 0.1.2

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-close-out-schema.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { brandSchemas } from './brand-schemas.ts';
+import { frictionSchema } from './friction-schema.ts';
+import type { BuildCloseOut } from './types/facts.ts';
+
+const reasonSchema = z.string().min(1);
+const builtSchema = z.object({ kind: z.literal('built') });
+const blockedSchema = z.object({ kind: z.literal('blocked'), reason: reasonSchema });
+const abandonedSchema = z.object({ kind: z.literal('abandoned'), reason: reasonSchema });
+
+const citedEvidenceSchema = z.object({
+  criterion: brandSchemas.criterionId,
+  evidence: brandSchemas.factId,
+});
+
+const openItemSchema = z.object({
+  kind: z.literal('core.issue'),
+  title: z.string().min(1),
+  body: z.string(),
+});
+
+export const buildCloseOutSchema: z.ZodType<BuildCloseOut> = z.object({
+  result: z.discriminatedUnion('kind', [builtSchema, blockedSchema, abandonedSchema]),
+  criteria: z.array(citedEvidenceSchema),
+  openItems: z.array(openItemSchema),
+  friction: z.array(frictionSchema),
+  frictionDropped: z.number().int().nonnegative(),
+});

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/define-admission.ts

@@ -0,0 +1,6 @@
+import type { Admission } from './types/planning.ts';
+import type { Registered } from './types/registries.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

@@ -0,0 +1,6 @@
+import type { Gate } from './types/planning.ts';
+import type { Registered } from './types/registries.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

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

package/src/derive-item-state.ts

@@ -0,0 +1,76 @@
+import type { AttemptRow, DerivedState, ItemRow, ItemRows } from './types/core.ts';
+
+interface StateInput {
+  readonly item: ItemRow;
+  readonly rows: ItemRows;
+
+  // the succeeded and failed attempts that ended after the item's latest `item.retry` lever
+  readonly counted: readonly AttemptRow[];
+}
+
+interface StateRule {
+  readonly derived: DerivedState;
+  readonly holds: (input: StateInput) => boolean;
+}
+
+const stateRules: readonly StateRule[] = [
+  { derived: { state: 'archived' }, holds: (input) => input.item.closedAt !== null },
+  { derived: { state: 'done' }, holds: (input) => hasMergedPullRequest(input.rows) },
+  { derived: { state: 'running' }, holds: (input) => input.rows.liveLease !== null },
+  { derived: { state: 'waiting', reason: 'PR open' }, holds: hasOpenPullRequest },
+  { derived: { state: 'waiting', reason: 'no PR linked' }, holds: hasSucceededWithoutPullRequest },
+  { derived: { state: 'waiting', reason: 'attempts used up' }, holds: hasUsedUpAttempts },
+  { derived: { state: 'idea' }, holds: (input) => input.item.acceptance.length === 0 },
+  { derived: { state: 'blocked' }, holds: (input) => hasOpenBlocker(input.rows) },
+];
+
+export function deriveItemState(item: ItemRow, rows: ItemRows): DerivedState {
+  const input = { item, rows, counted: collectCountedAttempts(rows) };
+
+  return stateRules.find((rule) => rule.holds(input))?.derived ?? { state: 'ready' };
+}
+
+function collectCountedAttempts(rows: ItemRows): AttemptRow[] {
+  const retryAt = Math.max(
+    Number.NEGATIVE_INFINITY,
+    ...rows.levers.filter((lever) => lever.kind === 'item.retry').map((lever) => lever.at),
+  );
+
+  return rows.attempts.filter((attempt) => attempt.endedAt !== null && attempt.endedAt > retryAt);
+}
+
+function hasMergedPullRequest(rows: ItemRows): boolean {
+  const succeeded = new Set(collectSucceeded(rows.attempts).map((attempt) => attempt.id));
+
+  return rows.pullRequests.some((pr) => pr.state === 'merged' && succeeded.has(pr.attempt));
+}
+
+function collectSucceeded(attempts: readonly AttemptRow[]): AttemptRow[] {
+  return attempts.filter((attempt) => attempt.state === 'succeeded');
+}
+
+function hasOpenPullRequest(input: StateInput): boolean {
+  const succeeded = new Set(collectSucceeded(input.counted).map((attempt) => attempt.id));
+
+  return input.rows.pullRequests.some((pr) => pr.state === 'open' && succeeded.has(pr.attempt));
+}
+
+function hasSucceededWithoutPullRequest(input: StateInput): boolean {
+  const linked = new Set(input.rows.pullRequests.map((pr) => pr.attempt));
+
+  return collectSucceeded(input.counted).some((attempt) => !linked.has(attempt.id));
+}
+
+function hasUsedUpAttempts(input: StateInput): boolean {
+  const failed = input.counted.filter((attempt) => attempt.state === 'failed');
+
+  return failed.length >= input.rows.maxAttempts;
+}
+
+function hasOpenBlocker(rows: ItemRows): boolean {
+  return rows.links.some((link) => {
+    const blockerState = rows.blockerStates.get(link.source);
+
+    return link.type === 'blocks' && blockerState !== 'done' && blockerState !== 'archived';
+  });
+}

package/src/fact-schemas.ts

@@ -0,0 +1,132 @@
+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 criterionSchema = z.object({
+  id: brandSchemas.criterionId,
+  text: z.string().min(1),
+  evidence: z.array(brandSchemas.factId),
+});
+
+const linkPayloadSchema = z.object({
+  source: brandSchemas.itemId,
+  target: brandSchemas.itemId,
+  type: brandSchemas.linkTypeName,
+});
+
+const faultSchema = z.object({
+  plugin: z.string().min(1),
+  kind: z.enum(['signal', 'gate', 'waiver', 'admission', 'propagation', 'filter-field']),
+  item: brandSchemas.itemId.nullable(),
+  error: z.string(),
+});
+
+const copiedEvidenceSchema = z.object({
+  criterion: brandSchemas.criterionId,
+  evidence: z.array(brandSchemas.factId),
+});
+
+const pullRequestNumberSchema = z.number().int().positive();
+
+export const factSchemas: { readonly [T in FactType]: z.ZodType<SliceOneFacts[T]> } = {
+  'boxxy.item.filed': z.object({
+    id: brandSchemas.itemId,
+    kind: brandSchemas.itemKindName,
+    repo: brandSchemas.repoName,
+    title: z.string().min(1),
+    outcome: z.string().min(1),
+    acceptance: z.array(criterionSchema),
+    foundInAttempt: brandSchemas.attemptId.nullable(),
+    filedBy: actorRefSchema,
+    filedAt: brandSchemas.instant,
+    closedAt: brandSchemas.instant.nullable(),
+    closeReason: z.string().nullable(),
+  }),
+  'boxxy.item.edited': z
+    .object({
+      title: z.string().min(1).exactOptional(),
+      outcome: z.string().min(1).exactOptional(),
+      acceptance: z.array(criterionSchema).exactOptional(),
+    })
+    .refine((fields) => Object.keys(fields).length > 0, 'an edit changes at least one field'),
+  'boxxy.item.closed': z.object({ reason: z.string().min(1) }),
+  'boxxy.link.added': linkPayloadSchema,
+  'boxxy.link.removed': linkPayloadSchema,
+  'boxxy.lever.recorded': z.object({
+    seq: z.number().int().nonnegative(),
+    kind: z.templateLiteral([z.string().min(1), '.', z.string().min(1)]),
+    item: brandSchemas.itemId,
+    until: brandSchemas.instant.nullable(),
+    expiresAt: brandSchemas.instant.nullable(),
+    reason: z.string().nullable(),
+    actor: actorRefSchema,
+    at: brandSchemas.instant,
+  }),
+  'boxxy.attempt.claimed': z.object({
+    item: brandSchemas.itemId,
+    phase: brandSchemas.phaseName,
+    number: z.number().int().positive(),
+    pool: brandSchemas.poolName,
+    slot: z.number().int().nonnegative(),
+    gen: z.number().int().nonnegative(),
+    recipeHash: brandSchemas.recipeHash,
+    rulesVersion: brandSchemas.rulesVersion,
+  }),
+  'boxxy.decision.recorded': z.object({
+    id: brandSchemas.decisionId,
+    attempt: brandSchemas.attemptId,
+    item: brandSchemas.itemId,
+    pool: brandSchemas.poolName,
+    rulesVersion: brandSchemas.rulesVersion,
+    snapshotHash: brandSchemas.snapshotHash,
+    storeVersion: z.number().int().nonnegative(),
+    pepysOffsets: z.record(brandSchemas.streamName, z.number().int().nonnegative()),
+    faults: z.array(faultSchema),
+    at: brandSchemas.instant,
+  }),
+  'boxxy.attempt.started': z.object({ atcSession: brandSchemas.atcSessionId }),
+  'boxxy.attempt.reconciling': z.object({ reason: z.string().min(1) }),
+  'boxxy.attempt.reconciled': z.object({ atcSession: brandSchemas.atcSessionId }),
+  'boxxy.attempt.session_bound': z.object({
+    atcSession: brandSchemas.atcSessionId,
+    agentSession: brandSchemas.agentSessionId,
+    seenAt: brandSchemas.instant,
+  }),
+  'boxxy.attempt.closed_out': z.object({ closeOut: buildCloseOutSchema }),
+  'boxxy.attempt.settled': z.object({
+    state: z.enum(['succeeded', 'failed']),
+    failure: z.string().min(1).nullable(),
+    endedAt: brandSchemas.instant,
+    criteria: z.array(copiedEvidenceSchema),
+    matched: z.array(brandSchemas.itemId),
+    frictionDropped: z.number().int().nonnegative(),
+  }),
+  'boxxy.evidence.recorded': z.object({
+    kind: z.enum(['pr', 'commit', 'test', 'ci-run', 'live-check']),
+    ref: z.string().min(1),
+    observed: z.string().nullable(),
+  }),
+  'boxxy.evidence.pr_linked': z.object({
+    repo: brandSchemas.repoName,
+    number: pullRequestNumberSchema,
+    url: z.url(),
+  }),
+  'boxxy.evidence.commit_linked': z.object({
+    repo: brandSchemas.repoName,
+    sha: brandSchemas.commitSha,
+    pr: pullRequestNumberSchema,
+  }),
+  'boxxy.pr.merged': z.object({
+    repo: brandSchemas.repoName,
+    number: pullRequestNumberSchema,
+    mergedAt: brandSchemas.instant,
+    mergeCommit: brandSchemas.commitSha,
+  }),
+  'boxxy.pr.closed': z.object({ repo: brandSchemas.repoName, number: pullRequestNumberSchema }),
+  'boxxy.proposal.recorded': frictionSchema,
+  'boxxy.runner.paused': z.object({ runner: brandSchemas.runnerId }),
+  'boxxy.runner.resumed': z.object({ runner: brandSchemas.runnerId }),
+};

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/friction-schema.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+import type { Friction } from './types/facts.ts';
+
+export const frictionSchema: z.ZodType<Friction> = z.object({
+  target: z.object({
+    kind: z.enum(['skill', 'rule', 'lint', 'agents-md', 'tool']),
+    name: z.string().min(1),
+  }),
+  change: z.string().min(1),
+});

package/src/index.ts

@@ -1 +1,196 @@
-export { packageName } from './package-name.ts';
+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,
+  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';
+
+export type {
+  AnyNewFact,
+  ApplyResult,
+  ClaimStore,
+  Clock,
+  CostReader,
+  CostToLandInput,
+  CostToLandRow,
+  FactSink,
+  Forge,
+  ItemDetailRows,
+  ItemFilter,
+  NewId,
+  PullRequestReading,
+  RowWrite,
+  SessionFault,
+  SessionReading,
+  SpawnRequest,
+  StartOutcome,
+  StoreChange,
+  StoreReader,
+  StoreTx,
+  TableName,
+  Tables,
+  WorkerKind,
+} from './types/ports.ts';
+
+export type {
+  Concept,
+  ConceptEntry,
+  ConceptName,
+  FilterField,
+  KindRules,
+  LoadedRules,
+  LoadRejection,
+  LoadRejectionReason,
+  LoadResult,
+  ParamKindName,
+  ParamKinds,
+  Pipeline,
+  PipelineStep,
+  PlainKinds,
+  PluginKindName,
+  PluginRef,
+  Registered,
+  Registry,
+  Resolved,
+  RulesFile,
+  Schema,
+  SignalRef,
+} from './types/registries.ts';