@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
mdx 163 lines 7 KB
Raw
1 ---
2 title: Deadlines
3 description: Give a waiting process a time limit with a scheduled command, and let the aggregate decide whether the deadline or the action wins.
4 ---
5
6 import DAG from "../../../components/DAG.astro";
7
8 A saga that waits needs a deadline. A large transfer waits for a support agent's approval, and expires if nobody approves it within 24 hours. Schedule a command for the deadline, and let the aggregate decide whichever comes first.
9
10 ## Declare a command that reports the deadline
11
12 A scheduled command fires when nobody is waiting for its answer, so it never rejects. It reports a fact, and records nothing when the fact no longer applies.
13
14 ```typescript
15 // packages/domain/src/Transfer/ExpireTransfer.command.ts
16 import * as Domain from "@alchemy.run/domain";
17 import { TransferFailed } from "./FailTransfer.command.ts";
18 import { TransferId } from "./Transfer.id.ts";
19
20 /**
21 * The approval window closed. Scheduled by `TransferApprovalDeadline`; it
22 * reports a fact, so it never rejects, and it records nothing if the transfer
23 * was approved in time.
24 */
25 export class ExpireTransfer extends Domain.Command("ExpireTransfer", {
26 target: TransferId,
27 events: [TransferFailed],
28 }) {}
29 ```
30
31 ## Schedule it
32
33 A policy schedules the command when the waiting starts.
34
35 ```typescript
36 // packages/domain/src/Transfer/TransferApprovalDeadline.policy.ts
37 import * as Domain from "@alchemy.run/domain";
38 import * as Effect from "effect/Effect";
39 import { ExpireTransfer } from "./ExpireTransfer.command.ts";
40 import { TransferRequested } from "./RequestTransfer.command.ts";
41 import { Transfer } from "./Transfer.aggregate.ts";
42
43 /** How long a support agent has to approve a large transfer. */
44 export const APPROVAL_WINDOW = "24 hours";
45
46 /**
47 * Whenever a transfer needs approval, expire it if nobody approves it in time.
48 * The Transfer decides the race: approval and expiry are commands on the same
49 * instance, so exactly one of them wins.
50 */
51 export class TransferApprovalDeadline extends Domain.Policy("TransferApprovalDeadline", {
52 from: Transfer,
53 on: [TransferRequested],
54 }) {}
55
56 export const TransferApprovalDeadlineLive = TransferApprovalDeadline.toLayer(
57 Effect.gen(function* () {
58 const transfers = yield* Transfer;
59 return Effect.fn(function* ({ source, event }) {
60 if (!event.needsApproval) return;
61 yield* transfers.schedule(source, new ExpireTransfer(), { after: APPROVAL_WINDOW }).pipe(
62 // A redelivery after the window closed: the expiry already ran.
63 Effect.catchTag("AlreadyExecuted", () => Effect.void),
64 );
65 });
66 }),
67 );
68 ```
69
70 The schedule is durable: it fires even if everything restarted in between. Scheduling again with the same command id replaces the earlier one.
71
72 A scheduled command takes its command id like any other command, so it runs once. Scheduling an id the transfer already handled fails with `AlreadyExecuted`, because that command would never run again. Here it means the policy ran a second time for the same event, after the expiry fired, so there's nothing to do.
73
74 ## Let the aggregate decide the race
75
76 Approval and expiry are both commands to the same transfer. One may come from a support agent at any moment, the other from the schedule after 24 hours.
77
78 <DAG
79 nodes={[
80 { id: "agent", label: "Support agent", type: "approves", kind: "client", col: 0, row: 0 },
81 { id: "schedule", label: "Schedule", type: "set by the policy", col: 0, row: 2 },
82 { id: "approve", label: "ApproveTransfer", type: "any time", kind: "command", col: 1, row: 0 },
83 { id: "expire", label: "ExpireTransfer", type: "after 24 hours", kind: "command", col: 1, row: 2 },
84 { id: "transfer", label: "Transfer", type: "one at a time", kind: "aggregate", col: 2, row: 1 },
85 ]}
86 edges={[
87 { from: "agent", to: "approve" },
88 { from: "schedule", to: "expire", dashed: true },
89 { from: "approve", to: "transfer" },
90 { from: "expire", to: "transfer" },
91 ]}
92 caption="Both commands reach the same transfer, which handles one at a time."
93 />
94
95 The transfer handles one command at a time, so whichever arrives first changes its state, and its `decide` turns the other away. Approval is only accepted while the transfer is awaiting approval:
96
97 ```typescript title="packages/domain/src/Transfer/Transfer.aggregate.ts"
98 ApproveTransfer: Effect.fn(function* (s, _, { id }) {
99 const approvedBy = yield* CurrentActor;
100 if (approvedBy._tag !== "Agent") return yield* new NotPermitted();
101 if (s._tag !== "AwaitingApproval") return yield* new NotAwaitingApproval();
102 ```
103
104 Expiry fails the transfer only if it's still waiting, and records nothing otherwise:
105
106 ```typescript title="packages/domain/src/Transfer/Transfer.aggregate.ts"
107 ExpireTransfer: (s, _, { id }) =>
108 s._tag === "AwaitingApproval"
109 ? [new TransferFailed({ transferId: id, reason: "not approved in time" })]
110 : [],
111 ```
112
113 So an approved transfer ignores its expiry, and an expired transfer rejects a late approval with `NotAwaitingApproval`.
114
115 ## Cancel it
116
117 When the deadline no longer applies, cancel it. Schedule the command with a command id you can name again, and unschedule it by that id:
118
119 ```typescript
120 // when the waiting starts
121 yield* transfers.schedule(source, new ExpireTransfer(), {
122 after: APPROVAL_WINDOW,
123 commandId: `expire:${source.id}`,
124 });
125
126 // when the transfer is approved
127 yield* transfers.unschedule(source, `expire:${source.id}`);
128 ```
129
130 `schedule` returns a `ScheduleReceipt` with the command id and when the command is due (`at`), so code that schedules without its own id can still cancel by `receipt.commandId`.
131
132 Unscheduling is durable, like scheduling. Once it succeeds, the command never fires, even when a story's clock passes its time. When there was nothing to cancel, it fails and says why: `AlreadyExecuted` when the command already ran, `AlreadyCancelled` when it was cancelled before, and `NotScheduled` when nothing was scheduled with that id.
133
134 A policy cancels after the approval is recorded, so the expiry can still arrive in between. Keep the guard in `decide` for that case. A policy can also run again for the same event, and then finds the expiry already cancelled:
135
136 ```typescript
137 yield* transfers.unschedule(source, `expire:${source.id}`).pipe(
138 Effect.catchTag(["AlreadyExecuted", "AlreadyCancelled"], () => Effect.void),
139 );
140 ```
141
142 ## Test it with the clock
143
144 A story has its own clock. `Story.clock` moves it, and any scheduled command that's now due fires.
145
146 ```typescript title="packages/domain/test/deadlines.test.ts"
147 // A minute before the deadline, nothing has happened.
148 Story.clock("2026-01-02T08:59:00Z"),
149 Story.then(transfer),
150 // At the deadline, the transfer expires.
151 Story.clock("2026-01-02T09:00:00Z"),
152 Story.then(transfer, new TransferFailed({ transferId: transfer.id, reason: "not approved in time" })),
153 // Approval now comes too late.
154 Story.provide(CurrentActor, agent("support-7")),
155 Story.when(transfer, new ApproveTransfer()),
156 Story.rejected(new NotAwaitingApproval()),
157 ```
158
159 `Story.then(transfer)` with no events checks that nothing new was recorded.
160
161 :::note
162 Scheduling is covered in [Command](/domain/command#send-it-later). A [saga](/domain/saga) waits for the decision.
163 :::