The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import * as Domain from "@alchemy.run/domain"; |
| 2 | import { Story } from "@alchemy.run/domain/Story"; |
| 3 | import { describe, expect, it } from "@alchemy.run/test"; |
| 4 | import * as Effect from "effect/Effect"; |
| 5 | import * as Fiber from "effect/Fiber"; |
| 6 | import * as FetchHttpClient from "effect/http/FetchHttpClient"; |
| 7 | import * as Layer from "effect/Layer"; |
| 8 | import * as Metric from "effect/Metric"; |
| 9 | import * as Option from "effect/Option"; |
| 10 | import * as Redacted from "effect/Redacted"; |
| 11 | import * as Schema from "effect/Schema"; |
| 12 | import * as Socket from "effect/socket/Socket"; |
| 13 | import * as Stream from "effect/Stream"; |
| 14 | import * as Tracer from "effect/Tracer"; |
| 15 | import { Activity } from "effect/workflow"; |
| 16 | |
| 17 | // A wallet whose debits a policy audits on a second aggregate, and reminds later. |
| 18 | class Opened extends Domain.Event("Opened", { balance: Schema.Number }) {} |
| 19 | class Debited extends Domain.Event( |
| 20 | "Debited", |
| 21 | { amount: Schema.Number, note: Schema.Redacted(Schema.String) }, |
| 22 | { attributes: (e) => ({ "wallet.amount": e.amount, "wallet.note": e.note }) }, |
| 23 | ) {} |
| 24 | class Insufficient extends Domain.Rejection( |
| 25 | "Insufficient", |
| 26 | { balance: Schema.Number }, |
| 27 | { attributes: (r) => ({ "wallet.balance": r.balance }) }, |
| 28 | ) {} |
| 29 | |
| 30 | class Open extends Domain.Command("Open", { |
| 31 | target: Schema.String, |
| 32 | input: { balance: Schema.Number }, |
| 33 | events: [Opened], |
| 34 | }) {} |
| 35 | class Debit extends Domain.Command("Debit", { |
| 36 | target: Schema.String, |
| 37 | input: { amount: Schema.Number, note: Schema.Redacted(Schema.String) }, |
| 38 | events: [Debited], |
| 39 | rejects: [Insufficient], |
| 40 | attributes: (cmd) => ({ "wallet.amount": cmd.amount }), |
| 41 | }) {} |
| 42 | |
| 43 | class Wallet extends Domain.Aggregate("Wallet", { |
| 44 | id: Schema.String, |
| 45 | state: Schema.Struct({ balance: Schema.Number }), |
| 46 | initial: { balance: 0 }, |
| 47 | commands: [Open, Debit], |
| 48 | decide: { |
| 49 | Open: (_, cmd) => [new Opened({ balance: cmd.balance })], |
| 50 | Debit: Effect.fn(function* (s, cmd) { |
| 51 | yield* Effect.annotateCurrentSpan("wallet.checked", true); |
| 52 | return s.balance < cmd.amount |
| 53 | ? yield* new Insufficient({ balance: s.balance }) |
| 54 | : [new Debited({ amount: cmd.amount, note: cmd.note })]; |
| 55 | }), |
| 56 | }, |
| 57 | evolve: { |
| 58 | Opened: (_, e) => ({ balance: e.balance }), |
| 59 | Debited: (s, e) => ({ balance: s.balance - e.amount }), |
| 60 | }, |
| 61 | }) {} |
| 62 | |
| 63 | class Audited extends Domain.Event("Audited", { wallet: Schema.String }) {} |
| 64 | class Reminded extends Domain.Event("Reminded") {} |
| 65 | class Audit extends Domain.Command("Audit", { |
| 66 | target: Schema.String, |
| 67 | input: { wallet: Schema.String }, |
| 68 | events: [Audited], |
| 69 | }) {} |
| 70 | class Remind extends Domain.Command("Remind", { target: Schema.String, events: [Reminded] }) {} |
| 71 | class Ledger extends Domain.Aggregate("Ledger", { |
| 72 | id: Schema.String, |
| 73 | state: Schema.Struct({ audits: Schema.Number }), |
| 74 | initial: { audits: 0 }, |
| 75 | commands: [Audit, Remind], |
| 76 | decide: { |
| 77 | Audit: (_, cmd) => [new Audited({ wallet: cmd.wallet })], |
| 78 | Remind: () => [new Reminded()], |
| 79 | }, |
| 80 | evolve: { |
| 81 | Audited: (s) => ({ audits: s.audits + 1 }), |
| 82 | Reminded: (s) => s, |
| 83 | }, |
| 84 | }) {} |
| 85 | |
| 86 | class AuditDebits extends Domain.Policy("AuditDebits", { from: Wallet, on: [Debited] }) {} |
| 87 | const AuditDebitsLive = AuditDebits.toLayer( |
| 88 | Effect.gen(function* () { |
| 89 | const ledgers = yield* Ledger; |
| 90 | return Effect.fn(function* ({ source }) { |
| 91 | yield* ledgers.send("main", new Audit({ wallet: source.id })); |
| 92 | yield* ledgers |
| 93 | .schedule("main", new Remind(), { after: "1 hour" }) |
| 94 | .pipe(Effect.catchTag("AlreadyExecuted", () => Effect.void)); |
| 95 | }); |
| 96 | }), |
| 97 | ); |
| 98 | |
| 99 | class Balance extends Domain.View("Balance", { |
| 100 | from: [Wallet], |
| 101 | key: Wallet, |
| 102 | state: Schema.Struct({ balance: Schema.Number }), |
| 103 | initial: { balance: 0 }, |
| 104 | evolve: { |
| 105 | Opened: (_, e) => ({ balance: e.balance }), |
| 106 | Debited: (v, e) => ({ balance: v.balance - e.amount }), |
| 107 | }, |
| 108 | }) {} |
| 109 | |
| 110 | // The model a browser client reads the balance from. |
| 111 | class Balances extends Domain.Model("TelemetryBalances", { |
| 112 | aggregates: [Wallet], |
| 113 | views: [Balance], |
| 114 | }) {} |
| 115 | class WalletApi extends Domain.Api("WalletApi", { model: Balances, views: ["Balance"] }) {} |
| 116 | |
| 117 | class Bank extends Domain.Model("TelemetryBank", { |
| 118 | aggregates: [Wallet, Ledger], |
| 119 | policies: [AuditDebits], |
| 120 | }) {} |
| 121 | |
| 122 | // A second model: a policy that checks an external system and starts a saga, |
| 123 | // and a projection over the wallet's events. |
| 124 | class Scorer extends Domain.ExternalSystem("Scorer", { |
| 125 | score: { args: { wallet: Schema.String }, success: { risk: Schema.Number } }, |
| 126 | }) {} |
| 127 | |
| 128 | class Review extends Domain.Saga("Review", { key: Schema.String, input: {} }) {} |
| 129 | const ReviewLive = Review.toLayer( |
| 130 | Effect.gen(function* () { |
| 131 | const ledgers = yield* Ledger; |
| 132 | return Effect.fn(function* ({ key }) { |
| 133 | yield* Activity.make({ |
| 134 | name: "audit", |
| 135 | execute: ledgers.send("main", new Audit({ wallet: key })).pipe(Effect.orDie), |
| 136 | }); |
| 137 | }); |
| 138 | }), |
| 139 | ); |
| 140 | |
| 141 | class ReviewDebits extends Domain.Policy("ReviewDebits", { from: Wallet, on: [Debited] }) {} |
| 142 | const ReviewDebitsLive = ReviewDebits.toLayer( |
| 143 | Effect.gen(function* () { |
| 144 | const scorer = yield* Scorer; |
| 145 | const reviews = yield* Review; |
| 146 | return Effect.fn(function* ({ source }) { |
| 147 | const { risk } = yield* scorer.score({ wallet: source.id }); |
| 148 | if (risk > 0.5) yield* reviews.start(source, {}); |
| 149 | }); |
| 150 | }), |
| 151 | ); |
| 152 | |
| 153 | class Movements extends Domain.Projection("Movements", { |
| 154 | from: [Wallet], |
| 155 | key: Wallet, |
| 156 | on: [Debited], |
| 157 | }) {} |
| 158 | const MovementsLive = Movements.toLayer(Effect.succeed(() => Effect.void)); |
| 159 | |
| 160 | class Reviewed extends Domain.Model("TelemetryReviews", { |
| 161 | aggregates: [Wallet, Ledger], |
| 162 | policies: [ReviewDebits], |
| 163 | projections: [Movements], |
| 164 | sagas: [Review], |
| 165 | }) {} |
| 166 | |
| 167 | const reviewStory = Story.make(Reviewed, { |
| 168 | layer: Layer.mergeAll(ReviewDebitsLive, ReviewLive, MovementsLive), |
| 169 | stub: [Scorer], |
| 170 | }); |
| 171 | |
| 172 | const story = Story.make(Bank, { layer: Layer.mergeAll(AuditDebitsLive) }); |
| 173 | const alice = Wallet.ref("alice"); |
| 174 | const ledger = Ledger.ref("main"); |
| 175 | |
| 176 | /** A tracer that keeps every span it starts. */ |
| 177 | const recording = () => { |
| 178 | const spans: Array<Tracer.NativeSpan> = []; |
| 179 | const tracer = Tracer.make({ |
| 180 | span: (options) => { |
| 181 | const span = new Tracer.NativeSpan(options); |
| 182 | spans.push(span); |
| 183 | return span; |
| 184 | }, |
| 185 | }); |
| 186 | const named = (name: string) => spans.filter((span) => span.name === name); |
| 187 | const one = (name: string) => { |
| 188 | const found = named(name); |
| 189 | expect(found.map((s) => s.name)).toEqual([name]); |
| 190 | return found[0]!; |
| 191 | }; |
| 192 | return { spans, tracer, named, one }; |
| 193 | }; |
| 194 | |
| 195 | const parentId = (span: Tracer.Span) => Option.getOrUndefined(span.parent)?.spanId; |
| 196 | |
| 197 | describe("Domain telemetry", { tags: ["unit", "local"] }, () => { |
| 198 | it.effect("a command's whole flow is one trace, with one correlation id", () => |
| 199 | Effect.gen(function* () { |
| 200 | const { tracer, one, spans } = recording(); |
| 201 | yield* story( |
| 202 | Story.given(alice, new Opened({ balance: 100 })), |
| 203 | Story.when(alice, new Debit({ amount: 40, note: Redacted.make("rent") })), |
| 204 | Story.then(alice, new Debited({ amount: 40, note: Redacted.make("rent") })), |
| 205 | Story.then(ledger, new Audited({ wallet: "alice" })), |
| 206 | ).pipe(Effect.withTracer(tracer)); |
| 207 | |
| 208 | const debit = one("Domain.decide Wallet.Debit"); |
| 209 | const policy = one("Domain.policy AuditDebits"); |
| 210 | const audit = one("Domain.decide Ledger.Audit"); |
| 211 | const auditSend = one("Domain.send Ledger.Audit"); |
| 212 | |
| 213 | // The policy continues the debit's trace, and the command it sends continues the policy's. |
| 214 | expect(policy.traceId).toBe(debit.traceId); |
| 215 | expect(parentId(policy)).toBe(debit.spanId); |
| 216 | expect(parentId(auditSend)).toBe(policy.spanId); |
| 217 | expect(parentId(audit)).toBe(auditSend.spanId); |
| 218 | expect(audit.traceId).toBe(debit.traceId); |
| 219 | |
| 220 | // One correlation id, the debit's command id, end to end. |
| 221 | const correlation = debit.attributes.get("domain.correlation_id"); |
| 222 | expect(correlation).toBe(debit.attributes.get("domain.command_id")); |
| 223 | for (const span of [policy, auditSend, audit]) { |
| 224 | expect(span.attributes.get("domain.correlation_id")).toBe(correlation); |
| 225 | } |
| 226 | expect(spans.every((s) => s.status._tag === "Ended")).toBe(true); |
| 227 | }), |
| 228 | ); |
| 229 | |
| 230 | it.effect("records only the attributes a declaration returns, and never a Redacted value", () => |
| 231 | Effect.gen(function* () { |
| 232 | const { tracer, one } = recording(); |
| 233 | yield* story( |
| 234 | Story.given(alice, new Opened({ balance: 100 })), |
| 235 | Story.when(alice, new Debit({ amount: 40, note: Redacted.make("rent") })), |
| 236 | Story.then(alice, new Debited({ amount: 40, note: Redacted.make("rent") })), |
| 237 | Story.then(ledger, new Audited({ wallet: "alice" })), |
| 238 | ).pipe(Effect.withTracer(tracer)); |
| 239 | |
| 240 | const debit = one("Domain.decide Wallet.Debit"); |
| 241 | expect(debit.attributes.get("wallet.amount")).toBe(40); |
| 242 | expect(debit.attributes.get("wallet.checked")).toBe(true); // annotated inside decide |
| 243 | expect(debit.attributes.get("domain.outcome")).toBe("accepted"); |
| 244 | // The event's own attributes ride on its span event; its note is Redacted. |
| 245 | const [name, , attributes] = debit.events[0]!; |
| 246 | expect(name).toBe("Debited"); |
| 247 | expect(attributes).toMatchObject({ "wallet.amount": 40, "wallet.note": "<redacted>" }); |
| 248 | |
| 249 | // Nothing from a payload is recorded unless a declaration asks for it. |
| 250 | const audit = one("Domain.decide Ledger.Audit"); |
| 251 | const keys = [...audit.attributes.keys()]; |
| 252 | expect(keys.every((key) => key.startsWith("domain."))).toBe(true); |
| 253 | const values = [ |
| 254 | ...debit.attributes.values(), |
| 255 | ...debit.events.flatMap(([, , a]) => Object.values(a)), |
| 256 | ]; |
| 257 | expect(values).not.toContain("rent"); |
| 258 | }), |
| 259 | ); |
| 260 | |
| 261 | it.effect("a rejection is an outcome, not an error", () => |
| 262 | Effect.gen(function* () { |
| 263 | const { tracer, one } = recording(); |
| 264 | yield* story( |
| 265 | Story.given(alice, new Opened({ balance: 10 })), |
| 266 | Story.when(alice, new Debit({ amount: 40, note: Redacted.make("rent") })), |
| 267 | Story.rejected(new Insufficient({ balance: 10 })), |
| 268 | ).pipe(Effect.withTracer(tracer)); |
| 269 | |
| 270 | const debit = one("Domain.decide Wallet.Debit"); |
| 271 | expect(debit.attributes.get("domain.outcome")).toBe("Insufficient"); |
| 272 | expect(debit.attributes.get("wallet.balance")).toBe(10); |
| 273 | expect(debit.status._tag === "Ended" && debit.status.exit._tag).toBe("Success"); |
| 274 | const send = one("Domain.send Wallet.Debit"); |
| 275 | expect(send.attributes.get("domain.outcome")).toBe("Insufficient"); |
| 276 | expect(send.status._tag === "Ended" && send.status.exit._tag).toBe("Success"); |
| 277 | }), |
| 278 | ); |
| 279 | |
| 280 | it.effect("a scheduled command links to its cause instead of continuing its trace", () => |
| 281 | Effect.gen(function* () { |
| 282 | const { tracer, one } = recording(); |
| 283 | yield* story( |
| 284 | Story.clock("2026-01-01T00:00:00Z"), |
| 285 | Story.given(alice, new Opened({ balance: 100 })), |
| 286 | Story.when(alice, new Debit({ amount: 40, note: Redacted.make("rent") })), |
| 287 | Story.then(alice, new Debited({ amount: 40, note: Redacted.make("rent") })), |
| 288 | Story.then(ledger, new Audited({ wallet: "alice" })), |
| 289 | Story.clock("2026-01-01T01:00:00Z"), |
| 290 | Story.then(ledger, new Reminded()), |
| 291 | ).pipe(Effect.withTracer(tracer)); |
| 292 | |
| 293 | const scheduled = one("Domain.schedule Ledger.Remind"); |
| 294 | const remind = one("Domain.decide Ledger.Remind"); |
| 295 | expect(parentId(remind)).not.toBe(scheduled.spanId); |
| 296 | expect(remind.links.map((l) => l.span.spanId)).toEqual([scheduled.spanId]); |
| 297 | // Still the same flow. |
| 298 | expect(remind.attributes.get("domain.correlation_id")).toBe( |
| 299 | one("Domain.decide Wallet.Debit").attributes.get("domain.correlation_id"), |
| 300 | ); |
| 301 | }), |
| 302 | ); |
| 303 | |
| 304 | it.effect("a saga run starts its own trace, linked to the policy that started it", () => |
| 305 | Effect.gen(function* () { |
| 306 | const { tracer, one, named } = recording(); |
| 307 | yield* reviewStory( |
| 308 | Story.given(alice, new Opened({ balance: 100 })), |
| 309 | Story.when(alice, new Debit({ amount: 40, note: Redacted.make("rent") })), |
| 310 | Story.then(alice, new Debited({ amount: 40, note: Redacted.make("rent") })), |
| 311 | Story.call(Scorer.score, { wallet: "alice" }), |
| 312 | Story.succeed(Scorer.score, { risk: 0.9 }), |
| 313 | Story.then(ledger, new Audited({ wallet: "alice" })), |
| 314 | Story.saga(Review, "alice", { _tag: "Completed", result: undefined }), |
| 315 | ).pipe(Effect.withTracer(tracer)); |
| 316 | |
| 317 | const debit = one("Domain.decide Wallet.Debit"); |
| 318 | const policy = one("Domain.policy ReviewDebits"); |
| 319 | // The external call is part of the policy's run. |
| 320 | expect(parentId(one("Domain.external Scorer.score"))).toBe(policy.spanId); |
| 321 | |
| 322 | // Every replay of the run is its own trace, linked to the policy that started it. |
| 323 | const runs = named("Domain.saga Review"); |
| 324 | expect(runs.length).toBeGreaterThan(0); |
| 325 | for (const run of runs) { |
| 326 | expect(run.traceId).not.toBe(debit.traceId); |
| 327 | expect(run.links.map((l) => l.span.spanId)).toEqual([policy.spanId]); |
| 328 | expect(run.attributes.get("domain.correlation_id")).toBe( |
| 329 | debit.attributes.get("domain.correlation_id"), |
| 330 | ); |
| 331 | } |
| 332 | // The command its step sends keeps the flow's correlation id. |
| 333 | expect(one("Domain.decide Ledger.Audit").attributes.get("domain.correlation_id")).toBe( |
| 334 | debit.attributes.get("domain.correlation_id"), |
| 335 | ); |
| 336 | }), |
| 337 | ); |
| 338 | |
| 339 | it.effect("a projection batch links to the commits it handles", () => |
| 340 | Effect.gen(function* () { |
| 341 | const { tracer, one } = recording(); |
| 342 | yield* reviewStory( |
| 343 | Story.given(alice, new Opened({ balance: 100 })), |
| 344 | Story.when(alice, new Debit({ amount: 40, note: Redacted.make("rent") })), |
| 345 | Story.then(alice, new Debited({ amount: 40, note: Redacted.make("rent") })), |
| 346 | Story.call(Scorer.score, { wallet: "alice" }), |
| 347 | Story.succeed(Scorer.score, { risk: 0.1 }), |
| 348 | ).pipe(Effect.withTracer(tracer)); |
| 349 | |
| 350 | const debit = one("Domain.decide Wallet.Debit"); |
| 351 | const batch = one("Domain.projection Movements"); |
| 352 | expect(batch.traceId).not.toBe(debit.traceId); |
| 353 | expect(batch.links.map((l) => l.span.spanId)).toEqual([debit.spanId]); |
| 354 | expect(batch.attributes.get("domain.batch")).toBe(1); |
| 355 | }), |
| 356 | ); |
| 357 | |
| 358 | it.effect("a live read carries the caller's span, so the server joins its trace", () => |
| 359 | Effect.gen(function* () { |
| 360 | const { tracer } = recording(); |
| 361 | const urls: Array<string> = []; |
| 362 | // A socket that never opens: enough to see what the client asked for. |
| 363 | const sockets = Layer.succeed(Socket.WebSocketConstructor, (url) => { |
| 364 | urls.push(url); |
| 365 | return { |
| 366 | addEventListener: () => {}, |
| 367 | removeEventListener: () => {}, |
| 368 | close: () => {}, |
| 369 | readyState: 0, |
| 370 | } as never; |
| 371 | }); |
| 372 | const watched = yield* Effect.gen(function* () { |
| 373 | const client = yield* WalletApi.client; |
| 374 | const fiber = yield* client.Balance.watch("alice").pipe(Stream.runDrain, Effect.forkChild); |
| 375 | for (let i = 0; i < 100 && urls.length === 0; i++) yield* Effect.yieldNow; |
| 376 | const span = yield* Effect.currentSpan; |
| 377 | yield* Fiber.interrupt(fiber); |
| 378 | return span; |
| 379 | }).pipe( |
| 380 | Effect.withSpan("click"), |
| 381 | Effect.scoped, |
| 382 | Effect.provide( |
| 383 | Domain.protocolWebSocket("http://bank.test/api").pipe( |
| 384 | Layer.provide(Layer.mergeAll(FetchHttpClient.layer, sockets)), |
| 385 | ), |
| 386 | ), |
| 387 | Effect.withTracer(tracer), |
| 388 | ); |
| 389 | expect(urls).toHaveLength(1); |
| 390 | const read = JSON.parse(new URL(urls[0]!).searchParams.get("read")!); |
| 391 | expect(read.tag).toBe("Balance.watch"); |
| 392 | // The RPC client's span for the read, a child of the caller's. |
| 393 | expect(read.traceId).toBe(watched.traceId); |
| 394 | expect(typeof read.spanId).toBe("string"); |
| 395 | }), |
| 396 | ); |
| 397 | |
| 398 | it.effect("counts commands by outcome", () => |
| 399 | Effect.gen(function* () { |
| 400 | const rejected = Metric.withAttributes(Domain.Telemetry.commands, { |
| 401 | "domain.aggregate": "Wallet", |
| 402 | "domain.command": "Debit", |
| 403 | "domain.outcome": "Insufficient", |
| 404 | }); |
| 405 | const before = (yield* Metric.value(rejected)).count; |
| 406 | yield* story( |
| 407 | Story.given(alice, new Opened({ balance: 10 })), |
| 408 | Story.when(alice, new Debit({ amount: 40, note: Redacted.make("rent") })), |
| 409 | Story.rejected(new Insufficient({ balance: 10 })), |
| 410 | ); |
| 411 | expect((yield* Metric.value(rejected)).count).toBe(before + 1); |
| 412 | }), |
| 413 | ); |
| 414 | }); |