@fabrika/app 0.9.0-cloudflare.2 → 0.9.0-cloudflare.3

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.
Files changed (53) hide show
  1. package/package.json +9 -9
  2. package/skill/SKILL.md +20 -18
  3. package/skill/references/app-setup.md +29 -16
  4. package/skill/references/endpoint.md +24 -22
  5. package/skill/references/errors.md +3 -2
  6. package/skill/references/jobs.md +13 -3
  7. package/skill/references/tests.md +7 -0
  8. package/src/bun.ts +159 -6
  9. package/src/cloudflare/application.ts +543 -73
  10. package/src/cloudflare/export.ts +621 -0
  11. package/src/cloudflare/import.ts +1097 -0
  12. package/src/cloudflare/maintenance.ts +518 -0
  13. package/src/cloudflare/ops.ts +147 -18
  14. package/src/cloudflare/restore.ts +167 -0
  15. package/src/cloudflare/tracker.ts +192 -0
  16. package/src/cloudflare.ts +3 -2
  17. package/src/contract/artifact-schema.ts +7 -1
  18. package/src/contract/build.ts +6 -2
  19. package/src/contract/context.ts +26 -9
  20. package/src/contract/defaults.ts +22 -2
  21. package/src/contract/define.ts +1 -1
  22. package/src/contract/group.ts +1 -1
  23. package/src/files/kinds.ts +54 -24
  24. package/src/implement/anonymous.ts +1 -10
  25. package/src/implement/boot.ts +21 -9
  26. package/src/implement/dispatch.ts +171 -33
  27. package/src/implement/egress.ts +34 -8
  28. package/src/implement/invocation.ts +50 -10
  29. package/src/implement/workload.ts +18 -3
  30. package/src/jobs/runner.ts +639 -96
  31. package/src/testing/kit.ts +60 -0
  32. package/types/src/bun.d.ts +34 -1
  33. package/types/src/cloudflare/application.d.ts +36 -5
  34. package/types/src/cloudflare/export.d.ts +16 -0
  35. package/types/src/cloudflare/import.d.ts +58 -0
  36. package/types/src/cloudflare/maintenance.d.ts +117 -0
  37. package/types/src/cloudflare/ops.d.ts +39 -4
  38. package/types/src/cloudflare/restore.d.ts +9 -0
  39. package/types/src/cloudflare/tracker.d.ts +29 -0
  40. package/types/src/cloudflare.d.ts +2 -1
  41. package/types/src/contract/artifact-schema.d.ts +2 -0
  42. package/types/src/contract/context.d.ts +24 -9
  43. package/types/src/contract/defaults.d.ts +19 -1
  44. package/types/src/contract/define.d.ts +1 -1
  45. package/types/src/contract/group.d.ts +1 -1
  46. package/types/src/files/kinds.d.ts +17 -6
  47. package/types/src/implement/anonymous.d.ts +0 -4
  48. package/types/src/implement/boot.d.ts +11 -0
  49. package/types/src/implement/dispatch.d.ts +31 -0
  50. package/types/src/implement/invocation.d.ts +17 -7
  51. package/types/src/implement/workload.d.ts +5 -0
  52. package/types/src/jobs/runner.d.ts +60 -2
  53. package/types/src/testing/kit.d.ts +16 -0
@@ -0,0 +1,518 @@
1
+ // The object's maintenance barrier (ADR-0069 §3): its mode and generation, whether R2 holds them, the transitions
2
+ // Control drives, the drain of what runs, and the write fence every invocation checks. The durable copy is an R2
3
+ // object in the environment's bucket, never SQLite or KV, which point-in-time recovery rewinds; so is the generation
4
+ // since which the object has written nothing (ADR-0070 §2), in an object of its own that no older release reads.
5
+
6
+ import {
7
+ OPS_MODES,
8
+ OPS_STATE_KEY,
9
+ type OpsMaintenance,
10
+ type OpsMode,
11
+ type OpsPublishedState,
12
+ type OpsStateAck,
13
+ opsTransitionRefused,
14
+ } from '@fabrika/auth-core'
15
+ import type { InvocationAdmission, InvocationGate, InvocationKind } from '../implement/dispatch.js'
16
+ import { LEASE_GRACE_MS } from '../jobs/runner.js'
17
+ import { method } from './bindings.js'
18
+
19
+ /** A handler's share of the drain's bound; a job's lease grace follows it, as Control's request timeout assumes. */
20
+ const DRAIN_HANDLER_MS = 25_000
21
+ export const DRAIN_BOUND_MS = DRAIN_HANDLER_MS + LEASE_GRACE_MS
22
+
23
+ /** How often a transition puts again after a conflict whose R2 state it did not adopt. */
24
+ const PUT_ATTEMPTS = 3
25
+
26
+ /** The state R2 holds, and its version: the etag a conditional put names. */
27
+ export interface StoredMaintenance {
28
+ readonly state: OpsPublishedState
29
+ readonly version: string
30
+ }
31
+
32
+ /**
33
+ * Since which generation the object has written nothing, as of the published generation `generation`: kept only while
34
+ * it is `read-only`, `closed` or `inspect`.
35
+ */
36
+ export interface FrozenRecord {
37
+ readonly generation: number
38
+ readonly since: number
39
+ }
40
+
41
+ /** The object's durable copy of its maintenance state. */
42
+ export interface MaintenanceStore {
43
+ /** `null` only for a definite not-found; every other failure throws, and is never read as absence. */
44
+ read(): Promise<StoredMaintenance | null>
45
+ /** Puts `state` if R2 still holds `version` (`null`: holds nothing); the new version, or `null` when the condition failed. */
46
+ put(state: OpsPublishedState, version: string | null): Promise<string | null>
47
+ /** The frozen record, `null` when none is stored. A store without these keeps the record in memory only. */
48
+ readFrozen?(): Promise<FrozenRecord | null>
49
+ putFrozen?(record: FrozenRecord): Promise<void>
50
+ }
51
+
52
+ /** `__fabrika/ops/<object>.json` in the environment's bucket (`bucket`, an R2 binding). */
53
+ export function r2MaintenanceStore(bucket: unknown, object: string): MaintenanceStore {
54
+ const key = OPS_STATE_KEY(object)
55
+ // Beside the state, never in it: an older release parses the state strictly and must still load it.
56
+ const frozenKey = `${key.slice(0, -'.json'.length)}.frozen.json`
57
+ const call = (name: string): (...args: unknown[]) => unknown => {
58
+ const found = method(bucket, name)
59
+ if (found === null) {
60
+ throw new Error(`the FABRIKA_FILES binding has no ${name}; the maintenance state lives in the environment's bucket`)
61
+ }
62
+ return found
63
+ }
64
+ return {
65
+ async read() {
66
+ const answer: unknown = await call('get')(key)
67
+ if (answer === null) {
68
+ return null
69
+ }
70
+ const version = typeof answer === 'object' ? Reflect.get(answer, 'etag') : undefined
71
+ const text = method(answer, 'text')
72
+ if (typeof version !== 'string' || version === '' || text === null) {
73
+ throw new Error('R2 answered the maintenance state without its etag or body')
74
+ }
75
+ const body: unknown = await text()
76
+ const state = typeof body === 'string' ? parseStoredState(body) : null
77
+ if (state === null) {
78
+ throw new Error('the maintenance state in R2 does not parse')
79
+ }
80
+ return { state, version }
81
+ },
82
+ async put(state, version) {
83
+ const onlyIf = version === null ? { etagDoesNotMatch: '*' } : { etagMatches: version }
84
+ const answer: unknown = await call('put')(key, JSON.stringify(state), { httpMetadata: { contentType: 'application/json' }, onlyIf })
85
+ if (answer === null) {
86
+ return null
87
+ }
88
+ const etag = typeof answer === 'object' ? Reflect.get(answer, 'etag') : undefined
89
+ if (typeof etag !== 'string' || etag === '') {
90
+ throw new Error('R2 answered the maintenance state put without its etag')
91
+ }
92
+ return etag
93
+ },
94
+ async readFrozen() {
95
+ const answer: unknown = await call('get')(frozenKey)
96
+ if (answer === null) {
97
+ return null
98
+ }
99
+ const text = method(answer, 'text')
100
+ const body: unknown = text === null ? null : await text()
101
+ const record = typeof body === 'string' ? parseFrozenRecord(body) : null
102
+ if (record === null) {
103
+ throw new Error('the frozen record in R2 does not parse')
104
+ }
105
+ return record
106
+ },
107
+ async putFrozen(record) {
108
+ await call('put')(frozenKey, JSON.stringify(record), { httpMetadata: { contentType: 'application/json' } })
109
+ },
110
+ }
111
+ }
112
+
113
+ /** Exactly two positive generations, the stretch's start not after the generation it was recorded at. */
114
+ function parseFrozenRecord(text: string): FrozenRecord | null {
115
+ let value: unknown
116
+ try {
117
+ value = JSON.parse(text)
118
+ } catch {
119
+ return null
120
+ }
121
+ if (typeof value !== 'object' || value === null || Array.isArray(value) || Object.keys(value).length !== 2) {
122
+ return null
123
+ }
124
+ const generation: unknown = Reflect.get(value, 'generation')
125
+ const since: unknown = Reflect.get(value, 'since')
126
+ return positive(generation) && positive(since) && since <= generation ? { generation, since } : null
127
+ }
128
+
129
+ function positive(value: unknown): value is number {
130
+ return typeof value === 'number' && Number.isSafeInteger(value) && value > 0
131
+ }
132
+
133
+ /** The stored record, parsed strictly: exactly a positive generation and a mode. */
134
+ function parseStoredState(text: string): OpsPublishedState | null {
135
+ let value: unknown
136
+ try {
137
+ value = JSON.parse(text)
138
+ } catch {
139
+ return null
140
+ }
141
+ if (typeof value !== 'object' || value === null || Array.isArray(value) || Object.keys(value).length !== 2) {
142
+ return null
143
+ }
144
+ const generation: unknown = Reflect.get(value, 'generation')
145
+ const mode = OPS_MODES.find((candidate) => candidate === Reflect.get(value, 'mode'))
146
+ if (typeof generation !== 'number' || !Number.isSafeInteger(generation) || generation <= 0 || mode === undefined) {
147
+ return null
148
+ }
149
+ return { generation, mode }
150
+ }
151
+
152
+ /** What each mode admits of ordinary invocations; ops requests are admitted in every mode. */
153
+ const ADMITTED: Readonly<Record<OpsMode, ReadonlySet<InvocationKind>>> = {
154
+ open: new Set(['read', 'write', 'webhook', 'kick', 'job', 'framework-job']),
155
+ 'read-only': new Set(['read']),
156
+ closed: new Set(),
157
+ inspect: new Set(),
158
+ }
159
+
160
+ /** The kinds a drain aborts at once; a request gets the handler's share of the bound and is fenced. */
161
+ const STOPPABLE: ReadonlySet<InvocationKind> = new Set(['kick', 'job', 'framework-job'])
162
+
163
+ export type TransitionResult =
164
+ | { readonly kind: 'acknowledged'; readonly ack: OpsStateAck }
165
+ /** The 409: what R2 holds as far as the object knows, `null` before the first publication. */
166
+ | { readonly kind: 'stale'; readonly published: OpsPublishedState | null }
167
+ /** R2 could not be read or written: the call fails and Control retries. */
168
+ | { readonly kind: 'failed' }
169
+ /** The caller's `frozen` held the object in `inspect`: nothing changed. */
170
+ | { readonly kind: 'frozen' }
171
+
172
+ export type MigrateResult<T> = { readonly kind: 'migrated'; readonly value: T } | {
173
+ readonly kind: 'stale'
174
+ readonly published: OpsPublishedState | null
175
+ }
176
+
177
+ /** What a step run in the barrier's turn answers, and what keeps the turn past the answer (`null`: nothing). */
178
+ export interface TurnStep<T> {
179
+ readonly value: T
180
+ readonly holdUntil: Promise<void> | null
181
+ }
182
+
183
+ export type StepResult<T> = { readonly kind: 'ran'; readonly value: T } | {
184
+ readonly kind: 'stale'
185
+ readonly published: OpsPublishedState | null
186
+ }
187
+
188
+ /** One unit the drain waits for: an admitted invocation, or work it handed on that outlives it. */
189
+ interface Unit {
190
+ readonly kind: InvocationKind
191
+ }
192
+
193
+ export interface BarrierOptions {
194
+ /** The drain's bound; `DRAIN_BOUND_MS` by default. */
195
+ readonly drainBoundMs?: number
196
+ }
197
+
198
+ export class MaintenanceBarrier {
199
+ #mode: OpsMode
200
+ #generation: number | null
201
+ /** What R2 holds as far as this instance knows: as last read, written or adopted. */
202
+ #stored: OpsPublishedState | null
203
+ #version: string | null
204
+ /** The generation since which the object has written nothing, while it is published in a mode that writes nothing. */
205
+ #frozenSince: number | null
206
+ readonly #store: MaintenanceStore
207
+ readonly #drainBoundMs: number
208
+ /** One transition at a time: each waits for the one before it. */
209
+ #turn: Promise<void> = Promise.resolve()
210
+ readonly #units = new Set<Unit>()
211
+ readonly #stops = new Map<AbortController, InvocationKind>()
212
+ #settled: (() => void)[] = []
213
+
214
+ private constructor(store: MaintenanceStore, stored: StoredMaintenance | null, frozen: FrozenRecord | null, options: BarrierOptions) {
215
+ this.#store = store
216
+ this.#stored = stored?.state ?? null
217
+ this.#version = stored?.version ?? null
218
+ this.#mode = stored?.state.mode ?? 'open'
219
+ this.#generation = stored?.state.generation ?? null
220
+ this.#frozenSince = stored === null ? null : frozenOnLoad(stored.state, frozen)
221
+ this.#drainBoundMs = options.drainBoundMs ?? DRAIN_BOUND_MS
222
+ }
223
+
224
+ /** The cold start: an absent state is `open`; a failed read rejects, and the caller retries on its next request. */
225
+ static async load(store: MaintenanceStore, options: BarrierOptions = {}): Promise<MaintenanceBarrier> {
226
+ const stored = await store.read()
227
+ const frozen = stored === null || stored.state.mode === 'open' ? null : ((await store.readFrozen?.()) ?? null)
228
+ return new MaintenanceBarrier(store, stored, frozen, options)
229
+ }
230
+
231
+ get mode(): OpsMode {
232
+ return this.#mode
233
+ }
234
+
235
+ view(): OpsMaintenance {
236
+ return { mode: this.#mode, generation: this.#generation, published: this.#isPublished() }
237
+ }
238
+
239
+ /** What R2 holds as far as this instance knows, `null` before the first publication: what a stale refusal names. */
240
+ get published(): OpsPublishedState | null {
241
+ return this.#stored
242
+ }
243
+
244
+ /**
245
+ * The generation at which the object entered its current stretch of `read-only`, `closed` and `inspect`, or at which a
246
+ * data step last wrote within it; `null` outside such a stretch. A consistent dump is one state while it holds.
247
+ */
248
+ get frozenSince(): number | null {
249
+ return this.#frozenSince
250
+ }
251
+
252
+ /**
253
+ * Called in a data step's turn before the step writes while the object writes nothing else (an import step, a
254
+ * restore's `arm`): the stretch starts again at the current generation, durably before the write. A failed put rejects.
255
+ */
256
+ async restrictedWrite(): Promise<void> {
257
+ if (this.#mode === 'open' || this.#generation === null || this.#frozenSince === this.#generation) {
258
+ return
259
+ }
260
+ this.#frozenSince = this.#generation
261
+ await this.#store.putFrozen?.({ generation: this.#generation, since: this.#generation })
262
+ }
263
+
264
+ /** The scope of one invocation, admitted now: the generation and mode it captures, which its writes are fenced on. */
265
+ event(): BarrierEvent {
266
+ return new BarrierEvent(this, this.#generation, this.#mode)
267
+ }
268
+
269
+ /** Whether a write of an invocation admitted at `generation` in `mode` may commit now. */
270
+ writable(generation: number | null, mode: OpsMode): boolean {
271
+ return mode === 'open' && this.#mode === 'open' && this.#generation === generation
272
+ }
273
+
274
+ /** Admits an invocation of `kind` captured at `generation`, or `null` when the mode refuses it or a transition followed. */
275
+ admit(kind: InvocationKind, generation: number | null): InvocationAdmission | null {
276
+ if (!ADMITTED[this.#mode].has(kind) || this.#generation !== generation) {
277
+ return null
278
+ }
279
+ const unit: Unit = { kind }
280
+ const stop = new AbortController()
281
+ this.#units.add(unit)
282
+ this.#stops.set(stop, kind)
283
+ let released = false
284
+ return {
285
+ signal: stop.signal,
286
+ track: (work) => {
287
+ const outliving: Unit = { kind }
288
+ this.#units.add(outliving)
289
+ const done = () => this.#leave(outliving)
290
+ work.then(done, done)
291
+ },
292
+ release: () => {
293
+ if (!released) {
294
+ released = true
295
+ this.#stops.delete(stop)
296
+ this.#leave(unit)
297
+ }
298
+ },
299
+ }
300
+ }
301
+
302
+ /**
303
+ * `POST /__fabrika/ops/state`: the transition of ADR-0069 §3, acknowledged once published and drained. `frozen` is
304
+ * asked in the turn, after every data step before it: while it holds, no transition leaves `inspect`.
305
+ */
306
+ transition(requested: OpsPublishedState, frozen: () => boolean = () => false): Promise<TransitionResult> {
307
+ // Exactly the state: what R2 stores and a stale refusal names.
308
+ const request: OpsPublishedState = { generation: requested.generation, mode: requested.mode }
309
+ return this.#inTurn(async () => {
310
+ const current = this.#generation === null ? null : { generation: this.#generation, mode: this.#mode }
311
+ if (opsTransitionRefused(current, request)) {
312
+ return { kind: 'stale', published: this.#stored }
313
+ }
314
+ if (this.#mode === 'inspect' && request.mode !== 'inspect' && frozen()) {
315
+ return { kind: 'frozen' }
316
+ }
317
+ const retry = current !== null && current.generation === request.generation
318
+ if (!retry || !this.#isPublished()) {
319
+ if (rank(request.mode) > rank(this.#mode)) {
320
+ // Before any await: from here no invocation of a class the mode forbids is admitted, and no older write commits.
321
+ this.#mode = request.mode
322
+ this.#generation = request.generation
323
+ }
324
+ const put = await this.#publish(request)
325
+ if (put.kind !== 'published') {
326
+ return put
327
+ }
328
+ await this.#froze(request)
329
+ }
330
+ const stillRunning = await this.#drain()
331
+ return { kind: 'acknowledged', ack: { generation: request.generation, mode: request.mode, stillRunning } }
332
+ })
333
+ }
334
+
335
+ /**
336
+ * `POST /__fabrika/ops/migrate`: `work` runs only under the published generation, in a mode that may migrate, and no
337
+ * transition runs meanwhile.
338
+ */
339
+ migrate<T>(generation: number, work: () => Promise<T>): Promise<MigrateResult<T>> {
340
+ return this.#inTurn(async () => {
341
+ if (!this.#isPublished() || this.#generation !== generation || this.#mode === 'inspect') {
342
+ return { kind: 'stale', published: this.#stored }
343
+ }
344
+ return { kind: 'migrated', value: await work() }
345
+ })
346
+ }
347
+
348
+ /**
349
+ * A data step of Control's (ADR-0070): `work` runs in the barrier's turn, only under the published `generation`, with
350
+ * the mode it is in. No transition runs until `work` settles, nor, when it answers one, until `holdUntil` settles.
351
+ */
352
+ async step<T>(generation: number, work: (mode: OpsMode) => Promise<TurnStep<T>>): Promise<StepResult<T>> {
353
+ const previous = this.#turn
354
+ const done = Promise.withResolvers<void>()
355
+ this.#turn = done.promise
356
+ let holdUntil: Promise<void> | null = null
357
+ await previous
358
+ try {
359
+ if (!this.#isPublished() || this.#generation !== generation) {
360
+ return { kind: 'stale', published: this.#stored }
361
+ }
362
+ const answered = await work(this.#mode)
363
+ holdUntil = answered.holdUntil
364
+ return { kind: 'ran', value: answered.value }
365
+ } finally {
366
+ if (holdUntil === null) {
367
+ done.resolve()
368
+ } else {
369
+ const release = () => done.resolve()
370
+ holdUntil.then(release, release)
371
+ }
372
+ }
373
+ }
374
+
375
+ /**
376
+ * After `request` is published: `open` ends the stretch, a mode that writes nothing keeps it or starts it at the
377
+ * request's generation. A failed put of the record is left to the cold start, which then starts the stretch anew.
378
+ */
379
+ async #froze(request: OpsPublishedState): Promise<void> {
380
+ if (request.mode === 'open') {
381
+ this.#frozenSince = null
382
+ return
383
+ }
384
+ this.#frozenSince ??= request.generation
385
+ try {
386
+ await this.#store.putFrozen?.({ generation: request.generation, since: this.#frozenSince })
387
+ } catch {
388
+ // The stored record then names an older generation or none, which a cold start reads as a stretch starting anew.
389
+ }
390
+ }
391
+
392
+ #isPublished(): boolean {
393
+ return this.#stored !== null && this.#stored.generation === this.#generation && this.#stored.mode === this.#mode
394
+ }
395
+
396
+ /** Step 3: the conditional put; on success an opening transition switches memory, on a conflict R2 is read again. */
397
+ async #publish(request: OpsPublishedState): Promise<{ readonly kind: 'published' } | Exclude<TransitionResult, { kind: 'acknowledged' }>> {
398
+ for (let attempt = 0; attempt < PUT_ATTEMPTS; attempt++) {
399
+ let version: string | null
400
+ try {
401
+ version = await this.#store.put(request, this.#version)
402
+ } catch {
403
+ return { kind: 'failed' }
404
+ }
405
+ if (version !== null) {
406
+ this.#stored = request
407
+ this.#version = version
408
+ this.#mode = request.mode
409
+ this.#generation = request.generation
410
+ return { kind: 'published' }
411
+ }
412
+ let stored: StoredMaintenance | null
413
+ try {
414
+ stored = await this.#store.read()
415
+ } catch {
416
+ return { kind: 'failed' }
417
+ }
418
+ this.#version = stored?.version ?? null
419
+ this.#stored = stored?.state ?? null
420
+ // A higher generation, or the same one in another mode, is published elsewhere: adopted, never overwritten.
421
+ if (stored !== null && opsTransitionRefused(stored.state, request)) {
422
+ this.#mode = stored.state.mode
423
+ this.#generation = stored.state.generation
424
+ // What happened before it is unknown: its stretch starts at it.
425
+ this.#frozenSince = stored.state.mode === 'open' ? null : stored.state.generation
426
+ return { kind: 'stale', published: stored.state }
427
+ }
428
+ }
429
+ return { kind: 'failed' }
430
+ }
431
+
432
+ /** Step 4: stops every run the mode forbids, then waits for what it forbids to settle, within the bound. */
433
+ async #drain(): Promise<number> {
434
+ const admitted = ADMITTED[this.#mode]
435
+ for (const [stop, kind] of this.#stops) {
436
+ if (STOPPABLE.has(kind) && !admitted.has(kind)) {
437
+ stop.abort()
438
+ }
439
+ }
440
+ const running = () => [...this.#units].filter((unit) => !admitted.has(unit.kind)).length
441
+ if (running() === 0) {
442
+ return 0
443
+ }
444
+ const bound = Promise.withResolvers<void>()
445
+ const timer = setTimeout(bound.resolve, this.#drainBoundMs)
446
+ try {
447
+ while (running() > 0) {
448
+ const settled = Promise.withResolvers<void>()
449
+ this.#settled.push(settled.resolve)
450
+ if ((await Promise.race([settled.promise.then(() => 'settled' as const), bound.promise.then(() => 'bound' as const)])) === 'bound') {
451
+ break
452
+ }
453
+ }
454
+ } finally {
455
+ clearTimeout(timer)
456
+ }
457
+ return running()
458
+ }
459
+
460
+ #leave(unit: Unit): void {
461
+ this.#units.delete(unit)
462
+ const waiting = this.#settled
463
+ this.#settled = []
464
+ for (const resolve of waiting) {
465
+ resolve()
466
+ }
467
+ }
468
+
469
+ async #inTurn<T>(work: () => Promise<T>): Promise<T> {
470
+ const previous = this.#turn
471
+ const done = Promise.withResolvers<void>()
472
+ this.#turn = done.promise
473
+ await previous
474
+ try {
475
+ return await work()
476
+ } finally {
477
+ done.resolve()
478
+ }
479
+ }
480
+ }
481
+
482
+ /**
483
+ * The stretch a cold start resumes: none while `open`; the record's when it was written at the published generation;
484
+ * otherwise, conservatively, one starting at the published generation.
485
+ */
486
+ function frozenOnLoad(state: OpsPublishedState, frozen: FrozenRecord | null): number | null {
487
+ if (state.mode === 'open') {
488
+ return null
489
+ }
490
+ return frozen !== null && frozen.generation === state.generation && frozen.since <= state.generation ? frozen.since : state.generation
491
+ }
492
+
493
+ /** How restrictive a mode is: `open` least, `inspect` most. */
494
+ function rank(mode: OpsMode): number {
495
+ return OPS_MODES.indexOf(mode)
496
+ }
497
+
498
+ /** One invocation's view of the barrier: the gate that admits and counts its work, and its write fence. */
499
+ export class BarrierEvent implements InvocationGate {
500
+ readonly #barrier: MaintenanceBarrier
501
+ readonly #generation: number | null
502
+ readonly #mode: OpsMode
503
+
504
+ constructor(barrier: MaintenanceBarrier, generation: number | null, mode: OpsMode) {
505
+ this.#barrier = barrier
506
+ this.#generation = generation
507
+ this.#mode = mode
508
+ }
509
+
510
+ admit(kind: InvocationKind): InvocationAdmission | null {
511
+ return this.#barrier.admit(kind, this.#generation)
512
+ }
513
+
514
+ /** Whether this invocation may commit a write now: still `open`, at the generation it was admitted under. */
515
+ writable(): boolean {
516
+ return this.#barrier.writable(this.#generation, this.#mode)
517
+ }
518
+ }