@boxxy/model 0.0.0 → 0.1.1

package/src/fact-schemas.ts

@@ -0,0 +1,138 @@
+import { z } from 'zod';
+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),
+  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']),
+  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/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,182 @@
-export { packageName } from './package-name.ts';
+export type { ContentHash, JsonValue } from '@boxxy/content-hash';
+export { brandSchemas } from './brand-schemas.ts';
+export { buildCloseOutSchema } from './build-close-out-schema.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 { frictionSchema } from './friction-schema.ts';
+export { liveLevers } from './live-levers.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 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';

package/src/live-levers.ts

@@ -0,0 +1,22 @@
+import type { Instant, LeverKind, LeverRow } from './types/core.ts';
+
+export function liveLevers(levers: readonly LeverRow[], now: Instant): LeverRow[] {
+  return levers.filter((lever) => !isExpired(lever, now) && !isUndone(lever, levers));
+}
+
+function isExpired(lever: LeverRow, now: Instant): boolean {
+  return lever.expiresAt !== null && lever.expiresAt <= now;
+}
+
+const undoKinds: ReadonlyMap<LeverKind, LeverKind> = new Map([
+  ['plan.defer', 'plan.undefer'],
+  ['plan.expedite', 'plan.unexpedite'],
+]);
+
+function isUndone(lever: LeverRow, levers: readonly LeverRow[]): boolean {
+  const undoKind = undoKinds.get(lever.kind);
+
+  return levers.some(
+    (later) => later.item === lever.item && later.kind === undoKind && later.seq > lever.seq,
+  );
+}

package/src/signal-key.ts

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

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

@@ -0,0 +1,37 @@
+import { contentHash } from '@boxxy/content-hash';
+import { faker } from '@faker-js/faker';
+import { brandSchemas } from '../brand-schemas.ts';
+import type { AttemptRow } from '../types/core.ts';
+
+const hashOptions = { length: 64, casing: 'lower', prefix: '' } as const;
+
+export function buildMockAttemptRow(overrides: Partial<AttemptRow> = {}): AttemptRow {
+  const spawnRequest =
+    overrides.spawnRequest === undefined
+      ? { prompt: faker.lorem.sentence() }
+      : overrides.spawnRequest;
+
+  return {
+    id: brandSchemas.attemptId.parse(faker.string.uuid({ version: 7 })),
+    item: brandSchemas.itemId.parse(faker.string.uuid({ version: 7 })),
+    phase: brandSchemas.phaseName.parse('build'),
+    number: 1,
+    runner: brandSchemas.runnerId.parse('runner-1'),
+    recipeHash: brandSchemas.recipeHash.parse(faker.string.hexadecimal(hashOptions)),
+    rulesVersion: brandSchemas.rulesVersion.parse(faker.string.hexadecimal(hashOptions)),
+    pool: brandSchemas.poolName.parse('build'),
+    slot: 1,
+    slotGen: 1,
+    leaseGen: 1,
+    spawnRequest,
+    spawnRequestHash: contentHash(spawnRequest),
+    state: 'succeeded',
+    failure: null,
+    atcSession: brandSchemas.atcSessionId.parse(faker.string.uuid()),
+    closeOut: null,
+    claimedAt: brandSchemas.instant.parse(faker.number.int({ max: 1_800_000_000_000 })),
+    startedAt: brandSchemas.instant.parse(faker.number.int({ max: 1_800_000_000_000 })),
+    endedAt: brandSchemas.instant.parse(faker.number.int({ max: 1_800_000_000_000 })),
+    ...overrides,
+  };
+}

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

@@ -0,0 +1,22 @@
+import { faker } from '@faker-js/faker';
+import { brandSchemas } from '../brand-schemas.ts';
+import type { ItemRow } from '../types/core.ts';
+
+export function buildMockItemRow(overrides: Partial<ItemRow> = {}): ItemRow {
+  return {
+    id: brandSchemas.itemId.parse(faker.string.uuid({ version: 7 })),
+    kind: brandSchemas.itemKindName.parse('core.issue'),
+    repo: brandSchemas.repoName.parse(`${faker.string.alpha(8)}/${faker.string.alpha(8)}`),
+    title: faker.lorem.sentence(),
+    outcome: faker.lorem.sentence(),
+    acceptance: [
+      { id: brandSchemas.criterionId.parse('a1'), text: faker.lorem.sentence(), evidence: [] },
+    ],
+    foundInAttempt: null,
+    filedBy: 'boxxy:owner:local',
+    filedAt: brandSchemas.instant.parse(faker.number.int({ max: 1_800_000_000_000 })),
+    closedAt: null,
+    closeReason: null,
+    ...overrides,
+  };
+}

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

@@ -0,0 +1,14 @@
+import type { ItemRows } from '../types/core.ts';
+
+export function buildMockItemRows(overrides: Partial<ItemRows> = {}): ItemRows {
+  return {
+    links: [],
+    blockerStates: new Map(),
+    levers: [],
+    attempts: [],
+    liveLease: null,
+    pullRequests: [],
+    maxAttempts: 2,
+    ...overrides,
+  };
+}

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

@@ -0,0 +1,15 @@
+import { faker } from '@faker-js/faker';
+import { brandSchemas } from '../brand-schemas.ts';
+import type { LeaseRow } from '../types/core.ts';
+
+export function buildMockLeaseRow(overrides: Partial<LeaseRow> = {}): LeaseRow {
+  return {
+    item: brandSchemas.itemId.parse(faker.string.uuid({ version: 7 })),
+    phase: brandSchemas.phaseName.parse('build'),
+    attempt: brandSchemas.attemptId.parse(faker.string.uuid({ version: 7 })),
+    gen: 1,
+    takenAt: brandSchemas.instant.parse(faker.number.int({ max: 1_800_000_000_000 })),
+    releasedAt: null,
+    ...overrides,
+  };
+}

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

@@ -0,0 +1,17 @@
+import { faker } from '@faker-js/faker';
+import { brandSchemas } from '../brand-schemas.ts';
+import type { LeverRow } from '../types/core.ts';
+
+export function buildMockLeverRow(overrides: Partial<LeverRow> = {}): LeverRow {
+  return {
+    seq: faker.number.int({ min: 1, max: 10_000 }),
+    kind: 'plan.defer',
+    item: brandSchemas.itemId.parse(faker.string.uuid({ version: 7 })),
+    until: null,
+    expiresAt: null,
+    reason: faker.lorem.sentence(),
+    actor: 'boxxy:owner:local',
+    at: brandSchemas.instant.parse(faker.number.int({ max: 1_800_000_000_000 })),
+    ...overrides,
+  };
+}

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

@@ -0,0 +1,15 @@
+import { faker } from '@faker-js/faker';
+import { brandSchemas } from '../brand-schemas.ts';
+import type { LinkRow } from '../types/core.ts';
+
+export function buildMockLinkRow(overrides: Partial<LinkRow> = {}): LinkRow {
+  return {
+    source: brandSchemas.itemId.parse(faker.string.uuid({ version: 7 })),
+    target: brandSchemas.itemId.parse(faker.string.uuid({ version: 7 })),
+    type: brandSchemas.linkTypeName.parse('blocks'),
+    addedBy: 'boxxy:owner:local',
+    addedAt: brandSchemas.instant.parse(faker.number.int({ max: 1_800_000_000_000 })),
+    removedAt: null,
+    ...overrides,
+  };
+}

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

@@ -0,0 +1,16 @@
+import { faker } from '@faker-js/faker';
+import { brandSchemas } from '../brand-schemas.ts';
+import type { PullRequestRow } from '../types/core.ts';
+
+export function buildMockPullRequestRow(overrides: Partial<PullRequestRow> = {}): PullRequestRow {
+  return {
+    repo: brandSchemas.repoName.parse(`${faker.string.alpha(8)}/${faker.string.alpha(8)}`),
+    number: faker.number.int({ min: 1, max: 10_000 }),
+    attempt: brandSchemas.attemptId.parse(faker.string.uuid({ version: 7 })),
+    state: 'open',
+    mergedAt: null,
+    mergeCommit: null,
+    checkedAt: brandSchemas.instant.parse(faker.number.int({ max: 1_800_000_000_000 })),
+    ...overrides,
+  };
+}

package/src/test-utils/seed-faker.ts

@@ -0,0 +1,3 @@
+import { faker } from '@faker-js/faker';
+
+faker.seed(1);