@milkenjoyer/toolchain 0.15.0 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -265,3 +265,7 @@ Rule 16 applies once `specs.json` has an `arithmetic` key. Each `arithmetic` glo
265
265
  - `domain-no-throw`: Domain.Rejection/Schema.TaggedError.
266
266
 
267
267
  Source checks skip tests/proofs. Runtime story coverage is tracked in #325.
268
+
269
+ # Boat start budgets
270
+
271
+ See [Boat start budgets](STARTS.md) for `@milkenjoyer/toolchain/starts` in 0.16.0.
package/STARTS.md ADDED
@@ -0,0 +1,11 @@
1
+ # Boat start budgets
2
+
3
+ Pin `@milkenjoyer/toolchain` to `0.16.0` and import `boatJobFindings` from `@milkenjoyer/toolchain/starts`. Add its findings to the existing workflow policy, with every workflow as a `[path, text]` pair. It bounds each closure to `BOAT_JOBS_PER_RUN = 2`, including literal matrices, repeated local reusable calls and `workflow_run` descendants. Each descendant counts once per distinct activity type, or three times when `types` is absent. Dynamic and unresolved graphs produce findings. Keep runner, timeout and concurrency checks.
4
+
5
+ Scripts wrap each create, fork or resume in `admitStart({ repo, jobs: 1 }, start, { deadline })`. `Repo` validates an `owner/name`. `deadline` is an absolute epoch time in milliseconds. `start` is a lazy Effect that runs once after admission. Supply `BoatStarts.layer(key, { fetch? })` with a redacted key. It reads the key's default billing wallet. The optional `fetch` supplies the SDK transport.
6
+
7
+ Read failures and incomplete history retry until the deadline, then fail `StartHeld` with an `Unread` line. Other waits also poll fresh Boat readings until the deadline. An unknown repo, an invalid plan or non-positive `jobs` holds at once. `StartHeld.line` names the cause. The pure `decide(request, counts, now)` takes the current epoch time explicitly, including when counts are unread.
8
+
9
+ `startShares` assigns 80% of each live limit across the five repos. Account headroom is 20 starts per window. Repo CI history counts a Boat job without `runStartedAt` as starting now unless Boat reports it settled, including states the SDK does not list, such as `paused`. A start stamped after Boat answers counts at the answer's time. That history omits direct sandbox starts. A kept sandbox resume takes this admission path too. Product repos adopt the published pin instead of copying files.
10
+
11
+ Admission reads counts and reserves nothing, so concurrent callers can race. Workflows triggered by merges, Renovate, schedules and pushes start without admission, bounded only by `BOAT_JOBS_PER_RUN`. Boat reports no start spend, so nothing here proves zero paid starts.
@@ -0,0 +1,100 @@
1
+ import * as Schema from "effect/Schema";
2
+ import * as Effect from "effect/Effect";
3
+ import * as Layer from "effect/Layer";
4
+ import * as Context from "effect/Context";
5
+ import * as Redacted from "effect/Redacted";
6
+ export declare const Repo: Schema.brand<Schema.String, "Repo">;
7
+ export type Repo = typeof Repo.Type;
8
+ type Window = "minute" | "hour" | "day";
9
+ type PerWindow<A> = { readonly [W in Window]: A; };
10
+ type Share = {
11
+ readonly repo: Repo;
12
+ readonly share: number;
13
+ };
14
+ type Plan = {
15
+ readonly limits: PerWindow<number>;
16
+ readonly used: PerWindow<number>;
17
+ readonly nextStartDollars: number | undefined;
18
+ };
19
+ type RepoStarts = {
20
+ readonly repo: Repo;
21
+ readonly starts: ReadonlyArray<number>;
22
+ readonly complete: boolean;
23
+ };
24
+ type Counts = {
25
+ readonly now: number;
26
+ readonly plan: Plan;
27
+ readonly repo: RepoStarts;
28
+ };
29
+ type StartRequest = {
30
+ readonly repo: Repo;
31
+ readonly jobs: number;
32
+ };
33
+ declare const Line: Schema.Union<readonly [Schema.TaggedStruct<"Unread", {
34
+ readonly reason: Schema.String;
35
+ }>, Schema.TaggedStruct<"Paid", {
36
+ readonly nextStartDollars: Schema.UndefinedOr<Schema.Number>;
37
+ }>, Schema.TaggedStruct<"Account", {
38
+ readonly window: Schema.Literals<readonly ["minute", "hour", "day"]>;
39
+ readonly used: Schema.Number;
40
+ readonly line: Schema.Number;
41
+ }>, Schema.TaggedStruct<"Budget", {
42
+ readonly repo: Schema.brand<Schema.String, "Repo">;
43
+ readonly window: Schema.Literals<readonly ["minute", "hour", "day"]>;
44
+ readonly used: Schema.Number;
45
+ readonly budget: Schema.Number;
46
+ }>]>;
47
+ type Line = typeof Line.Type;
48
+ type Admission = {
49
+ readonly _tag: "Admit";
50
+ } | {
51
+ readonly _tag: "Wait";
52
+ readonly until: number;
53
+ readonly line: Line;
54
+ } | {
55
+ readonly _tag: "Hold";
56
+ readonly line: Line;
57
+ };
58
+ export declare const startShares: ReadonlyArray<Share>;
59
+ export declare const decide: (request: StartRequest, counts: Counts | undefined, now: number) => Admission;
60
+ declare const StartReadError_base: Schema.Class<StartReadError, Schema.TaggedStruct<"StartReadError", {
61
+ readonly reason: Schema.String;
62
+ }>, import("effect/Cause").YieldableError & {
63
+ readonly brand: unique symbol;
64
+ }>;
65
+ export declare class StartReadError extends StartReadError_base {}
66
+ declare const BoatStarts_base: Context.ServiceClass<BoatStarts, "toolchain/BoatStarts", {
67
+ readonly plan: Effect.Effect<Plan, StartReadError>;
68
+ readonly repoStarts: (repo: Repo) => Effect.Effect<RepoStarts, StartReadError>;
69
+ }>;
70
+ export declare class BoatStarts extends BoatStarts_base {
71
+ static readonly layer: (key: Redacted.Redacted<string>, options?: {
72
+ readonly fetch?: (url: string | URL | Request, init?: RequestInit) => Promise<Response>;
73
+ }) => Layer.Layer<BoatStarts, never, never>;
74
+ }
75
+ export declare const BOAT_JOBS_PER_RUN = 2;
76
+ type WorkflowFile = readonly [path: string, text: string];
77
+ export declare const boatJobFindings: (files: ReadonlyArray<WorkflowFile>) => ReadonlyArray<string>;
78
+ declare const StartHeld_base: Schema.Class<StartHeld, Schema.TaggedStruct<"StartHeld", {
79
+ readonly line: Schema.Union<readonly [Schema.TaggedStruct<"Unread", {
80
+ readonly reason: Schema.String;
81
+ }>, Schema.TaggedStruct<"Paid", {
82
+ readonly nextStartDollars: Schema.UndefinedOr<Schema.Number>;
83
+ }>, Schema.TaggedStruct<"Account", {
84
+ readonly window: Schema.Literals<readonly ["minute", "hour", "day"]>;
85
+ readonly used: Schema.Number;
86
+ readonly line: Schema.Number;
87
+ }>, Schema.TaggedStruct<"Budget", {
88
+ readonly repo: Schema.brand<Schema.String, "Repo">;
89
+ readonly window: Schema.Literals<readonly ["minute", "hour", "day"]>;
90
+ readonly used: Schema.Number;
91
+ readonly budget: Schema.Number;
92
+ }>]>;
93
+ }>, import("effect/Cause").YieldableError & {
94
+ readonly brand: unique symbol;
95
+ }>;
96
+ export declare class StartHeld extends StartHeld_base {}
97
+ export declare const admitStart: <A, E, R>(request: StartRequest, start: Effect.Effect<A, E, R>, args_2: {
98
+ readonly deadline: number;
99
+ }) => Effect.Effect<A, E | StartHeld, R | BoatStarts>;
100
+ export type { Admission, Counts, Line, PerWindow, Plan, RepoStarts, Share, StartRequest, Window };
@@ -0,0 +1,385 @@
1
+ import * as Schema from "effect/Schema";
2
+ import * as Effect from "effect/Effect";
3
+ import * as Layer from "effect/Layer";
4
+ import * as Clock from "effect/Clock";
5
+ import * as Context from "effect/Context";
6
+ import * as Redacted from "effect/Redacted";
7
+ import { BoatApi, CiJobState, Configuration } from "@boatdev/sdk";
8
+ import { parse } from "yaml";
9
+ // src/starts/budget.ts
10
+ const Repo = Schema.String.check(Schema.isPattern(/^[\w.-]+\/[\w.-]+$/u)).pipe(Schema.brand("Repo"));
11
+ const Window = Schema.Literals([
12
+ "minute",
13
+ "hour",
14
+ "day"
15
+ ]);
16
+ const Line = Schema.Union([
17
+ Schema.TaggedStruct("Unread", { reason: Schema.String }),
18
+ Schema.TaggedStruct("Paid", { nextStartDollars: Schema.UndefinedOr(Schema.Number) }),
19
+ Schema.TaggedStruct("Account", {
20
+ window: Window,
21
+ used: Schema.Number,
22
+ line: Schema.Number
23
+ }),
24
+ Schema.TaggedStruct("Budget", {
25
+ repo: Repo,
26
+ window: Window,
27
+ used: Schema.Number,
28
+ budget: Schema.Number
29
+ })
30
+ ]);
31
+ const windows = [
32
+ "minute",
33
+ "hour",
34
+ "day"
35
+ ];
36
+ const windowMillis = {
37
+ minute: 6e4,
38
+ hour: 36e5,
39
+ day: 864e5
40
+ };
41
+ const pollMillis = {
42
+ minute: 15e3,
43
+ hour: 6e4,
44
+ day: 3e5
45
+ };
46
+ const startShares = [
47
+ {
48
+ repo: Repo.make("birbprophet/agent-kit"),
49
+ share: .1
50
+ },
51
+ {
52
+ repo: Repo.make("siglata/siglata"),
53
+ share: .2
54
+ },
55
+ {
56
+ repo: Repo.make("optionhouse-xyz/optionhouse"),
57
+ share: .25
58
+ },
59
+ {
60
+ repo: Repo.make("birbprophet/vibebattler"),
61
+ share: .25
62
+ },
63
+ {
64
+ repo: Repo.make("birbprophet/secrets"),
65
+ share: 0
66
+ }
67
+ ];
68
+ const count = (value) => Number.isSafeInteger(value) && value >= 0;
69
+ const unread = (reason) => ({
70
+ _tag: "Hold",
71
+ line: {
72
+ _tag: "Unread",
73
+ reason
74
+ }
75
+ });
76
+ const decide = (request, counts, now) => {
77
+ const share = startShares.find(({ repo }) => repo === request.repo);
78
+ if (share === void 0) return unread("repo has no start budget");
79
+ if (!count(request.jobs) || request.jobs === 0) return unread("jobs must be a positive safe integer");
80
+ if (!Number.isFinite(now)) return unread("start time unread");
81
+ if (counts === void 0) return {
82
+ _tag: "Wait",
83
+ until: now + pollMillis.minute,
84
+ line: {
85
+ _tag: "Unread",
86
+ reason: "start plan unread"
87
+ }
88
+ };
89
+ if (!Number.isFinite(counts.now) || !windows.every((window) => count(counts.plan.limits[window]) && count(counts.plan.used[window]))) return unread("start plan unread");
90
+ if (counts.repo.repo !== request.repo || !counts.repo.starts.every((at) => Number.isFinite(at) && at <= counts.now)) return unread("repo start history incomplete");
91
+ if (!counts.repo.complete) return {
92
+ _tag: "Wait",
93
+ until: now + pollMillis.minute,
94
+ line: {
95
+ _tag: "Unread",
96
+ reason: "repo start history incomplete"
97
+ }
98
+ };
99
+ const { plan } = counts;
100
+ if (plan.nextStartDollars !== 0) return {
101
+ _tag: "Wait",
102
+ until: now + pollMillis.minute,
103
+ line: {
104
+ _tag: "Paid",
105
+ nextStartDollars: plan.nextStartDollars
106
+ }
107
+ };
108
+ for (const window of windows) {
109
+ const used = plan.used[window];
110
+ const line = plan.limits[window] - 20;
111
+ if (used + request.jobs > line) return window === "day" ? {
112
+ _tag: "Hold",
113
+ line: {
114
+ _tag: "Account",
115
+ window,
116
+ used,
117
+ line
118
+ }
119
+ } : {
120
+ _tag: "Wait",
121
+ until: now + pollMillis[window],
122
+ line: {
123
+ _tag: "Account",
124
+ window,
125
+ used,
126
+ line
127
+ }
128
+ };
129
+ }
130
+ for (const window of windows) {
131
+ const starts = counts.repo.starts.filter((at) => at > now - windowMillis[window]).toSorted((left, right) => left - right);
132
+ const used = starts.length;
133
+ const budget = Math.floor(share.share * plan.limits[window]);
134
+ if (used + request.jobs <= budget) continue;
135
+ const line = {
136
+ _tag: "Budget",
137
+ repo: request.repo,
138
+ window,
139
+ used,
140
+ budget
141
+ };
142
+ const expires = starts[used + request.jobs - budget - 1];
143
+ return request.jobs > budget || expires === void 0 ? {
144
+ _tag: "Hold",
145
+ line
146
+ } : {
147
+ _tag: "Wait",
148
+ until: expires + windowMillis[window],
149
+ line
150
+ };
151
+ }
152
+ return { _tag: "Admit" };
153
+ };
154
+ // src/starts/boat.ts
155
+ var StartReadError = class extends Schema.TaggedError()("StartReadError", { reason: Schema.String }) {};
156
+ const Count = Schema.Number.check(Schema.makeFilter((value) => Number.isSafeInteger(value) && value >= 0));
157
+ const Usage = Schema.Struct({
158
+ limit: Count,
159
+ used: Count
160
+ });
161
+ const Limits = Schema.Struct({
162
+ ok: Schema.Literal(true),
163
+ starts: Schema.Struct({
164
+ minute: Usage,
165
+ hour: Usage,
166
+ day: Usage
167
+ }),
168
+ nextStartDollars: Schema.optional(Schema.NullOr(Schema.Finite))
169
+ });
170
+ const Ci = Schema.Struct({
171
+ ok: Schema.Literal(true),
172
+ jobs: Schema.Array(Schema.Struct({
173
+ repo: Schema.String,
174
+ label: Schema.String,
175
+ state: Schema.String.check(Schema.isMinLength(1)),
176
+ queuedAt: Schema.Date,
177
+ runStartedAt: Schema.optional(Schema.NullOr(Schema.Date))
178
+ }))
179
+ });
180
+ const settled = /* @__PURE__ */ new Set([
181
+ CiJobState.Success,
182
+ CiJobState.Failure,
183
+ CiJobState.Cancelled,
184
+ CiJobState.Skipped,
185
+ CiJobState.Failed,
186
+ CiJobState.Refused
187
+ ]);
188
+ var BoatStarts = class BoatStarts extends Context.Service()("toolchain/BoatStarts") {
189
+ static layer = (key, options = {}) => Layer.sync(BoatStarts, () => {
190
+ const api = new BoatApi(new Configuration({
191
+ accessToken: Redacted.value(key),
192
+ ...options.fetch === void 0 ? {} : { fetchApi: options.fetch }
193
+ }));
194
+ const plan = Effect.gen(function* () {
195
+ const response = yield* Effect.tryPromise({
196
+ try: () => api.limits(),
197
+ catch: () => new StartReadError({ reason: "Boat limits request failed" })
198
+ });
199
+ const limits = yield* Schema.decodeUnknownEffect(Limits)(response).pipe(Effect.mapError(() => new StartReadError({ reason: "Boat limits unread" })));
200
+ return {
201
+ limits: {
202
+ minute: limits.starts.minute.limit,
203
+ hour: limits.starts.hour.limit,
204
+ day: limits.starts.day.limit
205
+ },
206
+ used: {
207
+ minute: limits.starts.minute.used,
208
+ hour: limits.starts.hour.used,
209
+ day: limits.starts.day.used
210
+ },
211
+ nextStartDollars: limits.nextStartDollars ?? void 0
212
+ };
213
+ });
214
+ const repoStarts = Effect.fn("BoatStarts.repoStarts")(function* (repo) {
215
+ const response = yield* Effect.tryPromise({
216
+ try: () => api.getCiOverview({
217
+ repo,
218
+ limit: 500
219
+ }),
220
+ catch: () => new StartReadError({ reason: "Boat CI request failed" })
221
+ });
222
+ const now = yield* Clock.currentTimeMillis;
223
+ const { jobs } = yield* Schema.decodeUnknownEffect(Ci)(response).pipe(Effect.mapError(() => new StartReadError({ reason: "Boat CI history unread" })));
224
+ if (jobs.some((job) => job.repo !== repo)) return yield* new StartReadError({ reason: "Boat CI history differs from request" });
225
+ const oldest = Math.min(...jobs.map((job) => Math.max(job.queuedAt.getTime(), job.runStartedAt?.getTime() ?? 0)));
226
+ return {
227
+ repo,
228
+ starts: jobs.flatMap((job) => {
229
+ const at = job.runStartedAt?.getTime() ?? (settled.has(job.state) ? void 0 : now);
230
+ return job.label.split("/")[0]?.startsWith("boat") === true && at !== void 0 && at > now - windowMillis.day ? [Math.min(at, now)] : [];
231
+ }),
232
+ complete: jobs.length < 500 || oldest <= now - windowMillis.day
233
+ };
234
+ });
235
+ return BoatStarts.of({
236
+ plan,
237
+ repoStarts
238
+ });
239
+ });
240
+ };
241
+ // src/starts/policy.ts
242
+ const BOAT_JOBS_PER_RUN = 2;
243
+ const Matrix = Schema.Record(Schema.String, Schema.Array(Schema.Unknown));
244
+ const Workflow = Schema.Struct({
245
+ name: Schema.optionalKey(Schema.String),
246
+ on: Schema.optionalKey(Schema.Union([
247
+ Schema.String,
248
+ Schema.Array(Schema.String),
249
+ Schema.Record(Schema.String, Schema.Unknown)
250
+ ])),
251
+ jobs: Schema.Record(Schema.String, Schema.Struct({
252
+ "runs-on": Schema.optionalKey(Schema.Union([Schema.String, Schema.Array(Schema.String)])),
253
+ uses: Schema.optionalKey(Schema.String),
254
+ strategy: Schema.optionalKey(Schema.Struct({ matrix: Schema.optionalKey(Schema.Union([Schema.String, Matrix])) }))
255
+ }))
256
+ });
257
+ const Descendant = Schema.Struct({ workflow_run: Schema.Struct({
258
+ workflows: Schema.Union([Schema.String, Schema.Array(Schema.String)]),
259
+ types: Schema.optionalKey(Schema.Union([Schema.String, Schema.Array(Schema.String)]))
260
+ }) });
261
+ const dynamic = (value) => {
262
+ try {
263
+ return JSON.stringify(value).includes("${{");
264
+ } catch {
265
+ return true;
266
+ }
267
+ };
268
+ const boatJobFindings = (files) => {
269
+ const findings = [];
270
+ const workflows = [];
271
+ for (const [path, text] of files) try {
272
+ workflows.push({
273
+ path,
274
+ workflow: Schema.decodeUnknownSync(Workflow)(parse(text))
275
+ });
276
+ } catch {
277
+ findings.push(`${path}: workflow unread`);
278
+ }
279
+ const after = (entry) => {
280
+ const events = entry.workflow.on;
281
+ if (!Schema.is(Descendant)(events)) {
282
+ if (typeof events === "object" && "workflow_run" in events) findings.push(`${entry.path}: workflow_run unread`);
283
+ return {
284
+ names: [],
285
+ copies: 0
286
+ };
287
+ }
288
+ const names = events.workflow_run.workflows;
289
+ const selectors = typeof names === "string" ? [names] : names;
290
+ if (selectors.some((name) => /[*!?[\]]/u.test(name))) findings.push(`${entry.path}: workflow_run pattern unresolved`);
291
+ const types = events.workflow_run.types;
292
+ if (types !== void 0 && dynamic(types)) findings.push(`${entry.path}: dynamic workflow_run types`);
293
+ return {
294
+ names: selectors,
295
+ copies: types === void 0 ? 3 : new Set(typeof types === "string" ? [types] : types).size
296
+ };
297
+ };
298
+ const count = (entry, parents, descendants) => {
299
+ if (parents.includes(entry.path)) {
300
+ findings.push(`${entry.path}: workflow cycle`);
301
+ return 0;
302
+ }
303
+ const stack = [...parents, entry.path];
304
+ let total = 0;
305
+ for (const [name, job] of Object.entries(entry.workflow.jobs)) {
306
+ const label = `${entry.path} ${name}`;
307
+ const matrix = job.strategy?.matrix;
308
+ let copies = 1;
309
+ if (matrix !== void 0) {
310
+ if (typeof matrix === "string" || dynamic(matrix)) findings.push(`${label}: dynamic matrix`);
311
+ else {
312
+ const axes = Object.entries(matrix).filter(([axis]) => axis !== "include" && axis !== "exclude");
313
+ copies = (axes.length === 0 ? 0 : axes.reduce((product, [, values]) => product * values.length, 1)) + (matrix.include?.length ?? 0);
314
+ }
315
+ }
316
+ if (job.uses !== void 0) {
317
+ if (!/^\.\/\.github\/workflows\/[^/]+\.ya?ml$/u.test(job.uses)) {
318
+ findings.push(`${label}: remote or unresolved reusable workflow`);
319
+ continue;
320
+ }
321
+ const target = job.uses.slice(2);
322
+ const called = workflows.find(({ path }) => path === target || `.github/workflows/${path}` === target);
323
+ if (called === void 0) findings.push(`${label}: reusable workflow ${target} unread`);
324
+ else total += copies * count(called, stack, false);
325
+ } else if (job["runs-on"] === void 0 || dynamic(job["runs-on"])) findings.push(`${label}: dynamic or unread runs-on`);
326
+ else {
327
+ const runners = job["runs-on"];
328
+ if ((typeof runners === "string" ? [runners] : runners).some((runner) => runner.split("/")[0]?.startsWith("boat") === true)) total += copies;
329
+ }
330
+ }
331
+ if (descendants) for (const child of workflows) {
332
+ const { names, copies } = after(child);
333
+ if (dynamic(names)) findings.push(`${child.path}: dynamic workflow_run`);
334
+ const file = entry.path.split("/").at(-1) ?? entry.path;
335
+ if ((entry.workflow.name === void 0 ? [
336
+ entry.path,
337
+ file,
338
+ `.github/workflows/${file}`
339
+ ] : [entry.workflow.name]).some((name) => names.includes(name))) total += copies * count(child, stack, true);
340
+ }
341
+ return total;
342
+ };
343
+ for (const entry of workflows) {
344
+ const total = count(entry, [], true);
345
+ if (total > 2) findings.push(`${entry.path}: closure starts ${total} Boat jobs, limit 2`);
346
+ }
347
+ return [...new Set(findings)];
348
+ };
349
+ // src/starts.ts
350
+ var StartHeld = class extends Schema.TaggedError()("StartHeld", { line: Line }) {};
351
+ const admitStart = Effect.fn("Starts.admitStart")(function* (request, start, { deadline }) {
352
+ const boat = yield* BoatStarts;
353
+ let last = {
354
+ _tag: "Unread",
355
+ reason: "start deadline reached"
356
+ };
357
+ for (;;) {
358
+ const remaining = deadline - (yield* Clock.currentTimeMillis);
359
+ if (!Number.isFinite(remaining) || remaining <= 0) return yield* new StartHeld({ line: last });
360
+ const counts = yield* Effect.gen(function* () {
361
+ const plan = yield* boat.plan;
362
+ const repo = yield* boat.repoStarts(request.repo);
363
+ return {
364
+ now: yield* Clock.currentTimeMillis,
365
+ plan,
366
+ repo
367
+ };
368
+ }).pipe(Effect.catchTag("StartReadError", () => Effect.undefined), Effect.timeoutOrElse({
369
+ duration: remaining,
370
+ orElse: () => Effect.fail(new StartHeld({ line: last }))
371
+ }));
372
+ const now = yield* Clock.currentTimeMillis;
373
+ const decision = decide(request, counts, now);
374
+ if (decision._tag === "Hold") return yield* new StartHeld({ line: decision.line });
375
+ if (!Number.isFinite(deadline) || now >= deadline) return yield* new StartHeld({ line: decision._tag === "Wait" ? decision.line : {
376
+ _tag: "Unread",
377
+ reason: "start deadline reached"
378
+ } });
379
+ if (decision._tag === "Admit") return yield* start;
380
+ last = decision.line;
381
+ const window = decision.line._tag === "Account" || decision.line._tag === "Budget" ? decision.line.window : "minute";
382
+ yield* Effect.sleep(Math.max(0, Math.min(decision.until, now + pollMillis[window], deadline) - now));
383
+ }
384
+ });
385
+ export { BOAT_JOBS_PER_RUN, BoatStarts, Repo, StartHeld, StartReadError, admitStart, boatJobFindings, decide, startShares };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@milkenjoyer/toolchain",
3
- "version": "0.15.0",
3
+ "version": "0.16.0",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "git+https://github.com/birbprophet/agent-kit.git",
@@ -15,6 +15,7 @@
15
15
  },
16
16
  "files": [
17
17
  "dist",
18
+ "STARTS.md",
18
19
  "licenses",
19
20
  "node-version",
20
21
  "renovate.json",
@@ -81,6 +82,10 @@
81
82
  "types": "./dist/rules.d.mts",
82
83
  "default": "./dist/rules.mjs"
83
84
  },
85
+ "./starts": {
86
+ "types": "./dist/starts.d.mts",
87
+ "default": "./dist/starts.mjs"
88
+ },
84
89
  "./versions": {
85
90
  "types": "./dist/versions.d.mts",
86
91
  "default": "./dist/versions.mjs"
@@ -102,6 +107,7 @@
102
107
  "prepack": "vp pack"
103
108
  },
104
109
  "dependencies": {
110
+ "@boatdev/sdk": "1.13.0",
105
111
  "@effect/platform-node": "4.1.2",
106
112
  "@effect/tsgo": "0.67.3",
107
113
  "@foldkit/oxlint-plugin": "0.15.4",
@@ -112,6 +118,7 @@
112
118
  "oxc-parser": "0.157.0",
113
119
  "semver": "7.8.6",
114
120
  "ultracite": "8.1.1",
121
+ "yaml": "2.9.1",
115
122
  "z3-solver": "5.3.3"
116
123
  },
117
124
  "devDependencies": {
@@ -0,0 +1,140 @@
1
+ import { BoatApi, CiJobState, Configuration } from "@boatdev/sdk";
2
+ import * as Clock from "effect/Clock";
3
+ import * as Context from "effect/Context";
4
+ import * as Effect from "effect/Effect";
5
+ import * as Layer from "effect/Layer";
6
+ import * as Redacted from "effect/Redacted";
7
+ import * as Schema from "effect/Schema";
8
+
9
+ import {
10
+ type Plan,
11
+ type Repo,
12
+ type RepoStarts,
13
+ windowMillis,
14
+ } from "./budget.ts";
15
+
16
+ export class StartReadError extends Schema.TaggedError<
17
+ StartReadError,
18
+ { readonly brand: unique symbol }
19
+ >()("StartReadError", { reason: Schema.String }) {}
20
+
21
+ const Count = Schema.Number.check(
22
+ Schema.makeFilter((value) => Number.isSafeInteger(value) && value >= 0)
23
+ );
24
+ const Usage = Schema.Struct({ limit: Count, used: Count });
25
+ const Limits = Schema.Struct({
26
+ ok: Schema.Literal(true),
27
+ starts: Schema.Struct({ minute: Usage, hour: Usage, day: Usage }),
28
+ nextStartDollars: Schema.optional(Schema.NullOr(Schema.Finite)),
29
+ });
30
+ const Ci = Schema.Struct({
31
+ ok: Schema.Literal(true),
32
+ jobs: Schema.Array(
33
+ Schema.Struct({
34
+ repo: Schema.String,
35
+ label: Schema.String,
36
+ state: Schema.String.check(Schema.isMinLength(1)),
37
+ queuedAt: Schema.Date,
38
+ runStartedAt: Schema.optional(Schema.NullOr(Schema.Date)),
39
+ })
40
+ ),
41
+ });
42
+ const settled = new Set<string>([
43
+ CiJobState.Success,
44
+ CiJobState.Failure,
45
+ CiJobState.Cancelled,
46
+ CiJobState.Skipped,
47
+ CiJobState.Failed,
48
+ CiJobState.Refused,
49
+ ]);
50
+
51
+ export class BoatStarts extends Context.Service<
52
+ BoatStarts,
53
+ {
54
+ readonly plan: Effect.Effect<Plan, StartReadError>;
55
+ readonly repoStarts: (
56
+ repo: Repo
57
+ ) => Effect.Effect<RepoStarts, StartReadError>;
58
+ }
59
+ >()("toolchain/BoatStarts") {
60
+ static readonly layer = (
61
+ key: Redacted.Redacted<string>,
62
+ options: {
63
+ readonly fetch?: (
64
+ url: string | URL | Request,
65
+ init?: RequestInit
66
+ ) => Promise<Response>;
67
+ } = {}
68
+ ) =>
69
+ Layer.sync(BoatStarts, () => {
70
+ const api = new BoatApi(
71
+ new Configuration({
72
+ accessToken: Redacted.value(key),
73
+ ...(options.fetch === undefined ? {} : { fetchApi: options.fetch }),
74
+ })
75
+ );
76
+ const plan = Effect.gen(function* () {
77
+ const response = yield* Effect.tryPromise({
78
+ try: () => api.limits(),
79
+ catch: () =>
80
+ new StartReadError({ reason: "Boat limits request failed" }),
81
+ });
82
+ const limits = yield* Schema.decodeUnknownEffect(Limits)(response).pipe(
83
+ Effect.mapError(
84
+ () => new StartReadError({ reason: "Boat limits unread" })
85
+ )
86
+ );
87
+ return {
88
+ limits: {
89
+ minute: limits.starts.minute.limit,
90
+ hour: limits.starts.hour.limit,
91
+ day: limits.starts.day.limit,
92
+ },
93
+ used: {
94
+ minute: limits.starts.minute.used,
95
+ hour: limits.starts.hour.used,
96
+ day: limits.starts.day.used,
97
+ },
98
+ nextStartDollars: limits.nextStartDollars ?? undefined,
99
+ };
100
+ });
101
+ const repoStarts = Effect.fn("BoatStarts.repoStarts")(function* (
102
+ repo: Repo
103
+ ) {
104
+ const response = yield* Effect.tryPromise({
105
+ try: () => api.getCiOverview({ repo, limit: 500 }),
106
+ catch: () => new StartReadError({ reason: "Boat CI request failed" }),
107
+ });
108
+ const now = yield* Clock.currentTimeMillis;
109
+ const { jobs } = yield* Schema.decodeUnknownEffect(Ci)(response).pipe(
110
+ Effect.mapError(
111
+ () => new StartReadError({ reason: "Boat CI history unread" })
112
+ )
113
+ );
114
+ if (jobs.some((job) => job.repo !== repo))
115
+ return yield* new StartReadError({
116
+ reason: "Boat CI history differs from request",
117
+ });
118
+ const oldest = Math.min(
119
+ ...jobs.map((job) =>
120
+ Math.max(job.queuedAt.getTime(), job.runStartedAt?.getTime() ?? 0)
121
+ )
122
+ );
123
+ return {
124
+ repo,
125
+ starts: jobs.flatMap((job) => {
126
+ const at =
127
+ job.runStartedAt?.getTime() ??
128
+ (settled.has(job.state) ? undefined : now);
129
+ return job.label.split("/")[0]?.startsWith("boat") === true &&
130
+ at !== undefined &&
131
+ at > now - windowMillis.day
132
+ ? [Math.min(at, now)]
133
+ : [];
134
+ }),
135
+ complete: jobs.length < 500 || oldest <= now - windowMillis.day,
136
+ };
137
+ });
138
+ return BoatStarts.of({ plan, repoStarts });
139
+ });
140
+ }
@@ -0,0 +1,151 @@
1
+ import * as Schema from "effect/Schema";
2
+
3
+ export const Repo = Schema.String.check(
4
+ Schema.isPattern(/^[\w.-]+\/[\w.-]+$/u)
5
+ ).pipe(Schema.brand("Repo"));
6
+ export type Repo = typeof Repo.Type;
7
+ export type Window = "minute" | "hour" | "day";
8
+ export type PerWindow<A> = { readonly [W in Window]: A };
9
+ export type Share = { readonly repo: Repo; readonly share: number };
10
+ export type Plan = {
11
+ readonly limits: PerWindow<number>;
12
+ readonly used: PerWindow<number>;
13
+ readonly nextStartDollars: number | undefined;
14
+ };
15
+ export type RepoStarts = {
16
+ readonly repo: Repo;
17
+ readonly starts: ReadonlyArray<number>;
18
+ readonly complete: boolean;
19
+ };
20
+ export type Counts = {
21
+ readonly now: number;
22
+ readonly plan: Plan;
23
+ readonly repo: RepoStarts;
24
+ };
25
+ export type StartRequest = { readonly repo: Repo; readonly jobs: number };
26
+
27
+ const Window = Schema.Literals(["minute", "hour", "day"]);
28
+ export const Line = Schema.Union([
29
+ Schema.TaggedStruct("Unread", { reason: Schema.String }),
30
+ Schema.TaggedStruct("Paid", {
31
+ nextStartDollars: Schema.UndefinedOr(Schema.Number),
32
+ }),
33
+ Schema.TaggedStruct("Account", {
34
+ window: Window,
35
+ used: Schema.Number,
36
+ line: Schema.Number,
37
+ }),
38
+ Schema.TaggedStruct("Budget", {
39
+ repo: Repo,
40
+ window: Window,
41
+ used: Schema.Number,
42
+ budget: Schema.Number,
43
+ }),
44
+ ]);
45
+ export type Line = typeof Line.Type;
46
+ export type Admission =
47
+ | { readonly _tag: "Admit" }
48
+ | { readonly _tag: "Wait"; readonly until: number; readonly line: Line }
49
+ | { readonly _tag: "Hold"; readonly line: Line };
50
+
51
+ const windows: ReadonlyArray<Window> = ["minute", "hour", "day"];
52
+ export const windowMillis: PerWindow<number> = {
53
+ minute: 60_000,
54
+ hour: 3_600_000,
55
+ day: 86_400_000,
56
+ };
57
+ export const pollMillis: PerWindow<number> = {
58
+ minute: 15_000,
59
+ hour: 60_000,
60
+ day: 300_000,
61
+ };
62
+
63
+ export const startShares: ReadonlyArray<Share> = [
64
+ { repo: Repo.make("birbprophet/agent-kit"), share: 0.1 },
65
+ { repo: Repo.make("siglata/siglata"), share: 0.2 },
66
+ { repo: Repo.make("optionhouse-xyz/optionhouse"), share: 0.25 },
67
+ { repo: Repo.make("birbprophet/vibebattler"), share: 0.25 },
68
+ { repo: Repo.make("birbprophet/secrets"), share: 0 },
69
+ ];
70
+
71
+ const count = (value: number) => Number.isSafeInteger(value) && value >= 0;
72
+ const unread = (reason: string): Admission => ({
73
+ _tag: "Hold",
74
+ line: { _tag: "Unread", reason },
75
+ });
76
+
77
+ export const decide = (
78
+ request: StartRequest,
79
+ counts: Counts | undefined,
80
+ now: number
81
+ ): Admission => {
82
+ const share = startShares.find(({ repo }) => repo === request.repo);
83
+ if (share === undefined) return unread("repo has no start budget");
84
+ if (!count(request.jobs) || request.jobs === 0)
85
+ return unread("jobs must be a positive safe integer");
86
+ if (!Number.isFinite(now)) return unread("start time unread");
87
+ if (counts === undefined)
88
+ return {
89
+ _tag: "Wait",
90
+ until: now + pollMillis.minute,
91
+ line: { _tag: "Unread", reason: "start plan unread" },
92
+ };
93
+ if (
94
+ !Number.isFinite(counts.now) ||
95
+ !windows.every(
96
+ (window) =>
97
+ count(counts.plan.limits[window]) && count(counts.plan.used[window])
98
+ )
99
+ )
100
+ return unread("start plan unread");
101
+ if (
102
+ counts.repo.repo !== request.repo ||
103
+ !counts.repo.starts.every((at) => Number.isFinite(at) && at <= counts.now)
104
+ )
105
+ return unread("repo start history incomplete");
106
+ if (!counts.repo.complete)
107
+ return {
108
+ _tag: "Wait",
109
+ until: now + pollMillis.minute,
110
+ line: { _tag: "Unread", reason: "repo start history incomplete" },
111
+ };
112
+ const { plan } = counts;
113
+ if (plan.nextStartDollars !== 0)
114
+ return {
115
+ _tag: "Wait",
116
+ until: now + pollMillis.minute,
117
+ line: { _tag: "Paid", nextStartDollars: plan.nextStartDollars },
118
+ };
119
+ for (const window of windows) {
120
+ const used = plan.used[window];
121
+ const line = plan.limits[window] - 20;
122
+ if (used + request.jobs > line)
123
+ return window === "day"
124
+ ? { _tag: "Hold", line: { _tag: "Account", window, used, line } }
125
+ : {
126
+ _tag: "Wait",
127
+ until: now + pollMillis[window],
128
+ line: { _tag: "Account", window, used, line },
129
+ };
130
+ }
131
+ for (const window of windows) {
132
+ const starts = counts.repo.starts
133
+ .filter((at) => at > now - windowMillis[window])
134
+ .toSorted((left, right) => left - right);
135
+ const used = starts.length;
136
+ const budget = Math.floor(share.share * plan.limits[window]);
137
+ if (used + request.jobs <= budget) continue;
138
+ const line: Line = {
139
+ _tag: "Budget",
140
+ repo: request.repo,
141
+ window,
142
+ used,
143
+ budget,
144
+ };
145
+ const expires = starts[used + request.jobs - budget - 1];
146
+ return request.jobs > budget || expires === undefined
147
+ ? { _tag: "Hold", line }
148
+ : { _tag: "Wait", until: expires + windowMillis[window], line };
149
+ }
150
+ return { _tag: "Admit" };
151
+ };
@@ -0,0 +1,171 @@
1
+ import * as Schema from "effect/Schema";
2
+ import { parse } from "yaml";
3
+
4
+ export const BOAT_JOBS_PER_RUN = 2;
5
+
6
+ const Matrix = Schema.Record(Schema.String, Schema.Array(Schema.Unknown));
7
+ const Workflow = Schema.Struct({
8
+ name: Schema.optionalKey(Schema.String),
9
+ on: Schema.optionalKey(
10
+ Schema.Union([
11
+ Schema.String,
12
+ Schema.Array(Schema.String),
13
+ Schema.Record(Schema.String, Schema.Unknown),
14
+ ])
15
+ ),
16
+ jobs: Schema.Record(
17
+ Schema.String,
18
+ Schema.Struct({
19
+ "runs-on": Schema.optionalKey(
20
+ Schema.Union([Schema.String, Schema.Array(Schema.String)])
21
+ ),
22
+ uses: Schema.optionalKey(Schema.String),
23
+ strategy: Schema.optionalKey(
24
+ Schema.Struct({
25
+ matrix: Schema.optionalKey(Schema.Union([Schema.String, Matrix])),
26
+ })
27
+ ),
28
+ })
29
+ ),
30
+ });
31
+ const Descendant = Schema.Struct({
32
+ workflow_run: Schema.Struct({
33
+ workflows: Schema.Union([Schema.String, Schema.Array(Schema.String)]),
34
+ types: Schema.optionalKey(
35
+ Schema.Union([Schema.String, Schema.Array(Schema.String)])
36
+ ),
37
+ }),
38
+ });
39
+ type WorkflowFile = readonly [path: string, text: string];
40
+ type Parsed = {
41
+ readonly path: string;
42
+ readonly workflow: typeof Workflow.Type;
43
+ };
44
+
45
+ const dynamic = (value: unknown): boolean => {
46
+ try {
47
+ return JSON.stringify(value).includes("${{");
48
+ } catch {
49
+ return true;
50
+ }
51
+ };
52
+
53
+ export const boatJobFindings = (
54
+ files: ReadonlyArray<WorkflowFile>
55
+ ): ReadonlyArray<string> => {
56
+ const findings: string[] = [];
57
+ const workflows: Parsed[] = [];
58
+ for (const [path, text] of files) {
59
+ try {
60
+ workflows.push({
61
+ path,
62
+ workflow: Schema.decodeUnknownSync(Workflow)(parse(text)),
63
+ });
64
+ } catch {
65
+ findings.push(`${path}: workflow unread`);
66
+ }
67
+ }
68
+ const after = (
69
+ entry: Parsed
70
+ ): { readonly names: ReadonlyArray<string>; readonly copies: number } => {
71
+ const events = entry.workflow.on;
72
+ if (!Schema.is(Descendant)(events)) {
73
+ if (typeof events === "object" && "workflow_run" in events)
74
+ findings.push(`${entry.path}: workflow_run unread`);
75
+ return { names: [], copies: 0 };
76
+ }
77
+ const names = events.workflow_run.workflows;
78
+ const selectors = typeof names === "string" ? [names] : names;
79
+ if (selectors.some((name) => /[*!?[\]]/u.test(name)))
80
+ findings.push(`${entry.path}: workflow_run pattern unresolved`);
81
+ const types = events.workflow_run.types;
82
+ if (types !== undefined && dynamic(types))
83
+ findings.push(`${entry.path}: dynamic workflow_run types`);
84
+ return {
85
+ names: selectors,
86
+ copies:
87
+ types === undefined
88
+ ? 3
89
+ : new Set(typeof types === "string" ? [types] : types).size,
90
+ };
91
+ };
92
+ const count = (
93
+ entry: Parsed,
94
+ parents: ReadonlyArray<string>,
95
+ descendants: boolean
96
+ ): number => {
97
+ if (parents.includes(entry.path)) {
98
+ findings.push(`${entry.path}: workflow cycle`);
99
+ return 0;
100
+ }
101
+ const stack = [...parents, entry.path];
102
+ let total = 0;
103
+ for (const [name, job] of Object.entries(entry.workflow.jobs)) {
104
+ const label = `${entry.path} ${name}`;
105
+ const matrix = job.strategy?.matrix;
106
+ let copies = 1;
107
+ if (matrix !== undefined) {
108
+ if (typeof matrix === "string" || dynamic(matrix)) {
109
+ findings.push(`${label}: dynamic matrix`);
110
+ } else {
111
+ const axes = Object.entries(matrix).filter(
112
+ ([axis]) => axis !== "include" && axis !== "exclude"
113
+ );
114
+ copies =
115
+ (axes.length === 0
116
+ ? 0
117
+ : axes.reduce(
118
+ (product, [, values]) => product * values.length,
119
+ 1
120
+ )) + (matrix.include?.length ?? 0);
121
+ }
122
+ }
123
+ if (job.uses !== undefined) {
124
+ if (!/^\.\/\.github\/workflows\/[^/]+\.ya?ml$/u.test(job.uses)) {
125
+ findings.push(`${label}: remote or unresolved reusable workflow`);
126
+ continue;
127
+ }
128
+ const target = job.uses.slice(2);
129
+ const called = workflows.find(
130
+ ({ path }) =>
131
+ path === target || `.github/workflows/${path}` === target
132
+ );
133
+ if (called === undefined)
134
+ findings.push(`${label}: reusable workflow ${target} unread`);
135
+ else total += copies * count(called, stack, false);
136
+ } else if (job["runs-on"] === undefined || dynamic(job["runs-on"])) {
137
+ findings.push(`${label}: dynamic or unread runs-on`);
138
+ } else {
139
+ const runners = job["runs-on"];
140
+ if (
141
+ (typeof runners === "string" ? [runners] : runners).some(
142
+ (runner) => runner.split("/")[0]?.startsWith("boat") === true
143
+ )
144
+ )
145
+ total += copies;
146
+ }
147
+ }
148
+ if (descendants)
149
+ for (const child of workflows) {
150
+ const { names, copies } = after(child);
151
+ if (dynamic(names))
152
+ findings.push(`${child.path}: dynamic workflow_run`);
153
+ const file = entry.path.split("/").at(-1) ?? entry.path;
154
+ const rootNames =
155
+ entry.workflow.name === undefined
156
+ ? [entry.path, file, `.github/workflows/${file}`]
157
+ : [entry.workflow.name];
158
+ if (rootNames.some((name) => names.includes(name)))
159
+ total += copies * count(child, stack, true);
160
+ }
161
+ return total;
162
+ };
163
+ for (const entry of workflows) {
164
+ const total = count(entry, [], true);
165
+ if (total > BOAT_JOBS_PER_RUN)
166
+ findings.push(
167
+ `${entry.path}: closure starts ${total} Boat jobs, limit ${BOAT_JOBS_PER_RUN}`
168
+ );
169
+ }
170
+ return [...new Set(findings)];
171
+ };
package/src/starts.ts ADDED
@@ -0,0 +1,84 @@
1
+ import * as Clock from "effect/Clock";
2
+ import * as Effect from "effect/Effect";
3
+ import * as Schema from "effect/Schema";
4
+
5
+ import { BoatStarts } from "./starts/boat.ts";
6
+ import {
7
+ decide,
8
+ Line,
9
+ pollMillis,
10
+ type StartRequest,
11
+ } from "./starts/budget.ts";
12
+
13
+ export { BoatStarts, StartReadError } from "./starts/boat.ts";
14
+ export { decide, Repo, startShares } from "./starts/budget.ts";
15
+ export type {
16
+ Admission,
17
+ Counts,
18
+ PerWindow,
19
+ Plan,
20
+ RepoStarts,
21
+ Share,
22
+ StartRequest,
23
+ Window,
24
+ } from "./starts/budget.ts";
25
+ export { boatJobFindings, BOAT_JOBS_PER_RUN } from "./starts/policy.ts";
26
+ export type { Line } from "./starts/budget.ts";
27
+
28
+ export class StartHeld extends Schema.TaggedError<
29
+ StartHeld,
30
+ { readonly brand: unique symbol }
31
+ >()("StartHeld", {
32
+ line: Line,
33
+ }) {}
34
+
35
+ export const admitStart = Effect.fn("Starts.admitStart")(function* <A, E, R>(
36
+ request: StartRequest,
37
+ start: Effect.Effect<A, E, R>,
38
+ { deadline }: { readonly deadline: number }
39
+ ) {
40
+ const boat = yield* BoatStarts;
41
+ let last: Line = {
42
+ _tag: "Unread",
43
+ reason: "start deadline reached",
44
+ };
45
+ for (;;) {
46
+ const remaining = deadline - (yield* Clock.currentTimeMillis);
47
+ if (!Number.isFinite(remaining) || remaining <= 0)
48
+ return yield* new StartHeld({ line: last });
49
+ const counts = yield* Effect.gen(function* () {
50
+ const plan = yield* boat.plan;
51
+ const repo = yield* boat.repoStarts(request.repo);
52
+ return { now: yield* Clock.currentTimeMillis, plan, repo };
53
+ }).pipe(
54
+ Effect.catchTag("StartReadError", () => Effect.undefined),
55
+ Effect.timeoutOrElse({
56
+ duration: remaining,
57
+ orElse: () => Effect.fail(new StartHeld({ line: last })),
58
+ })
59
+ );
60
+ const now = yield* Clock.currentTimeMillis;
61
+ const decision = decide(request, counts, now);
62
+ if (decision._tag === "Hold")
63
+ return yield* new StartHeld({ line: decision.line });
64
+ if (!Number.isFinite(deadline) || now >= deadline)
65
+ return yield* new StartHeld({
66
+ line:
67
+ decision._tag === "Wait"
68
+ ? decision.line
69
+ : { _tag: "Unread", reason: "start deadline reached" },
70
+ });
71
+ if (decision._tag === "Admit") return yield* start;
72
+ last = decision.line;
73
+ const window =
74
+ decision.line._tag === "Account" || decision.line._tag === "Budget"
75
+ ? decision.line.window
76
+ : "minute";
77
+ yield* Effect.sleep(
78
+ Math.max(
79
+ 0,
80
+ Math.min(decision.until, now + pollMillis[window], deadline) - now
81
+ )
82
+ );
83
+ }
84
+ });