@boxxy/model 0.1.8 → 0.2.0

package/dist/facts/types.d.ts

@@ -87,7 +87,9 @@ export interface WorkFacts {
         readonly skillsRef: CommitSha | null;
         readonly rulesVersion: RulesVersion;
     };
-    'boxxy.decision.recorded': DecisionRow;
+    'boxxy.decision.recorded': Omit<DecisionRow, 'storeVersion'> & {
+        readonly snapshotStoreVersion: number;
+    };
     'boxxy.attempt.started': OfAttempt & {
         readonly atcSession: AtcSessionId;
         readonly resumeFallback: boolean;

package/dist/facts/work-fact-schemas.d.ts

@@ -99,7 +99,6 @@ export declare const workFactSchemas: {
         pool: z.core.$ZodBranded<z.ZodString, "PoolName", "out">;
         rulesVersion: z.core.$ZodBranded<z.core.$ZodBranded<z.ZodString, "ContentHash", "out">, "RulesVersion", "out">;
         snapshotHash: z.core.$ZodBranded<z.core.$ZodBranded<z.ZodString, "ContentHash", "out">, "SnapshotHash", "out">;
-        storeVersion: z.ZodNumber;
         pepysOffsets: z.ZodRecord<z.core.$ZodBranded<z.ZodString, "StreamName", "out">, z.ZodNumber>;
         faults: z.ZodArray<z.ZodObject<{
             plugin: z.ZodString;
@@ -120,6 +119,7 @@ export declare const workFactSchemas: {
             max: z.ZodNumber;
         }, z.core.$strip>>;
         at: z.core.$ZodBranded<z.ZodNumber, "Instant", "out">;
+        snapshotStoreVersion: z.ZodNumber;
     }, z.core.$strip>;
     'boxxy.attempt.started': z.ZodObject<{
         attempt: z.core.$ZodBranded<z.ZodString, "AttemptId", "out">;

package/dist/index.d.ts

@@ -58,7 +58,7 @@ export type { AcceptanceInput, BuildCloseOut, BuildInput, CloseOut, CloseOutAnsw
 export type { Claim } from './dispatch/types.ts';
 export type { AnyNewFact, EntityRef, FactEnvelope, FactType, NewFact, OutboxFact, RelationPayload, WorkFacts, } from './facts/types.ts';
 export type { Admission, AdmissionGrant, AdmissionName, Decision, Fault, Filter, Frame, FrameItem, FrameValues, Gate, GateName, Hold, Lift, Limit, LimitFill, Pick, PlanContext, Pool, PropagationLine, SeatRef, SeatRelease, SeatTake, Signal, SignalKey, SignalName, Snapshot, StartPick, View, ViewName, Wait, WaitReason, Waiver, WaiverName, Wake, WakePick, } from './planning/types.ts';
-export type { ApplyResult, Attention, CallerProof, CapacityBackoff, ClaimStore, Clock, FactSink, ForgetOutcome, Forge, GitSource, HoldNotice, ItemDetailRows, ItemFilter, NewId, NoticeOutcome, Notifier, OutboxReader, PepysAnswer, PepysReader, SinkAnswer, PullRequestReading, RowWrite, SessionFault, SessionReading, SpawnRequest, StartOutcome, StopOutcome, StoreChange, StoreReader, StoreTx, SuspendOutcome, TableName, Tables, WakeSource, WorkerKind, } from './ports/types.ts';
+export type { ApplyResult, Attention, CallerProof, CapacityBackoff, ClaimStore, Clock, FactSink, ForgetOutcome, Forge, GitSource, HoldNotice, ItemDetailRows, ItemFilter, NewId, NoticeOutcome, NoticeTryUpdate, Notifier, OutboxReader, PepysAnswer, PepysReader, SinkAnswer, PullRequestReading, RowWrite, RunnerFault, SessionFault, SessionReading, SpawnRequest, StartOutcome, StopOutcome, StoreChange, StoreReader, StoreTx, SuspendOutcome, TableName, Tables, WakeSource, WorkerKind, WorkerRefusal, } from './ports/types.ts';
 export type { CostToLand, StageTime } from './reports/types.ts';
 export type { OutboxStatus } from './reports/outbox-status.ts';
 export type { ItemSetRows, ItemWithLevers } from './items/types.ts';

package/dist/ports/types.d.ts

@@ -32,6 +32,7 @@ export interface StoreReader extends OutboxReader {
     listLimitSeats: () => Promise<LimitSeatRow[]>;
     listItemNotes: (item: ItemId) => Promise<NoteRow[]>;
     listUnsentNotices: (limit: number) => Promise<NoticeRow[]>;
+    listNoticesDue: (now: Instant, limit: number) => Promise<NoticeRow[]>;
     listKeptSessions: () => Promise<{
         readonly item: ItemId;
         readonly kept: KeptSession;
@@ -67,7 +68,7 @@ export interface StoreTx extends StoreReader {
     writeHeartbeat: (runner: RunnerId, at: Instant) => Promise<void>;
     syncLimits: (limits: readonly Limit[], at: Instant) => Promise<void>;
     markPullRequestChecked: (ref: PullRequestRef, at: Instant) => Promise<void>;
-    markNoticeTried: (id: number, at: Instant, sent: boolean) => Promise<void>;
+    markNoticeTried: (id: number, update: NoticeTryUpdate) => Promise<void>;
 }
 export interface StoreChange {
     readonly at: Instant;
@@ -204,6 +205,9 @@ export type Attention = 'working' | 'needs-input' | 'turn-ended';
 export interface GitSource {
     readonly url: string;
     readonly ref: string;
+    readonly credentialRef?: {
+        readonly name: string;
+    };
 }
 export type SpawnRequest = SpawnRequestFields & ({
     readonly cwd: string;
@@ -227,13 +231,23 @@ export interface HoldNotice {
     readonly item: ItemId;
     readonly reason: HoldReason;
     readonly at: Instant;
+    readonly key: string;
 }
 export type NoticeOutcome = {
     readonly kind: 'sent';
 } | {
-    readonly kind: 'failed';
+    readonly kind: 'refused';
+    readonly reason: string;
+} | {
+    readonly kind: 'uncertain';
     readonly reason: string;
 };
+export interface NoticeTryUpdate {
+    readonly sentAt: Instant | null;
+    readonly keySeq: number;
+    readonly keyTries: number;
+    readonly nextTryAt: Instant;
+}
 export interface CallerProof {
     prove: (request: Request) => Promise<CallerIdentity | null>;
 }
@@ -248,6 +262,15 @@ export interface SessionFault {
     readonly attempt: AttemptId;
     readonly holder: AttemptId;
 }
+export interface WorkerRefusal {
+    readonly kind: 'fault';
+    readonly fault: 'spawn-refused' | 'wake-refused';
+    readonly attempt: AttemptId;
+    readonly item: ItemId;
+    readonly cause: 'capacity' | 'other';
+    readonly reason: string;
+}
+export type RunnerFault = SessionFault | WorkerRefusal;
 export type SinkAnswer = {
     readonly kind: 'stored';
 } | {

package/dist/test-utils/create-fake-notifier.d.ts

@@ -1,9 +1,14 @@
-import type { HoldNotice, Notifier } from '../ports/types.ts';
+import type { HoldNotice, NoticeOutcome, Notifier } from '../ports/types.ts';
 export interface FakeNotifier extends Notifier {
     readonly told: readonly HoldNotice[];
+    readonly attempts: readonly HoldNotice[];
     readonly calls: () => number;
-    failNext: (reason: string) => void;
-    failAlways: (reason: string) => void;
+    failNext: (outcome: Exclude<NoticeOutcome, {
+        kind: 'sent';
+    }>) => void;
+    failAlways: (outcome: Exclude<NoticeOutcome, {
+        kind: 'sent';
+    }>) => void;
     recover: () => void;
 }
 export declare function createFakeNotifier(): FakeNotifier;

package/dist/types.d.ts

@@ -261,6 +261,9 @@ export interface NoticeRow {
     readonly at: Instant;
     readonly tries: number;
     readonly sentAt: Instant | null;
+    readonly keySeq: number;
+    readonly keyTries: number;
+    readonly nextTryAt: Instant;
 }
 export type Effort = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 export interface Recipe {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boxxy/model",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "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",
@@ -31,7 +31,7 @@
     "typecheck": "tsrs --noEmit"
   },
   "dependencies": {
-    "@boxxy/content-hash": "0.1.8",
+    "@boxxy/content-hash": "0.2.0",
     "tiny-invariant": "1.3.3",
     "zod": "4.6.7"
   },

package/src/facts/types.ts

@@ -133,7 +133,11 @@ export interface WorkFacts {
     readonly skillsRef: CommitSha | null;
     readonly rulesVersion: RulesVersion;
   };
-  'boxxy.decision.recorded': DecisionRow;
+
+  // The sink adds `storeVersion` to every payload, so the decision's own field takes another name.
+  'boxxy.decision.recorded': Omit<DecisionRow, 'storeVersion'> & {
+    readonly snapshotStoreVersion: number;
+  };
   'boxxy.attempt.started': OfAttempt & {
     readonly atcSession: AtcSessionId;
     readonly resumeFallback: boolean;

package/src/facts/work-fact-schemas.ts

@@ -93,7 +93,9 @@ export const workFactSchemas = {
     skillsRef: brandSchemas.commitSha.nullable(),
     rulesVersion: brandSchemas.rulesVersion,
   }),
-  'boxxy.decision.recorded': decisionRowSchema,
+  'boxxy.decision.recorded': decisionRowSchema
+    .omit({ storeVersion: true })
+    .extend({ snapshotStoreVersion: countSchema }),
   'boxxy.attempt.started': z.object({
     ...ofAttempt,
     atcSession: brandSchemas.atcSessionId,

package/src/index.ts

@@ -229,6 +229,7 @@ export type {
   ItemFilter,
   NewId,
   NoticeOutcome,
+  NoticeTryUpdate,
   Notifier,
   OutboxReader,
   PepysAnswer,
@@ -236,6 +237,7 @@ export type {
   SinkAnswer,
   PullRequestReading,
   RowWrite,
+  RunnerFault,
   SessionFault,
   SessionReading,
   SpawnRequest,
@@ -249,6 +251,7 @@ export type {
   Tables,
   WakeSource,
   WorkerKind,
+  WorkerRefusal,
 } from './ports/types.ts';
 
 export type { CostToLand, StageTime } from './reports/types.ts';

package/src/ports/types.ts

@@ -95,6 +95,9 @@ export interface StoreReader extends OutboxReader {
   // the rows not yet sent, whatever their tries, oldest first
   listUnsentNotices: (limit: number) => Promise<NoticeRow[]>;
 
+  // the rows not yet sent whose `nextTryAt` has passed, oldest `nextTryAt` first
+  listNoticesDue: (now: Instant, limit: number) => Promise<NoticeRow[]>;
+
   // oldest kept first
   listKeptSessions: () => Promise<{ readonly item: ItemId; readonly kept: KeptSession }[]>;
 
@@ -152,8 +155,8 @@ export interface StoreTx extends StoreReader {
   syncLimits: (limits: readonly Limit[], at: Instant) => Promise<void>;
   markPullRequestChecked: (ref: PullRequestRef, at: Instant) => Promise<void>;
 
-  // one more try of the notice; `sent` also sets its `sentAt`
-  markNoticeTried: (id: number, at: Instant, sent: boolean) => Promise<void>;
+  // one more try of the notice, with the new key state and next try time; a `sentAt` also marks it sent
+  markNoticeTried: (id: number, update: NoticeTryUpdate) => Promise<void>;
 }
 
 // A change may write no fact, such as the suspend mark; such a change moves no store version. The
@@ -305,11 +308,13 @@ export type SessionReading =
 
 export type Attention = 'working' | 'needs-input' | 'turn-ended';
 
-// A git repository that atc clones on the target. It carries no credential: an imp clones over its
-// own network, where the broker adds the credential from the session's grants.
+// A git repository that atc clones for the session. The atc daemon clones it before the session
+// exists, so a private repository needs `credentialRef`: the name of the daemon's environment
+// variable that holds a clone token. The name is no secret; boxxy never reads the token.
 export interface GitSource {
   readonly url: string;
   readonly ref: string;
+  readonly credentialRef?: { readonly name: string };
 }
 
 // Exactly one of the two: `cwd`, the repo's folder on a target on the atc daemon's own host, or
@@ -341,11 +346,27 @@ export interface HoldNotice {
   readonly item: ItemId;
   readonly reason: HoldReason;
   readonly at: Instant;
+
+  // the row's current key; the adapter sends it unchanged
+  readonly key: string;
 }
 
 export type NoticeOutcome =
   | { readonly kind: 'sent' }
-  | { readonly kind: 'failed'; readonly reason: string };
+
+  // atc ran nothing
+  | { readonly kind: 'refused'; readonly reason: string }
+
+  // atc may have sent the message
+  | { readonly kind: 'uncertain'; readonly reason: string };
+
+// What one try writes to its row, besides one more `tries`.
+export interface NoticeTryUpdate {
+  readonly sentAt: Instant | null;
+  readonly keySeq: number;
+  readonly keyTries: number;
+  readonly nextTryAt: Instant;
+}
 
 // Proves who sent a request to the server. The server's root middleware calls it for every
 // session and hook procedure, and knows no header and no token itself. null: no proof, so the
@@ -370,6 +391,21 @@ export interface SessionFault {
   readonly holder: AttemptId;
 }
 
+// A spawn or a wake that the worker refused. A refused spawn settles the attempt as `no-capacity`
+// or `spawn-refused`; a refused wake sleeps the attempt again for capacity, and otherwise leaves it
+// `waking` for the next reading. The runner logs the worker's reason, which no fact carries.
+export interface WorkerRefusal {
+  readonly kind: 'fault';
+  readonly fault: 'spawn-refused' | 'wake-refused';
+  readonly attempt: AttemptId;
+  readonly item: ItemId;
+  readonly cause: 'capacity' | 'other';
+  readonly reason: string;
+}
+
+// What a claim or a reading returns for the runner to log.
+export type RunnerFault = SessionFault | WorkerRefusal;
+
 // What one batch sent to the sink got back. `retry` may or may not have stored the batch.
 export type SinkAnswer =
   | { readonly kind: 'stored' }

package/src/rows/decision-row-schema.ts

@@ -17,7 +17,7 @@ const limitCountSchema = z.object({
   max: countSchema,
 });
 
-// A plain object, so that the wire schema of `boxxy.decision.recorded` can extend it.
+// A plain object, so that the schema of `boxxy.decision.recorded` can rename one field of it.
 export const decisionRowSchema = z.object({
   id: brandSchemas.decisionId,
   attempt: brandSchemas.attemptId,

package/src/rows/notice-row-schema.ts

@@ -14,4 +14,7 @@ export const noticeRowSchema: z.ZodType<NoticeRow> = z.object({
   at: brandSchemas.instant,
   tries: countSchema,
   sentAt: brandSchemas.instant.nullable(),
+  keySeq: countSchema,
+  keyTries: countSchema,
+  nextTryAt: brandSchemas.instant,
 });

package/src/rows/spawn-request-schema.ts

@@ -14,6 +14,16 @@ export const gitSourceSchema: z.ZodType<GitSource> = z.strictObject({
     .min(1)
     .max(255)
     .refine((ref) => !ref.startsWith('-'), 'a git source ref must not start with -'),
+
+  // atc's own rule for the name of an environment variable
+  credentialRef: z
+    .strictObject({
+      name: z
+        .string()
+        .max(255)
+        .regex(/^[A-Za-z_]\w*$/u, 'a credentialRef names an environment variable'),
+    })
+    .exactOptional(),
 });
 
 const spawnRequestFields = z.strictObject({

package/src/test-utils/create-fake-notifier.ts

@@ -4,46 +4,48 @@ export interface FakeNotifier extends Notifier {
   // each notice that was sent, in order
   readonly told: readonly HoldNotice[];
 
-  // the number of calls, sent or failed
+  // every call, sent or not, in order
+  readonly attempts: readonly HoldNotice[];
+
+  // the number of calls, sent or not
   readonly calls: () => number;
 
-  // the next call fails with the reason
-  failNext: (reason: string) => void;
+  // the next call ends with the outcome
+  failNext: (outcome: Exclude<NoticeOutcome, { kind: 'sent' }>) => void;
 
-  // every call fails with the reason until `recover`
-  failAlways: (reason: string) => void;
+  // every call ends with the outcome until `recover`
+  failAlways: (outcome: Exclude<NoticeOutcome, { kind: 'sent' }>) => void;
   recover: () => void;
 }
 
 export function createFakeNotifier(): FakeNotifier {
   const told: HoldNotice[] = [];
-  let calls = 0;
-  let next: string | null = null;
-  let always: string | null = null;
+  const attempts: HoldNotice[] = [];
+  let next: NoticeOutcome | null = null;
+  let always: NoticeOutcome | null = null;
 
   return {
     told,
-    calls: () => calls,
-    failNext: (reason) => {
-      next = reason;
+    attempts,
+    calls: () => attempts.length,
+    failNext: (outcome) => {
+      next = outcome;
     },
-    failAlways: (reason) => {
-      always = reason;
+    failAlways: (outcome) => {
+      always = outcome;
     },
     recover: () => {
       always = null;
     },
     tellHold: (notice) => {
-      calls += 1;
+      attempts.push(notice);
 
-      const reason = next ?? always;
+      const outcome = next ?? always;
 
       next = null;
 
-      if (reason !== null) {
-        const failed: NoticeOutcome = { kind: 'failed', reason };
-
-        return Promise.resolve(failed);
+      if (outcome !== null) {
+        return Promise.resolve(outcome);
       }
 
       told.push(notice);

package/src/types.ts

@@ -386,7 +386,7 @@ export interface RunnerRow {
   readonly paused: boolean;
 }
 
-// A hold notice for the `Notifier` port. The tick tries it again until `tries` reaches 5.
+// A hold notice for the `Notifier` port. The tick tries it again, with no cap, until atc takes it.
 export interface NoticeRow {
   readonly id: number;
   readonly item: ItemId;
@@ -394,6 +394,15 @@ export interface NoticeRow {
   readonly at: Instant;
   readonly tries: number;
   readonly sentAt: Instant | null;
+
+  // the row's current key is `boxxy-notice:<id>:<keySeq>`
+  readonly keySeq: number;
+
+  // uncertain tries under the current key; 0 after each change of key
+  readonly keyTries: number;
+
+  // a tick sends the row once now >= nextTryAt; a new row holds its `at`
+  readonly nextTryAt: Instant;
 }
 
 export type Effort = 'low' | 'medium' | 'high' | 'xhigh' | 'max';