@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

main
ts 708 lines 26 KB
Raw
1 import type { HttpEffect } from "alchemy/Http";
2 import * as Context from "effect/Context";
3 import * as Effect from "effect/Effect";
4 import * as Schema from "effect/Schema";
5 import { Scope } from "effect/Scope";
6 import type * as Stream from "effect/Stream";
7 import * as Aggregate from "./Aggregate.ts";
8 import type { Plan } from "./Backfill.ts";
9 import type { ReplayInput, ReplayResult } from "./CatchUp.ts";
10 import { ModelHostedTwice } from "./DefinitionError.ts";
11 import { DefinitionError } from "./internal.ts";
12 import type * as Policy from "./Policy.ts";
13 import type * as Projection from "./Projection.ts";
14 import type * as DomainStream from "./Stream.ts";
15 import { TraceJson } from "./Telemetry.ts";
16 import type * as View from "./View.ts";
17
18 /**
19 * Capture the services `R` for later use, minus the `Scope`: a captured
20 * construction-time scope must never replace the scope of a later request or
21 * event (finalizers would attach to the wrong lifetime, and on workerd the
22 * work would be pinned to another request's I/O context). Platforms that host
23 * a model call this when they are built.
24 */
25 export const captureContext = <R = never>(): Effect.Effect<
26 Context.Context<Exclude<R, Scope>>,
27 never,
28 R
29 > =>
30 Effect.map(
31 Effect.context<R>(),
32 (context) => Context.omit(Scope)(context) as Context.Context<Exclude<R, Scope>>,
33 );
34
35 /**
36 * Everything a platform persists or sends is plain JSON. The kernel owns the
37 * schemas; platforms only move and store these values.
38 */
39 export type Json = unknown;
40
41 /**
42 * An event envelope in JSON form. `at` is epoch milliseconds.
43 */
44 export const EnvelopeJson = Schema.Struct({
45 ...Aggregate.Envelope.fields,
46 at: Schema.Number,
47 /** Absent on events stored before correlation ids: the command id stands in. */
48 correlationId: Schema.optionalKey(Schema.String),
49 /** The span that committed the event, so its reactions continue or link to it. */
50 trace: Schema.optionalKey(TraceJson),
51 });
52 export type EnvelopeJson = typeof EnvelopeJson.Type;
53
54 /**
55 * A committed event as stored by an aggregate.
56 */
57 export interface StoredEvent {
58 readonly event: Json;
59 readonly envelope: EnvelopeJson;
60 }
61
62 /**
63 * A unit of work routed from one host to another: an event (from an aggregate
64 * or a view) to a view or policy. Deliveries are at least once; targets drop
65 * duplicates by `(source, seq)`. Platforms must deliver in order per
66 * `(source, target)`.
67 */
68 export interface Delivery {
69 readonly target: {
70 readonly kind: "view" | "policy" | "projection";
71 readonly name: string;
72 /** The consumer's generation (see `Kernel.generationOf`), when it has been rebuilt. */
73 readonly generation?: number;
74 /** Rebuilt in the storage it had (see `Kernel.inPlace`): its id says `@` for `#`. */
75 readonly inPlace?: boolean;
76 };
77 /** The target partition: a key's id, or the source stream for an unkeyed policy. */
78 readonly key: string;
79 /** Named routes (from `keyOf`) the event takes into this key; absent for the default route. */
80 readonly routes?: ReadonlyArray<string>;
81 /** The source stream, e.g. `Account/a-1` or `Statement/a-1`. */
82 readonly source: string;
83 /** The event's sequence number in its source stream. */
84 readonly seq: number;
85 /** The aggregate or view that produced the event. */
86 readonly origin: string;
87 readonly tag: string;
88 readonly event: Json;
89 readonly envelope: EnvelopeJson;
90 /** For an event from a view: the view's encoded state after it. */
91 readonly state?: Json;
92 /**
93 * History: seeded (story `given`) or replayed to a consumer added after the
94 * event (see `CatchUp`). Views and projections apply it, policies ignore it.
95 */
96 readonly history?: boolean;
97 }
98
99 /**
100 * A client's live read (`watch` or `events`) of one key, in JSON form. A
101 * platform that pushes keeps it with the connection (on a WebSocket's
102 * attachment, so a hibernated object can resume pushing) and asks the kit's
103 * `push` what to send after each commit.
104 */
105 export const Subscription = Schema.Struct({
106 /** The client's request id, echoed as is (the client matches it by identity). */
107 requestId: Schema.Union([Schema.String, Schema.Number]),
108 mode: Schema.Literals(["watch", "events"]),
109 /** The client's filter: it narrows what a permitted read sends. */
110 where: Schema.optionalKey(Schema.Unknown),
111 /** The context the read's middleware provided (see `Domain.RequestContext`), for `validate`. */
112 context: Schema.Record(Schema.String, Schema.Unknown),
113 /** Progress: the last state version (`watch`) or event `seq` (`events`) sent. */
114 cursor: Schema.Number,
115 /** Set when the read was refused before reaching the key: the encoded `Exit` to send. */
116 refused: Schema.optionalKey(Schema.Unknown),
117 /** `events` only: set once the `CaughtUp` frame after the read's history was sent. */
118 caughtUpSent: Schema.optionalKey(Schema.Boolean),
119 });
120 export type Subscription = typeof Subscription.Type;
121
122 /**
123 * What to send a subscriber, from a kit's `push`.
124 */
125 export interface Push {
126 /** Effect RPC messages (a `Chunk`, then an `Exit` if the read ended), in JSON form. */
127 readonly messages: ReadonlyArray<Json>;
128 /** The subscription with its progress after these messages. */
129 readonly subscription: Subscription;
130 /** `validate` rejected the read: send the messages, then close the connection. */
131 readonly done: boolean;
132 }
133
134 /**
135 * Input to {@link AggregateKit.handle}.
136 */
137 export interface HandleInput {
138 readonly id: string;
139 /** The stored state, or `null` for an instance that has never committed. */
140 readonly state: Json;
141 readonly version: number;
142 readonly command: Json;
143 readonly commandId: string;
144 /** The context the command was sent with (see `Domain.RequestContext`). */
145 readonly context: Readonly<Record<string, Json>>;
146 /** Epoch milliseconds. */
147 readonly now: number;
148 /** The flow the command belongs to; the command id when it starts one. */
149 readonly correlationId?: string;
150 /** The span that sent the command. */
151 readonly trace?: TraceJson;
152 /** Link to `trace` instead of continuing it. */
153 readonly link?: boolean;
154 }
155
156 /**
157 * Result of {@link AggregateKit.handle}.
158 */
159 export type HandleResult =
160 | { readonly _tag: "Rejected"; readonly rejection: Json }
161 | {
162 readonly _tag: "Accepted";
163 readonly state: Json;
164 readonly version: number;
165 readonly events: ReadonlyArray<StoredEvent>;
166 readonly reply: Json;
167 readonly deliveries: ReadonlyArray<Delivery>;
168 };
169
170 /**
171 * The receipt of an accepted command, in JSON form.
172 */
173 export interface ReceiptJson {
174 readonly stream: string;
175 readonly version: number;
176 readonly events: ReadonlyArray<Json>;
177 readonly reply: Json;
178 }
179
180 /**
181 * Result of {@link AggregateStore.send}.
182 */
183 export type SendResult =
184 | { readonly _tag: "Rejected"; readonly rejection: Json }
185 | { readonly _tag: "Accepted"; readonly receipt: ReceiptJson };
186
187 /**
188 * The kernel for one aggregate type, handed to a platform.
189 */
190 export interface AggregateKit {
191 readonly name: string;
192 /**
193 * Decide, evolve, reply and route, purely. Throws only on a bug (an evolve
194 * guard, an undecodable value); a platform turns that into a defect.
195 */
196 readonly handle: (input: HandleInput) => Effect.Effect<HandleResult>;
197 /**
198 * Fold already-decided events into state and route them, without running
199 * `decide`. Used to seed history (story `given`).
200 */
201 readonly seed: (input: SeedInput) => Effect.Effect<SeedResult>;
202 /** Route a delivery produced by `handle` to its target's host. */
203 readonly deliver: (delivery: Delivery) => Effect.Effect<void>;
204 /** The views and projections that consume this aggregate, by `CatchUp.targetId`. */
205 readonly targets: ReadonlyArray<string>;
206 /** Whether each key of a consumer it feeds hears only from the instance with its own id. */
207 readonly consumerSingleSource: (target: string) => boolean;
208 /** Route stored events to the consumers lagging behind them (see `CatchUp`). */
209 readonly replay: (input: ReplayInput<StoredEvent>) => Effect.Effect<ReplayResult>;
210 /**
211 * What a subscriber of instance `id` receives, given its current state and
212 * the events committed since (at least those after the subscription's cursor).
213 */
214 readonly push: (
215 id: string,
216 subscription: Subscription,
217 current: { readonly state: Json; readonly version: number },
218 events: ReadonlyArray<StoredEvent>,
219 ) => Effect.Effect<Push>;
220 }
221
222 /**
223 * Input to {@link AggregateKit.seed}.
224 */
225 export interface SeedInput {
226 readonly id: string;
227 readonly state: Json;
228 readonly version: number;
229 readonly events: ReadonlyArray<Json>;
230 readonly commandId: string;
231 readonly now: number;
232 }
233
234 /**
235 * Result of {@link AggregateKit.seed}.
236 */
237 export interface SeedResult {
238 readonly state: Json;
239 readonly version: number;
240 readonly events: ReadonlyArray<StoredEvent>;
241 readonly deliveries: ReadonlyArray<Delivery>;
242 }
243
244 /**
245 * What a platform provides for an aggregate type.
246 */
247 export interface AggregateStore {
248 /**
249 * Handle a command on one instance: single writer per id; dedupe by
250 * `commandId`; persist events, state, receipt and deliveries atomically;
251 * then deliver at least once, in order.
252 */
253 readonly send: (id: string, command: Json, meta: Aggregate.SendMeta) => Effect.Effect<SendResult>;
254 /**
255 * Send a command to one instance when it is due, durably (it survives
256 * restarts) and at least once. Replaces a pending one with the same
257 * `commandId`. Rejections are impossible: only non-rejecting commands are
258 * scheduled. Returns when it is due, in epoch milliseconds on the
259 * platform's clock. Fails with `AlreadyExecuted` when the instance already
260 * has a receipt for `commandId`, so the command would never run.
261 */
262 readonly schedule: (
263 id: string,
264 command: Json,
265 meta: Aggregate.SendMeta,
266 due: Aggregate.Due,
267 ) => Effect.Effect<number, Aggregate.AlreadyExecuted>;
268 /**
269 * Cancel the pending scheduled command with this `commandId` on one
270 * instance, durably, and remember the cancel. Once this succeeds, the
271 * command never runs, even one already due. Fails with `AlreadyExecuted`
272 * when the instance has a receipt for `commandId`, `AlreadyCancelled` when
273 * it was cancelled before (and not scheduled again since), and
274 * `NotScheduled` when it was never scheduled.
275 */
276 readonly unschedule: (
277 id: string,
278 commandId: string,
279 ) => Effect.Effect<
280 void,
281 Aggregate.AlreadyExecuted | Aggregate.AlreadyCancelled | Aggregate.NotScheduled
282 >;
283 /** Read the stored state of an instance. */
284 readonly state: (id: string) => Effect.Effect<{ readonly state: Json; readonly version: number }>;
285 /** Read the committed events of an instance (tests and diagnostics; optional). */
286 readonly events?: (id: string) => Effect.Effect<ReadonlyArray<StoredEvent>>;
287 /** The stored state and version of an instance, then every new one. */
288 readonly changes: (
289 id: string,
290 ) => Stream.Stream<{ readonly state: Json; readonly version: number }>;
291 /** Committed events with `seq > after`, then live ones. */
292 readonly tail: (id: string, after: number) => Stream.Stream<StoredEvent>;
293 /**
294 * Append events without deciding. They reach views as history, and never
295 * trigger policies (tests; optional).
296 */
297 readonly seed?: (id: string, events: ReadonlyArray<Json>) => Effect.Effect<void>;
298 /**
299 * Accept a WebSocket upgrade (the current request) for a live read of
300 * `key`, then push to it on every commit. Optional: without it, live reads
301 * are streamed responses over `changes` and `tail`.
302 */
303 readonly connect?: (key: string, subscription: Subscription) => HttpEffect;
304 }
305
306 /** How much history has reached a consumer: see `View.History`. */
307 export interface HistoryJson {
308 readonly complete: boolean;
309 }
310
311 /**
312 * The stored state of one view key.
313 */
314 export interface ViewSnapshot {
315 /** The encoded state, or `null` when the key does not exist. */
316 readonly state: Json;
317 /** Number of applied deliveries. */
318 readonly version: number;
319 /** Last applied `seq` per source. */
320 readonly checkpoints: Readonly<Record<string, number>>;
321 /** Number of events the key has emitted. */
322 readonly seq: number;
323 /** The view's generation the key was built by: an earlier one is stale and starts over. */
324 readonly generation?: number;
325 }
326
327 /** The snapshot of a key that has never received a delivery. */
328 export const emptySnapshot: ViewSnapshot = { state: null, version: 0, checkpoints: {}, seq: 0 };
329
330 /**
331 * One event a view key emitted, with the key's state after it.
332 */
333 export interface ViewEntry {
334 readonly seq: number;
335 readonly event: Json;
336 readonly envelope: EnvelopeJson;
337 readonly state: Json;
338 }
339
340 /**
341 * The kernel for one view, handed to a platform.
342 */
343 export interface ViewKit {
344 readonly name: string;
345 /**
346 * Apply deliveries to a key's snapshot: evolve its state and emit events.
347 * Drops duplicates. Persist the snapshot and entries together, then send
348 * the downstream deliveries.
349 */
350 readonly apply: (
351 key: string,
352 snapshot: ViewSnapshot,
353 deliveries: ReadonlyArray<Delivery>,
354 ) => Effect.Effect<{
355 readonly snapshot: ViewSnapshot;
356 /** `false` when every delivery was a duplicate. */
357 readonly changed: boolean;
358 readonly entries: ReadonlyArray<ViewEntry>;
359 readonly downstream: ReadonlyArray<Delivery>;
360 }>;
361 /** Route a downstream delivery to its target's host. */
362 readonly deliver: (delivery: Delivery) => Effect.Effect<void>;
363 /** The views and projections that consume this view, by `CatchUp.targetId`. */
364 readonly targets: ReadonlyArray<string>;
365 /** Whether each key of a consumer it feeds hears only from the instance with its own id. */
366 readonly consumerSingleSource: (target: string) => boolean;
367 /**
368 * This view's generation. A stored key built by an earlier one is reset
369 * (state, entries, input log and cursors) before it is read or applied to.
370 */
371 readonly generation: number;
372 /** The generation of the view's storage: its generation, unless it is rebuilt in place. */
373 readonly classGeneration: number;
374 /** The view's id, by `CatchUp.targetId`, in this code. */
375 readonly target: string;
376 /**
377 * Set for a view keyed by the one aggregate it reads (`source`): before a key
378 * answers a read, it reads its history from the instance with its own id, so
379 * every answer covers the whole history even when no backfill filled it.
380 */
381 readonly catchUp?: { readonly source: string };
382 /** Whether each key hears only from the source instance with its own id (see `Kernel.singleSource`). */
383 readonly singleSource: boolean;
384 /**
385 * Route a source instance's stored rows (as its backfill `log` returns them)
386 * to one consumer (by `CatchUp.targetId`), as history: each row's seq and its
387 * deliveries. What a key keyed by its source runs on the rows it reads.
388 */
389 readonly history: (
390 target: string,
391 source: string,
392 id: string,
393 rows: ReadonlyArray<unknown>,
394 ) => Effect.Effect<
395 ReadonlyArray<{ readonly seq: number; readonly deliveries: ReadonlyArray<Delivery> }>
396 >;
397 /** Route emitted entries to the consumers lagging behind them (see `CatchUp`). */
398 readonly replay: (input: ReplayInput<ViewEntry>) => Effect.Effect<ReplayResult>;
399 /** Trace an `apply` of these deliveries to `key` (wrap the work that applies and persists them). */
400 readonly observe: (
401 key: string,
402 deliveries: ReadonlyArray<Delivery>,
403 ) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
404 /**
405 * What a subscriber of `key` receives, given its snapshot and the entries
406 * emitted since (at least those after the subscription's cursor).
407 */
408 readonly push: (
409 key: string,
410 subscription: Subscription,
411 snapshot: ViewSnapshot,
412 entries: ReadonlyArray<ViewEntry>,
413 ) => Effect.Effect<Push>;
414 }
415
416 /**
417 * What a platform provides for a view.
418 */
419 export interface ViewStore {
420 /** Apply deliveries to one key (single writer per key), then forward downstream deliveries. */
421 readonly receive: (key: string, deliveries: ReadonlyArray<Delivery>) => Effect.Effect<void>;
422 readonly read: (key: string) => Effect.Effect<ViewSnapshot>;
423 /** The current snapshot, then every new one. */
424 readonly changes: (key: string) => Stream.Stream<ViewSnapshot>;
425 /** Every entry of a key. */
426 readonly list: (key: string) => Effect.Effect<ReadonlyArray<ViewEntry>>;
427 /** Entries with `seq > after`, then live entries. */
428 readonly tail: (key: string, after: number) => Stream.Stream<ViewEntry>;
429 /**
430 * Accept a WebSocket upgrade (the current request) for a live read of
431 * `key`, then push to it on every commit. Optional: without it, live reads
432 * are streamed responses over `changes` and `tail`.
433 */
434 readonly connect?: (key: string, subscription: Subscription) => HttpEffect;
435 }
436
437 /**
438 * The kernel for one policy, handed to a platform.
439 */
440 export interface PolicyKit {
441 readonly name: string;
442 /** Run the policy's handler for one delivery. */
443 readonly run: (delivery: Delivery) => Effect.Effect<void>;
444 }
445
446 /**
447 * What a platform provides for a policy.
448 */
449 export interface PolicyStore {
450 /** Run deliveries at least once, in order per key. */
451 readonly receive: (delivery: Delivery) => Effect.Effect<void>;
452 }
453
454 /**
455 * One delivery a consumer's key accepted, in the key's immutable input log.
456 */
457 export interface Accepted {
458 /** The delivery's place in the key's input log, from 1. */
459 readonly position: number;
460 readonly delivery: Delivery;
461 /** Epoch milliseconds it was accepted. */
462 readonly at: number;
463 }
464
465 /**
466 * How a projection's Layer tunes it (variants, not part of its meaning).
467 */
468 export interface ProjectionOptions {
469 /** Hand the handler up to `size` accepted deliveries at once, waiting up to `wait` ms to fill. */
470 readonly batch?: { readonly size: number; readonly waitMillis: number };
471 }
472
473 /**
474 * The kernel for one projection, handed to a platform.
475 */
476 export interface ProjectionKit {
477 readonly name: string;
478 readonly options: ProjectionOptions;
479 /**
480 * This projection's generation. A key's log from an earlier one is reset;
481 * deliveries for an earlier one are dropped.
482 */
483 readonly generation: number;
484 /** Whether each key hears only from the source instance with its own id (see `Kernel.singleSource`). */
485 readonly singleSource: boolean;
486 /**
487 * Route a source instance's stored rows (as its backfill `log` returns them)
488 * to one consumer (by `CatchUp.targetId`), as history: each row's seq and its
489 * deliveries. What a key keyed by its source runs on the rows it reads.
490 */
491 readonly history: (
492 target: string,
493 source: string,
494 id: string,
495 rows: ReadonlyArray<unknown>,
496 ) => Effect.Effect<
497 ReadonlyArray<{ readonly seq: number; readonly deliveries: ReadonlyArray<Delivery> }>
498 >;
499 /**
500 * Run the handler for a run of one key's input log, in order. Succeeds only
501 * when every write the handler made succeeded; the platform then records
502 * the run as processed.
503 */
504 readonly run: (key: string, batch: ReadonlyArray<Accepted>) => Effect.Effect<void>;
505 }
506
507 /**
508 * What a platform provides for a projection.
509 */
510 export interface ProjectionStore {
511 /**
512 * Accept a delivery into its key's input log (dropping one already
513 * accepted, by source and `seq`), then process the log in order, in batches.
514 */
515 readonly receive: (delivery: Delivery) => Effect.Effect<void>;
516 /** The last processed `seq` per source stream, for one key. */
517 readonly checkpoints: (key: string) => Effect.Effect<Readonly<Record<string, number>>>;
518 }
519
520 /**
521 * One entry appended to a stream key.
522 */
523 export interface StreamEntry {
524 readonly seq: number;
525 readonly event: Json;
526 readonly envelope: EnvelopeJson;
527 }
528
529 /**
530 * The stored progress of one stream key.
531 */
532 export interface StreamMeta {
533 /** Number of entries. */
534 readonly seq: number;
535 /** The last source `seq` the writer has handled, per source stream. */
536 readonly checkpoints: Readonly<Record<string, number>>;
537 /** The last write applied: the writer's input-log position and its append index there. */
538 readonly origin: readonly [number, number];
539 }
540
541 /** The meta of a stream key nothing has written. */
542 export const emptyStreamMeta: StreamMeta = { seq: 0, checkpoints: {}, origin: [0, 0] };
543
544 /**
545 * One append to a stream key, made by its writer while handling an input.
546 */
547 export interface StreamWrite {
548 /** Where the write comes from: the writer's input-log position and the append's index there. */
549 readonly origin: readonly [number, number];
550 /** The source event being handled. */
551 readonly source: string;
552 readonly sourceSeq: number;
553 readonly at: number;
554 readonly commandId: string;
555 readonly events: ReadonlyArray<Json>;
556 }
557
558 /**
559 * The kernel for one stream, handed to a platform.
560 */
561 export interface StreamKit {
562 readonly name: string;
563 /**
564 * What a subscriber of `key` receives, given its meta and the entries
565 * appended since (at least those after the subscription's cursor).
566 */
567 readonly push: (
568 key: string,
569 subscription: Subscription,
570 meta: StreamMeta,
571 entries: ReadonlyArray<StreamEntry>,
572 latest: StreamEntry | undefined,
573 ) => Effect.Effect<Push>;
574 }
575
576 /**
577 * What a platform provides for a stream.
578 */
579 export interface StreamStore {
580 /**
581 * Append a write to one key (single writer per key). A write whose origin is
582 * not after the last applied one is a repeat and is dropped.
583 */
584 readonly append: (key: string, write: StreamWrite) => Effect.Effect<void>;
585 /** Record that the writer handled source events without appending. */
586 readonly advance: (
587 key: string,
588 checkpoints: Readonly<Record<string, number>>,
589 ) => Effect.Effect<void>;
590 readonly read: (key: string) => Effect.Effect<StreamMeta>;
591 /** The current meta, then every new one. */
592 readonly changes: (key: string) => Stream.Stream<StreamMeta>;
593 /** Every entry of a key. */
594 readonly list: (key: string) => Effect.Effect<ReadonlyArray<StreamEntry>>;
595 /** Entries with `seq > after`, then live entries. */
596 readonly tail: (key: string, after: number) => Stream.Stream<StreamEntry>;
597 /** Accept a WebSocket upgrade for a live read of `key` (optional, like views). */
598 readonly connect?: (key: string, subscription: Subscription) => HttpEffect;
599 }
600
601 /**
602 * Where one model is hosted. One factory per concept, each called once per
603 * entity while the model's Layer is built. A factory may declare any
604 * infrastructure (Durable Objects, buckets, queues) and returns the store the
605 * kernel talks to.
606 */
607 export interface ModelHost {
608 readonly aggregate: (
609 aggregate: Aggregate.Any,
610 kit: AggregateKit,
611 ) => Effect.Effect<AggregateStore>;
612 readonly view: (view: View.Any, kit: ViewKit) => Effect.Effect<ViewStore>;
613 readonly policy: (policy: Policy.Any, kit: PolicyKit) => Effect.Effect<PolicyStore>;
614 readonly projection: (
615 projection: Projection.Any,
616 kit: ProjectionKit,
617 ) => Effect.Effect<ProjectionStore>;
618 readonly stream: (stream: DomainStream.Any, kit: StreamKit) => Effect.Effect<StreamStore>;
619 /**
620 * Called once every store is built. A platform that keeps events across
621 * deploys starts catching up the views and projections in `targets` (every
622 * consumer in the model, by `CatchUp.targetId`) that are new to it.
623 */
624 readonly start?: (
625 targets: ReadonlyArray<string>,
626 /** What a backfill needs to know of each consumer: the sources it reads, and its keys' shape. */
627 planOf: (target: string) => Plan | undefined,
628 /**
629 * The consumers among `targets` the deploy backfills. The others fill each
630 * key themselves, from its own instance (see `ViewKit.catchUp`).
631 */
632 backfill: ReadonlyArray<string>,
633 ) => Effect.Effect<void>;
634 /**
635 * How much of the history recorded before a consumer (by
636 * `CatchUp.targetId`) has reached it. A platform without it keeps nothing
637 * across deploys, so there is no history to wait for.
638 */
639 readonly history?: (target: string) => Effect.Effect<HistoryJson>;
640 }
641
642 /** What a platform is told about a model it hosts. */
643 export interface HostedModel {
644 readonly modelName: string;
645 /** The same for every Layer of one model, and different for another model with the same name. */
646 readonly id: object;
647 /** The names of the model's sagas, which run on the workflow engine. */
648 readonly sagas: ReadonlyArray<string>;
649 /** Whether this model keeps data it shared with other models before Domain version 0: `legacyData` on its `layer`. */
650 readonly legacyData: boolean;
651 }
652
653 /**
654 * How a Domain is hosted. `model` is called once per model while its Layer is
655 * built, and gives that model storage of its own: two models that use the
656 * same aggregate, view or stream definition never share its data. Hosting
657 * two models with the same name on one platform fails.
658 *
659 * Swap the platform Layer to move a Domain between infrastructures: in-memory
660 * for tests and single processes, Durable Objects on Cloudflare, and so on.
661 */
662 export class Platform extends Context.Service<
663 Platform,
664 {
665 readonly model: (model: HostedModel) => Effect.Effect<ModelHost, never, Scope>;
666 }
667 >()("alchemy/Domain/Platform") {}
668
669 /**
670 * Track the models a platform hosts: `claim` fails while a different model
671 * with the same name is hosted, since both would address the same storage.
672 * The same model may be built again while an earlier build is open.
673 *
674 * @internal
675 */
676 export const hostedModels = ({
677 release,
678 }: {
679 /**
680 * Free a model's name when its build closes, so it can be built again as
681 * a redeploy. A platform whose builds outlive their scope, like a Worker's
682 * init, keeps every name for as long as it runs.
683 */
684 readonly release: boolean;
685 }) => {
686 const hosted = new Map<string, { readonly id: object; builds: number }>();
687 return (modelName: string, id: object): Effect.Effect<void, never, Scope> =>
688 Effect.acquireRelease(
689 Effect.suspend(() => {
690 const held = hosted.get(modelName);
691 if (held !== undefined && held.id !== id) {
692 return Effect.die(
693 new DefinitionError({ reason: new ModelHostedTwice({ model: modelName }) }),
694 );
695 }
696 if (held === undefined) hosted.set(modelName, { id, builds: 1 });
697 else held.builds++;
698 return Effect.void;
699 }),
700 // Built again after this build closes (a redeploy), the name is free.
701 () =>
702 Effect.sync(() => {
703 if (!release) return;
704 const held = hosted.get(modelName);
705 if (held !== undefined && --held.builds === 0) hosted.delete(modelName);
706 }),
707 );
708 };