@camstack/types 1.2.549 → 1.2.551

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 (33) hide show
  1. package/CHANGELOG.md +28 -0
  2. package/dist/addon/addon-instance.d.ts +23 -0
  3. package/dist/addon/build-addon-route-provider.d.ts +2 -0
  4. package/dist/addon.js +1 -1
  5. package/dist/addon.mjs +1 -1
  6. package/dist/automation/fired-trigger.d.ts +44 -0
  7. package/dist/automation/index.d.ts +8 -5
  8. package/dist/automation/recipe.d.ts +12105 -604
  9. package/dist/automation/scheduler.d.ts +7 -0
  10. package/dist/automation/step-runner.d.ts +70 -0
  11. package/dist/automation/trace.d.ts +254 -145
  12. package/dist/automation/wait-until.d.ts +32 -0
  13. package/dist/automation/when-site.d.ts +1 -1
  14. package/dist/automation/when.d.ts +39 -1
  15. package/dist/capabilities/actions.cap.d.ts +1 -178
  16. package/dist/capabilities/addon-routes.cap.d.ts +3 -0
  17. package/dist/capabilities/core-blocks.cap.d.ts +117 -8723
  18. package/dist/capabilities/event-emitter.cap.d.ts +99 -3
  19. package/dist/capabilities/event-vocabulary.d.ts +99 -0
  20. package/dist/capabilities/index.d.ts +1 -0
  21. package/dist/capabilities/oauth-integration.cap.d.ts +8 -0
  22. package/dist/capabilities/schedulers.cap.d.ts +1 -178
  23. package/dist/capabilities/sso-bridge.cap.d.ts +3 -0
  24. package/dist/capabilities/user-management.cap.d.ts +4 -0
  25. package/dist/generated/addon-cap-facts.d.ts +1 -1
  26. package/dist/index.d.ts +4 -2
  27. package/dist/index.js +1488 -156
  28. package/dist/index.mjs +1442 -157
  29. package/dist/interfaces/addon-routes.d.ts +13 -0
  30. package/dist/interfaces/config-ui.d.ts +15 -24
  31. package/dist/{sleep-Bn346wCJ.mjs → sleep-D0roI_CZ.mjs} +4 -0
  32. package/dist/{sleep-LFKpQ2_f.js → sleep-dcR4vBFG.js} +4 -0
  33. package/package.json +1 -1
@@ -93,6 +93,13 @@ export declare const DEFAULT_MAX_HOLD_ATTEMPTS = 3;
93
93
  export declare const MAX_HOLD_ATTEMPTS_LIMIT = 20;
94
94
  /** A missed edge up to this late still runs. */
95
95
  export declare const DEFAULT_MAX_LATE_MS: number;
96
+ /**
97
+ * The longest one `wait` of a scheduler point lasts. A point's steps run in
98
+ * the scheduler's one serial queue, with no run ceiling: a wait holds every
99
+ * other scheduler's points for as long as it lasts. An action (one hour) has
100
+ * its own run and ceiling; a point keeps the five minutes it always had.
101
+ */
102
+ export declare const SCHEDULER_WAIT_MAX_SECONDS = 300;
96
103
  export declare const SchedulerPointSchema: z.ZodObject<{
97
104
  id: z.ZodString;
98
105
  at: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -7,6 +7,11 @@
7
7
  * sequence STOPS at the first failure (continuing past a failed step executes
8
8
  * an intent the operator never expressed), and every step is traced — the ones
9
9
  * after a failure, or after an abort, are `not-run` with the reason.
10
+ *
11
+ * Flow control (#500) is the operator EXPRESSING that intent: a step marked
12
+ * `continueOnError` is traced `failed-continued` and the sequence goes on; a
13
+ * `stop` step ends the run on purpose, as a success or as a failure, and the
14
+ * steps after it are `not-run` with its reason.
10
15
  */
11
16
  import type { CommandOriginClaim } from '../audit/device-transition.js';
12
17
  import type { DeviceTemplateRender } from '../expression/device-template.js';
@@ -34,6 +39,19 @@ export interface StepScope {
34
39
  setArgs(args: Readonly<Record<string, unknown>>): void;
35
40
  /** The device values the step's templates printed as `—`, with the reason (D1021). */
36
41
  setTemplateNotes(notes: readonly string[]): void;
42
+ /** End the run here, on purpose (#500): the later steps are `not-run` with this reason. */
43
+ stop(reason: string, outcome: StepStopOutcome): void;
44
+ /** The step waited for something that did not come and the run goes on (#500): traced `timed-out`. */
45
+ markTimedOut(reason: string): void;
46
+ }
47
+ /** How a `stop` step ends the run: as a success, or as a failure. */
48
+ export type StepStopOutcome = 'ok' | 'failed';
49
+ /** The `stop` that ended a run. */
50
+ export interface StepStop {
51
+ readonly reason: string;
52
+ readonly outcome: StepStopOutcome;
53
+ /** The step that stopped it. */
54
+ readonly path: string;
37
55
  }
38
56
  /** One step as the runner sees it: its meta and a closure that does the work. */
39
57
  export interface RunnableStep {
@@ -43,6 +61,46 @@ export interface RunnableStep {
43
61
  readonly guard?: () => Promise<StepConditionVerdict>;
44
62
  /** Run when the guard reads `false`; never when it reads `unknown`. */
45
63
  readonly otherwise?: readonly RunnableStep[];
64
+ /** A failure of THIS step is traced `failed-continued` and the sequence goes on (#500). */
65
+ readonly continueOnError?: boolean;
66
+ /** A `choose` step (#500): `run` is not called, the first branch that reads true is. */
67
+ readonly choose?: RunnableChoose;
68
+ /** A `parallel` step (#500): `run` is not called, these are started together and all awaited. */
69
+ readonly parallel?: readonly RunnableStep[];
70
+ /** A `repeat` step (#500): `run` is not called, the steps are, once per iteration. */
71
+ readonly repeat?: RunnableRepeat;
72
+ }
73
+ /** What a loop's condition answers: go on, or end the loop and why. */
74
+ export type RepeatCheck = {
75
+ readonly go: true;
76
+ } | {
77
+ readonly go: false;
78
+ readonly reason: string;
79
+ /** The condition could not be read: the loop ends and says so (D49). */
80
+ readonly unknown?: true;
81
+ };
82
+ export interface RunnableRepeat {
83
+ readonly steps: readonly RunnableStep[];
84
+ /** The most iterations the loop runs, whatever its condition says. */
85
+ readonly limit: number;
86
+ /** True when reaching `limit` means the condition never ended the loop: traced `timed-out`. */
87
+ readonly limitIsTimeout: boolean;
88
+ /** Asked before iteration `n` (0-based): a `while`, or the next device of a list. */
89
+ readonly before?: (iteration: number) => Promise<RepeatCheck>;
90
+ /** Asked after iteration `n`: an `until`. */
91
+ readonly after?: (iteration: number) => Promise<RepeatCheck>;
92
+ /** A pause between two iterations, never after the last. */
93
+ readonly between?: () => Promise<void>;
94
+ }
95
+ /** One branch of a `choose`: its condition and the steps it runs. */
96
+ export interface RunnableBranch {
97
+ readonly guard: () => Promise<StepConditionVerdict>;
98
+ readonly steps: readonly RunnableStep[];
99
+ }
100
+ export interface RunnableChoose {
101
+ readonly branches: readonly RunnableBranch[];
102
+ /** Run when every branch reads `false`; never when one reads `unknown`. */
103
+ readonly otherwise?: readonly RunnableStep[];
46
104
  }
47
105
  export interface StepFailure {
48
106
  readonly index: number;
@@ -68,12 +126,24 @@ export interface RunStepsOptions {
68
126
  readonly onFailure: (failure: StepFailure) => void;
69
127
  /** Called for a step skipped because its `if` read unknown: a branch that drops work says so (#472). */
70
128
  readonly onGuardUnknown?: (skipped: StepGuardUnknown) => void;
129
+ /** Called for a step that failed and was passed over (`continueOnError`): work that was dropped says so. */
130
+ readonly onContinuedFailure?: (failure: StepFailure) => void;
131
+ /** The index the first step of this list is traced at (a member of a `parallel` runs as a list of one). */
132
+ readonly indexOffset?: number;
71
133
  }
72
134
  export interface RunStepsResult {
73
135
  readonly steps: readonly AutomationStepTrace[];
74
136
  readonly failed: boolean;
75
137
  readonly aborted: boolean;
138
+ /** Set when a `stop` step ended the run. */
139
+ readonly stopped?: StepStop;
76
140
  }
141
+ /**
142
+ * What a loop's condition says about going on. A `while` goes on while it
143
+ * reads true, an `until` goes on while it reads false; `unknown` ends either,
144
+ * with the reason (D49): a loop never runs on a value it could not read.
145
+ */
146
+ export declare function repeatCheck(by: 'while' | 'until', verdict: StepConditionVerdict): RepeatCheck;
77
147
  export declare function runSteps(steps: readonly RunnableStep[], options: RunStepsOptions): Promise<RunStepsResult>;
78
148
  /** The bag of values `{ $var }` and `{{vars.x}}` read from. */
79
149
  export type StepVars = Readonly<Record<string, unknown>>;
@@ -70,6 +70,7 @@ export declare const AutomationConditionTraceNodeSchema: z.ZodObject<{
70
70
  detection: "detection";
71
71
  "device-becomes": "device-becomes";
72
72
  "device-event": "device-event";
73
+ "device-fired": "device-fired";
73
74
  "device-is": "device-is";
74
75
  expression: "expression";
75
76
  interval: "interval";
@@ -136,6 +137,90 @@ export declare const StepDeviceTraceSchema: z.ZodObject<{
136
137
  export type StepDeviceTrace = z.infer<typeof StepDeviceTraceSchema>;
137
138
  /** How many unknown-value notes one step trace keeps. */
138
139
  export declare const MAX_STEP_TEMPLATE_NOTES = 20;
140
+ /** A step one level down: it may be a block step itself, whose own steps are plain rows (the nesting ends there). */
141
+ export declare const NestedStepTraceSchema: z.ZodObject<{
142
+ path: z.ZodString;
143
+ kind: z.ZodString;
144
+ cap: z.ZodOptional<z.ZodString>;
145
+ method: z.ZodOptional<z.ZodString>;
146
+ actionId: z.ZodOptional<z.ZodString>;
147
+ deviceId: z.ZodOptional<z.ZodNumber>;
148
+ devices: z.ZodOptional<z.ZodArray<z.ZodObject<{
149
+ deviceId: z.ZodNumber;
150
+ outcome: z.ZodEnum<{
151
+ error: "error";
152
+ ok: "ok";
153
+ }>;
154
+ message: z.ZodOptional<z.ZodString>;
155
+ }, z.core.$strip>>>;
156
+ startedAt: z.ZodOptional<z.ZodNumber>;
157
+ endedAt: z.ZodOptional<z.ZodNumber>;
158
+ args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>>>;
159
+ templates: z.ZodOptional<z.ZodArray<z.ZodString>>;
160
+ condition: z.ZodOptional<z.ZodEnum<{
161
+ false: "false";
162
+ true: "true";
163
+ unknown: "unknown";
164
+ }>>;
165
+ conditionReason: z.ZodOptional<z.ZodString>;
166
+ outcome: z.ZodEnum<{
167
+ empty: "empty";
168
+ error: "error";
169
+ "failed-continued": "failed-continued";
170
+ "not-run": "not-run";
171
+ ok: "ok";
172
+ skipped: "skipped";
173
+ "timed-out": "timed-out";
174
+ }>;
175
+ message: z.ZodOptional<z.ZodString>;
176
+ branch: z.ZodOptional<z.ZodString>;
177
+ branchChecks: z.ZodOptional<z.ZodArray<z.ZodObject<{
178
+ condition: z.ZodEnum<{
179
+ false: "false";
180
+ true: "true";
181
+ unknown: "unknown";
182
+ }>;
183
+ conditionReason: z.ZodOptional<z.ZodString>;
184
+ }, z.core.$strip>>>;
185
+ iterations: z.ZodOptional<z.ZodNumber>;
186
+ steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
187
+ path: z.ZodString;
188
+ kind: z.ZodString;
189
+ cap: z.ZodOptional<z.ZodString>;
190
+ method: z.ZodOptional<z.ZodString>;
191
+ actionId: z.ZodOptional<z.ZodString>;
192
+ deviceId: z.ZodOptional<z.ZodNumber>;
193
+ devices: z.ZodOptional<z.ZodArray<z.ZodObject<{
194
+ deviceId: z.ZodNumber;
195
+ outcome: z.ZodEnum<{
196
+ error: "error";
197
+ ok: "ok";
198
+ }>;
199
+ message: z.ZodOptional<z.ZodString>;
200
+ }, z.core.$strip>>>;
201
+ startedAt: z.ZodOptional<z.ZodNumber>;
202
+ endedAt: z.ZodOptional<z.ZodNumber>;
203
+ args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>>>;
204
+ templates: z.ZodOptional<z.ZodArray<z.ZodString>>;
205
+ condition: z.ZodOptional<z.ZodEnum<{
206
+ false: "false";
207
+ true: "true";
208
+ unknown: "unknown";
209
+ }>>;
210
+ conditionReason: z.ZodOptional<z.ZodString>;
211
+ outcome: z.ZodEnum<{
212
+ empty: "empty";
213
+ error: "error";
214
+ "failed-continued": "failed-continued";
215
+ "not-run": "not-run";
216
+ ok: "ok";
217
+ skipped: "skipped";
218
+ "timed-out": "timed-out";
219
+ }>;
220
+ message: z.ZodOptional<z.ZodString>;
221
+ }, z.core.$strip>>>;
222
+ }, z.core.$strip>;
223
+ export type NestedStepTrace = z.infer<typeof NestedStepTraceSchema>;
139
224
  /** A step trace; the `else` steps that ran are one level of the same shape (the nesting is bounded at one). */
140
225
  export declare const AutomationStepTraceSchema: z.ZodObject<{
141
226
  path: z.ZodString;
@@ -165,11 +250,23 @@ export declare const AutomationStepTraceSchema: z.ZodObject<{
165
250
  outcome: z.ZodEnum<{
166
251
  empty: "empty";
167
252
  error: "error";
253
+ "failed-continued": "failed-continued";
168
254
  "not-run": "not-run";
169
255
  ok: "ok";
170
256
  skipped: "skipped";
257
+ "timed-out": "timed-out";
171
258
  }>;
172
259
  message: z.ZodOptional<z.ZodString>;
260
+ branch: z.ZodOptional<z.ZodString>;
261
+ branchChecks: z.ZodOptional<z.ZodArray<z.ZodObject<{
262
+ condition: z.ZodEnum<{
263
+ false: "false";
264
+ true: "true";
265
+ unknown: "unknown";
266
+ }>;
267
+ conditionReason: z.ZodOptional<z.ZodString>;
268
+ }, z.core.$strip>>>;
269
+ iterations: z.ZodOptional<z.ZodNumber>;
173
270
  else: z.ZodOptional<z.ZodArray<z.ZodObject<{
174
271
  path: z.ZodString;
175
272
  kind: z.ZodString;
@@ -198,15 +295,99 @@ export declare const AutomationStepTraceSchema: z.ZodObject<{
198
295
  outcome: z.ZodEnum<{
199
296
  empty: "empty";
200
297
  error: "error";
298
+ "failed-continued": "failed-continued";
201
299
  "not-run": "not-run";
202
300
  ok: "ok";
203
301
  skipped: "skipped";
302
+ "timed-out": "timed-out";
204
303
  }>;
205
304
  message: z.ZodOptional<z.ZodString>;
206
305
  }, z.core.$strip>>>;
306
+ steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
307
+ path: z.ZodString;
308
+ kind: z.ZodString;
309
+ cap: z.ZodOptional<z.ZodString>;
310
+ method: z.ZodOptional<z.ZodString>;
311
+ actionId: z.ZodOptional<z.ZodString>;
312
+ deviceId: z.ZodOptional<z.ZodNumber>;
313
+ devices: z.ZodOptional<z.ZodArray<z.ZodObject<{
314
+ deviceId: z.ZodNumber;
315
+ outcome: z.ZodEnum<{
316
+ error: "error";
317
+ ok: "ok";
318
+ }>;
319
+ message: z.ZodOptional<z.ZodString>;
320
+ }, z.core.$strip>>>;
321
+ startedAt: z.ZodOptional<z.ZodNumber>;
322
+ endedAt: z.ZodOptional<z.ZodNumber>;
323
+ args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>>>;
324
+ templates: z.ZodOptional<z.ZodArray<z.ZodString>>;
325
+ condition: z.ZodOptional<z.ZodEnum<{
326
+ false: "false";
327
+ true: "true";
328
+ unknown: "unknown";
329
+ }>>;
330
+ conditionReason: z.ZodOptional<z.ZodString>;
331
+ outcome: z.ZodEnum<{
332
+ empty: "empty";
333
+ error: "error";
334
+ "failed-continued": "failed-continued";
335
+ "not-run": "not-run";
336
+ ok: "ok";
337
+ skipped: "skipped";
338
+ "timed-out": "timed-out";
339
+ }>;
340
+ message: z.ZodOptional<z.ZodString>;
341
+ branch: z.ZodOptional<z.ZodString>;
342
+ branchChecks: z.ZodOptional<z.ZodArray<z.ZodObject<{
343
+ condition: z.ZodEnum<{
344
+ false: "false";
345
+ true: "true";
346
+ unknown: "unknown";
347
+ }>;
348
+ conditionReason: z.ZodOptional<z.ZodString>;
349
+ }, z.core.$strip>>>;
350
+ iterations: z.ZodOptional<z.ZodNumber>;
351
+ steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
352
+ path: z.ZodString;
353
+ kind: z.ZodString;
354
+ cap: z.ZodOptional<z.ZodString>;
355
+ method: z.ZodOptional<z.ZodString>;
356
+ actionId: z.ZodOptional<z.ZodString>;
357
+ deviceId: z.ZodOptional<z.ZodNumber>;
358
+ devices: z.ZodOptional<z.ZodArray<z.ZodObject<{
359
+ deviceId: z.ZodNumber;
360
+ outcome: z.ZodEnum<{
361
+ error: "error";
362
+ ok: "ok";
363
+ }>;
364
+ message: z.ZodOptional<z.ZodString>;
365
+ }, z.core.$strip>>>;
366
+ startedAt: z.ZodOptional<z.ZodNumber>;
367
+ endedAt: z.ZodOptional<z.ZodNumber>;
368
+ args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>>>;
369
+ templates: z.ZodOptional<z.ZodArray<z.ZodString>>;
370
+ condition: z.ZodOptional<z.ZodEnum<{
371
+ false: "false";
372
+ true: "true";
373
+ unknown: "unknown";
374
+ }>>;
375
+ conditionReason: z.ZodOptional<z.ZodString>;
376
+ outcome: z.ZodEnum<{
377
+ empty: "empty";
378
+ error: "error";
379
+ "failed-continued": "failed-continued";
380
+ "not-run": "not-run";
381
+ ok: "ok";
382
+ skipped: "skipped";
383
+ "timed-out": "timed-out";
384
+ }>;
385
+ message: z.ZodOptional<z.ZodString>;
386
+ }, z.core.$strip>>>;
387
+ }, z.core.$strip>>>;
207
388
  }, z.core.$strip>;
208
389
  export type AutomationStepTrace = z.infer<typeof AutomationStepTraceSchema>;
209
- export declare const AutomationRunTraceSchema: z.ZodObject<{
390
+ declare const runTraceObject: z.ZodObject<{
210
391
  runId: z.ZodString;
211
392
  startedAt: z.ZodNumber;
212
393
  endedAt: z.ZodNumber;
@@ -244,6 +425,7 @@ export declare const AutomationRunTraceSchema: z.ZodObject<{
244
425
  detection: "detection";
245
426
  "device-becomes": "device-becomes";
246
427
  "device-event": "device-event";
428
+ "device-fired": "device-fired";
247
429
  "device-is": "device-is";
248
430
  expression: "expression";
249
431
  interval: "interval";
@@ -321,11 +503,23 @@ export declare const AutomationRunTraceSchema: z.ZodObject<{
321
503
  outcome: z.ZodEnum<{
322
504
  empty: "empty";
323
505
  error: "error";
506
+ "failed-continued": "failed-continued";
324
507
  "not-run": "not-run";
325
508
  ok: "ok";
326
509
  skipped: "skipped";
510
+ "timed-out": "timed-out";
327
511
  }>;
328
512
  message: z.ZodOptional<z.ZodString>;
513
+ branch: z.ZodOptional<z.ZodString>;
514
+ branchChecks: z.ZodOptional<z.ZodArray<z.ZodObject<{
515
+ condition: z.ZodEnum<{
516
+ false: "false";
517
+ true: "true";
518
+ unknown: "unknown";
519
+ }>;
520
+ conditionReason: z.ZodOptional<z.ZodString>;
521
+ }, z.core.$strip>>>;
522
+ iterations: z.ZodOptional<z.ZodNumber>;
329
523
  else: z.ZodOptional<z.ZodArray<z.ZodObject<{
330
524
  path: z.ZodString;
331
525
  kind: z.ZodString;
@@ -354,132 +548,15 @@ export declare const AutomationRunTraceSchema: z.ZodObject<{
354
548
  outcome: z.ZodEnum<{
355
549
  empty: "empty";
356
550
  error: "error";
551
+ "failed-continued": "failed-continued";
357
552
  "not-run": "not-run";
358
553
  ok: "ok";
359
554
  skipped: "skipped";
555
+ "timed-out": "timed-out";
360
556
  }>;
361
557
  message: z.ZodOptional<z.ZodString>;
362
558
  }, z.core.$strip>>>;
363
- }, z.core.$strip>>;
364
- outcome: z.ZodEnum<{
365
- aborted: "aborted";
366
- failed: "failed";
367
- ran: "ran";
368
- "skipped-conditions": "skipped-conditions";
369
- "skipped-cooldown": "skipped-cooldown";
370
- "skipped-overlap": "skipped-overlap";
371
- "skipped-trigger": "skipped-trigger";
372
- }>;
373
- repeat: z.ZodNumber;
374
- lastAt: z.ZodNumber;
375
- scheduler: z.ZodOptional<z.ZodEnum<{
376
- "condition-false": "condition-false";
377
- done: "done";
378
- failed: "failed";
379
- "gave-up": "gave-up";
380
- held: "held";
381
- inactive: "inactive";
382
- missed: "missed";
383
- overridden: "overridden";
384
- "suspended-manual": "suspended-manual";
385
- }>>;
386
- }, z.core.$strip>;
387
- export type AutomationRunTrace = z.infer<typeof AutomationRunTraceSchema>;
388
- /**
389
- * What the hub's `runs` ledger holds for one owner (`automation:<blockId>` or
390
- * `action:<actionId>`): the cooldown stamp and the trace ring.
391
- */
392
- export declare const AutomationStateDocSchema: z.ZodObject<{
393
- version: z.ZodLiteral<1>;
394
- lastRunStartedAt: z.ZodNullable<z.ZodNumber>;
395
- traces: z.ZodArray<z.ZodObject<{
396
- runId: z.ZodString;
397
- startedAt: z.ZodNumber;
398
- endedAt: z.ZodNumber;
399
- trigger: z.ZodObject<{
400
- kind: z.ZodString;
401
- path: z.ZodOptional<z.ZodString>;
402
- outcome: z.ZodEnum<{
403
- fail: "fail";
404
- pass: "pass";
405
- }>;
406
- reason: z.ZodString;
407
- vars: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>>;
408
- hold: z.ZodOptional<z.ZodObject<{
409
- phase: z.ZodEnum<{
410
- cancelled: "cancelled";
411
- fired: "fired";
412
- pending: "pending";
413
- reseeded: "reseeded";
414
- }>;
415
- ms: z.ZodNumber;
416
- mode: z.ZodEnum<{
417
- held: "held";
418
- stable: "stable";
419
- }>;
420
- since: z.ZodOptional<z.ZodNumber>;
421
- deadline: z.ZodOptional<z.ZodNumber>;
422
- }, z.core.$strip>>;
423
- }, z.core.$strip>;
424
- conditions: z.ZodArray<z.ZodObject<{
425
- path: z.ZodString;
426
- kind: z.ZodEnum<{
427
- all: "all";
428
- any: "any";
429
- condition: "condition";
430
- detection: "detection";
431
- "device-becomes": "device-becomes";
432
- "device-event": "device-event";
433
- "device-is": "device-is";
434
- expression: "expression";
435
- interval: "interval";
436
- manual: "manual";
437
- not: "not";
438
- schedule: "schedule";
439
- stationary: "stationary";
440
- "stationary-present": "stationary-present";
441
- "time-is": "time-is";
442
- "triggered-by": "triggered-by";
443
- }>;
444
- outcome: z.ZodEnum<{
445
- fail: "fail";
446
- "not-evaluated": "not-evaluated";
447
- pass: "pass";
448
- }>;
449
- reason: z.ZodString;
450
- deviceId: z.ZodOptional<z.ZodNumber>;
451
- cap: z.ZodOptional<z.ZodString>;
452
- fieldPath: z.ZodOptional<z.ZodString>;
453
- operator: z.ZodOptional<z.ZodString>;
454
- expected: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>>;
455
- observed: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>>;
456
- }, z.core.$strip>>;
457
- verdict: z.ZodOptional<z.ZodObject<{
458
- mode: z.ZodDiscriminatedUnion<[z.ZodObject<{
459
- mode: z.ZodLiteral<"single">;
460
- }, z.core.$strip>, z.ZodObject<{
461
- mode: z.ZodLiteral<"restart">;
462
- }, z.core.$strip>, z.ZodObject<{
463
- mode: z.ZodLiteral<"queued">;
464
- max: z.ZodNumber;
465
- }, z.core.$strip>, z.ZodObject<{
466
- mode: z.ZodLiteral<"parallel">;
467
- max: z.ZodNumber;
468
- }, z.core.$strip>, z.ZodObject<{
469
- mode: z.ZodLiteral<"cooldown">;
470
- minutes: z.ZodNumber;
471
- }, z.core.$strip>], "mode">;
472
- decision: z.ZodEnum<{
473
- bypass: "bypass";
474
- cooldown: "cooldown";
475
- drop: "drop";
476
- queued: "queued";
477
- restart: "restart";
478
- run: "run";
479
- }>;
480
- reason: z.ZodString;
481
- }, z.core.$strip>>;
482
- steps: z.ZodArray<z.ZodObject<{
559
+ steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
483
560
  path: z.ZodString;
484
561
  kind: z.ZodString;
485
562
  cap: z.ZodOptional<z.ZodString>;
@@ -507,12 +584,24 @@ export declare const AutomationStateDocSchema: z.ZodObject<{
507
584
  outcome: z.ZodEnum<{
508
585
  empty: "empty";
509
586
  error: "error";
587
+ "failed-continued": "failed-continued";
510
588
  "not-run": "not-run";
511
589
  ok: "ok";
512
590
  skipped: "skipped";
591
+ "timed-out": "timed-out";
513
592
  }>;
514
593
  message: z.ZodOptional<z.ZodString>;
515
- else: z.ZodOptional<z.ZodArray<z.ZodObject<{
594
+ branch: z.ZodOptional<z.ZodString>;
595
+ branchChecks: z.ZodOptional<z.ZodArray<z.ZodObject<{
596
+ condition: z.ZodEnum<{
597
+ false: "false";
598
+ true: "true";
599
+ unknown: "unknown";
600
+ }>;
601
+ conditionReason: z.ZodOptional<z.ZodString>;
602
+ }, z.core.$strip>>>;
603
+ iterations: z.ZodOptional<z.ZodNumber>;
604
+ steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
516
605
  path: z.ZodString;
517
606
  kind: z.ZodString;
518
607
  cap: z.ZodOptional<z.ZodString>;
@@ -540,36 +629,55 @@ export declare const AutomationStateDocSchema: z.ZodObject<{
540
629
  outcome: z.ZodEnum<{
541
630
  empty: "empty";
542
631
  error: "error";
632
+ "failed-continued": "failed-continued";
543
633
  "not-run": "not-run";
544
634
  ok: "ok";
545
635
  skipped: "skipped";
636
+ "timed-out": "timed-out";
546
637
  }>;
547
638
  message: z.ZodOptional<z.ZodString>;
548
639
  }, z.core.$strip>>>;
549
- }, z.core.$strip>>;
550
- outcome: z.ZodEnum<{
551
- aborted: "aborted";
552
- failed: "failed";
553
- ran: "ran";
554
- "skipped-conditions": "skipped-conditions";
555
- "skipped-cooldown": "skipped-cooldown";
556
- "skipped-overlap": "skipped-overlap";
557
- "skipped-trigger": "skipped-trigger";
558
- }>;
559
- repeat: z.ZodNumber;
560
- lastAt: z.ZodNumber;
561
- scheduler: z.ZodOptional<z.ZodEnum<{
562
- "condition-false": "condition-false";
563
- done: "done";
564
- failed: "failed";
565
- "gave-up": "gave-up";
566
- held: "held";
567
- inactive: "inactive";
568
- missed: "missed";
569
- overridden: "overridden";
570
- "suspended-manual": "suspended-manual";
571
- }>>;
640
+ }, z.core.$strip>>>;
572
641
  }, z.core.$strip>>;
642
+ outcome: z.ZodEnum<{
643
+ aborted: "aborted";
644
+ failed: "failed";
645
+ ran: "ran";
646
+ "skipped-conditions": "skipped-conditions";
647
+ "skipped-cooldown": "skipped-cooldown";
648
+ "skipped-overlap": "skipped-overlap";
649
+ "skipped-trigger": "skipped-trigger";
650
+ }>;
651
+ repeat: z.ZodNumber;
652
+ lastAt: z.ZodNumber;
653
+ scheduler: z.ZodOptional<z.ZodEnum<{
654
+ "condition-false": "condition-false";
655
+ done: "done";
656
+ failed: "failed";
657
+ "gave-up": "gave-up";
658
+ held: "held";
659
+ inactive: "inactive";
660
+ missed: "missed";
661
+ overridden: "overridden";
662
+ "suspended-manual": "suspended-manual";
663
+ }>>;
664
+ }, z.core.$strip>;
665
+ /**
666
+ * Declared as an interface so it is printed by NAME: a capability that embeds
667
+ * the trace would otherwise inline every nested row into its own type, past
668
+ * what the compiler can print (TS7056).
669
+ */
670
+ export interface AutomationRunTrace extends z.infer<typeof runTraceObject> {
671
+ }
672
+ export declare const AutomationRunTraceSchema: z.ZodType<AutomationRunTrace>;
673
+ /**
674
+ * What the hub's `runs` ledger holds for one owner (`automation:<blockId>` or
675
+ * `action:<actionId>`): the cooldown stamp and the trace ring.
676
+ */
677
+ export declare const AutomationStateDocSchema: z.ZodObject<{
678
+ version: z.ZodLiteral<1>;
679
+ lastRunStartedAt: z.ZodNullable<z.ZodNumber>;
680
+ traces: z.ZodArray<z.ZodType<AutomationRunTrace, unknown, z.core.$ZodTypeInternals<AutomationRunTrace, unknown>>>;
573
681
  }, z.core.$strip>;
574
682
  export type AutomationStateDoc = z.infer<typeof AutomationStateDocSchema>;
575
683
  /** The state of an owner that never reported. */
@@ -615,3 +723,4 @@ export declare function buildStepArgsTrace(args: Readonly<Record<string, unknown
615
723
  * bookkeeping keys `kind`, `at` and `leaf` (the fired leaf's path, which moves to `path`).
616
724
  */
617
725
  export declare function buildTriggerTrace(trigger: Readonly<Record<string, unknown>>, outcome: 'pass' | 'fail', reason: string): AutomationTriggerTrace;
726
+ export {};
@@ -0,0 +1,32 @@
1
+ /**
2
+ * The loop of a `wait-until` step (#500): read the condition, and while it is
3
+ * not true wait for the next wake (a device report, the reconcile tick, a
4
+ * restart) and read again, until the timeout.
5
+ *
6
+ * `unknown` is never "met" (D49): a condition that cannot be read keeps the
7
+ * run waiting and, at the deadline, is what the timeout reports.
8
+ */
9
+ import type { StepConditionVerdict } from './step-condition.js';
10
+ export interface WaitUntilInput {
11
+ /** Read the condition NOW. A read that throws counts as `unknown`. */
12
+ readonly read: () => Promise<StepConditionVerdict>;
13
+ readonly timeoutMs: number;
14
+ readonly now: () => number;
15
+ /** Resolve at the next reason to read again, and no later than `ms` from now. */
16
+ readonly nextWake: (ms: number) => Promise<void>;
17
+ readonly isAborted: () => boolean;
18
+ }
19
+ export type WaitUntilResult = {
20
+ readonly result: 'met';
21
+ readonly waitedMs: number;
22
+ } | {
23
+ readonly result: 'timed-out';
24
+ readonly waitedMs: number;
25
+ readonly lastReason: string;
26
+ } | {
27
+ readonly result: 'aborted';
28
+ readonly waitedMs: number;
29
+ };
30
+ export declare function waitUntil(input: WaitUntilInput): Promise<WaitUntilResult>;
31
+ /** What the run trace says of a wait that ran out. */
32
+ export declare function waitTimedOutMessage(timeoutS: number, lastReason: string): string;
@@ -6,7 +6,7 @@
6
6
  * the operator believes is working. Pure: the site reading is handed in.
7
7
  */
8
8
  import { type SiteReading, type TimeSpecRefusal } from '../time/time-spec.js';
9
- import type { AutomationRecipe } from './recipe.js';
9
+ import { type AutomationRecipe } from './recipe.js';
10
10
  import { type AutomationWhen } from './when.js';
11
11
  export interface WhenSiteIssue {
12
12
  /** `when.1.between.from` — the end of the window that cannot be placed. */