The best way to control Claude Code, Codex and more from any computer or phone
| 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 | }; |