@powerhousedao/reactor-workflow 6.2.3-dev.49 → 6.2.3-dev.51

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.
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { A as BlockMatch, D as EgressPolicy, M as PieceOrigin, b as PieceWorkerResult, c as ConnectionRequest, d as SecretStore, h as WorkflowRunResult, j as BlockResolution, m as StepExecutionRecord, n as packagePieces, o as AttachmentPort, p as PropertySettingDef, r as CORE_PIECE_NAME, t as PieceRegistry, v as ModelManifestSource, w as PieceResolver, x as ReactorTap, y as PieceWorker } from "./piece-registry-wQBhKJUl.js";
1
+ import { C as StepExecutionRecord, F as BlockResolution, I as PieceOrigin, O as PieceResolver, P as BlockMatch, S as PropertySettingDef, T as ReactorTap, _ as PieceWorkerResult, b as WorkflowTelemetryOptions, f as SecretStore, g as PieceWorker, h as ModelManifestSource, i as ReplayedStep, j as EgressPolicy, l as ConnectionRequest, n as packagePieces, r as CORE_PIECE_NAME, s as AttachmentPort, t as PieceRegistry, v as TELEMETRY_SCOPE, w as WorkflowRunResult, y as WorkflowTelemetry } from "./piece-registry-BdkdVugw.js";
2
2
  import { ActionBase, TriggerBase } from "@powerhousedao/pieces-framework";
3
3
  import { ILogger, OperationWithContext } from "document-model";
4
4
  import "@powerhousedao/pieces-framework/workflow";
@@ -16,12 +16,16 @@ interface AttachmentClientLike {
16
16
  file: Blob;
17
17
  fileName?: string;
18
18
  mimeType?: string;
19
+ } | {
20
+ preprocessed: PreprocessedUpload;
21
+ signal?: AbortSignal;
19
22
  }): Promise<{
20
23
  ref?: string;
21
24
  } & Record<string, unknown>>;
22
25
  download(input: {
23
26
  documentId: string;
24
27
  ref: string;
28
+ signal?: AbortSignal;
25
29
  }): Promise<{
26
30
  header: {
27
31
  sizeBytes?: number;
@@ -31,7 +35,26 @@ interface AttachmentClientLike {
31
35
  body: ReadableStream<Uint8Array>;
32
36
  }>;
33
37
  }
34
- export declare function createAttachmentPort(client: AttachmentClientLike, documentIdFor: () => string | undefined, canReadRef: (documentId: string, ref: string) => Promise<boolean>): AttachmentPort;
38
+ interface PreprocessedUpload {
39
+ ref: string;
40
+ hash: string;
41
+ sizeBytes: number;
42
+ options: {
43
+ mimeType: string;
44
+ fileName: string;
45
+ extension?: string | null;
46
+ clientHash: string;
47
+ sizeBytes: number;
48
+ };
49
+ data: ReadableStream<Uint8Array>;
50
+ stream: () => ReadableStream<Uint8Array>;
51
+ }
52
+ interface AttachmentPortAccess {
53
+ documentIdFor: () => string | undefined;
54
+ canReadRef: (ref: string) => Promise<boolean>;
55
+ onWritten?: (ref: string) => void;
56
+ }
57
+ export declare function createAttachmentPort(client: AttachmentClientLike, access: AttachmentPortAccess): AttachmentPort;
35
58
  //#endregion
36
59
  //#region src/reactor/package-name.d.ts
37
60
  export declare const WORKFLOW_PACKAGE_NAME = "@powerhousedao/workflow";
@@ -39,12 +62,37 @@ export declare const WORKFLOW_PACKAGE_NAME = "@powerhousedao/workflow";
39
62
  //#region src/pieces/activepieces/registry-source.d.ts
40
63
  export declare function setPieceRegistryUrl(url: string | undefined): void;
41
64
  //#endregion
65
+ //#region src/reactor/run-scope.d.ts
66
+ interface ReactorConnectionScope {
67
+ access: "read" | "write";
68
+ }
69
+ interface RunScope {
70
+ runUser: {
71
+ address: string;
72
+ subject: AuthSubject;
73
+ } | null;
74
+ requireReactor: "read" | "write";
75
+ connection: ReactorConnectionScope;
76
+ deadline: number;
77
+ journal: {
78
+ recordDocuments(documentIds: string[]): Promise<void>;
79
+ recordJob(jobId: string, documentIds: string[]): Promise<void>;
80
+ };
81
+ }
82
+ type RunUser = NonNullable<RunScope["runUser"]>;
83
+ //#endregion
42
84
  //#region src/reactor/host.d.ts
43
85
  type WorkflowCaller = object;
44
86
  type HostIdentity = {
45
87
  address?: string;
46
88
  key: string;
47
89
  };
90
+ interface AttachmentReadRequest {
91
+ workflowId: string;
92
+ ref: string;
93
+ documentIds: string[];
94
+ runUser?: RunUser | null;
95
+ }
48
96
  interface WorkflowRuntimeHostDeps {
49
97
  relationalDb: IRelationalDb;
50
98
  reactorClient: IReactorClient;
@@ -58,10 +106,11 @@ interface WorkflowRuntimeHostDeps {
58
106
  modelEntries?(documentType: string): ModelManifestEntry[];
59
107
  webhooks?: IWebhookScope;
60
108
  attachments?: AttachmentClientLike;
61
- canReadAttachmentRef?(documentId: string, ref: string): Promise<boolean>;
109
+ canReadAttachmentRef?(request: AttachmentReadRequest): Promise<boolean>;
62
110
  secrets?: SecretStore;
63
111
  secretsKeyFile?: string | false;
64
112
  logger?: ILogger;
113
+ telemetry?: WorkflowTelemetryOptions;
65
114
  syncWaitMs?: number;
66
115
  pieceVersionLookupMs?: number;
67
116
  }
@@ -97,6 +146,7 @@ interface OutputTree {
97
146
  }
98
147
  //#endregion
99
148
  //#region src/reactor/piece-catalog.d.ts
149
+ type PieceSource = "local" | "registry" | "activepieces";
100
150
  interface PieceSummary {
101
151
  name: string;
102
152
  displayName: string;
@@ -106,6 +156,7 @@ interface PieceSummary {
106
156
  actionCount: number;
107
157
  triggerCount: number;
108
158
  categories: string[];
159
+ source: PieceSource;
109
160
  auth: unknown;
110
161
  unsupported?: string;
111
162
  deprecated?: boolean;
@@ -154,13 +205,34 @@ interface BlockSearchHit {
154
205
  strategy: string | null;
155
206
  unsupported?: string;
156
207
  }
208
+ interface SearchPieceMeta {
209
+ pieceName: string;
210
+ pieceVersion: string;
211
+ displayName: string;
212
+ description: string;
213
+ logoUrl: string;
214
+ categories: string[];
215
+ source: PieceSource;
216
+ deprecated?: boolean;
217
+ unsupported?: string;
218
+ }
219
+ interface PieceSearchMatch extends SearchPieceMeta {
220
+ namedPiece: boolean;
221
+ blocks: BlockSearchHit[];
222
+ }
157
223
  type BlockSearchStatus = "ready" | "indexing" | "error";
158
- interface BlockSearchResult {
224
+ interface PieceSearchResult {
159
225
  status: BlockSearchStatus;
160
- hits: BlockSearchHit[];
226
+ pieces: PieceSearchMatch[];
161
227
  indexedPieces: number;
162
228
  error: string | null;
163
229
  }
230
+ interface PieceSearchFilter {
231
+ kind: BlockSearchKind;
232
+ sources?: readonly PieceSource[];
233
+ categories?: readonly string[];
234
+ limit?: number;
235
+ }
164
236
  //#endregion
165
237
  //#region src/reactor/sync-wait.d.ts
166
238
  export declare const WORKFLOW_SYNCING_MESSAGE = "Workflow is still syncing; try again in a moment";
@@ -176,7 +248,7 @@ interface WorkflowAccessOptions {
176
248
  //#region src/reactor/step-test.d.ts
177
249
  interface StepTestResult {
178
250
  runId: string | null;
179
- status: "SUCCEEDED" | "FAILED";
251
+ status: "SUCCEEDED" | "FAILED" | "INDETERMINATE";
180
252
  output?: unknown;
181
253
  error?: string;
182
254
  errorName?: string;
@@ -222,6 +294,7 @@ interface StepExecutionRow {
222
294
  version_match: string | null;
223
295
  version_note: string | null;
224
296
  config_hash: string | null;
297
+ attempts: number | null;
225
298
  }
226
299
  interface RunDocumentRow {
227
300
  run_id: string;
@@ -257,7 +330,18 @@ interface TriggerDedupeRow {
257
330
  dedupe_key: string;
258
331
  run_id: string | null;
259
332
  created_at: string;
260
- }
333
+ attempts: number | null;
334
+ }
335
+ /** What a fire claim resolved to; see {@link WorkflowRunStore.claimAndEnqueueRun}. */
336
+ type FireClaim = {
337
+ outcome: "claimed";
338
+ runId: string;
339
+ } | {
340
+ outcome: "duplicate";
341
+ } | {
342
+ outcome: "abandoned";
343
+ attempts: number;
344
+ };
261
345
  interface PieceStoreRow {
262
346
  scope: string;
263
347
  scope_key: string;
@@ -265,6 +349,12 @@ interface PieceStoreRow {
265
349
  value: string;
266
350
  updated_at: string;
267
351
  }
352
+ interface WorkflowParkRow {
353
+ workflow_id: string;
354
+ published_version: number;
355
+ reason: string;
356
+ parked_at: string;
357
+ }
268
358
  interface WorkflowRuntimeDB {
269
359
  run: RunRow;
270
360
  step_execution: StepExecutionRow;
@@ -272,6 +362,11 @@ interface WorkflowRuntimeDB {
272
362
  trigger_state: TriggerStateRow;
273
363
  trigger_dedupe: TriggerDedupeRow;
274
364
  piece_store: PieceStoreRow;
365
+ workflow_park: WorkflowParkRow;
366
+ migration_mark: {
367
+ name: string;
368
+ applied_at: string;
369
+ };
275
370
  }
276
371
  interface ErasedRuns {
277
372
  runs: number;
@@ -310,8 +405,86 @@ declare class WorkflowRunStore {
310
405
  clearUnmigratedTriggerState(workflowId: string): void;
311
406
  recoverOrphanedRuns(): Promise<number>;
312
407
  recoverAbandonedRuns(): Promise<number>;
408
+ /**
409
+ * Closes a run out as CANCELLED, with the reason as its error.
410
+ *
411
+ * Two callers, one meaning — "this run did not finish, and the workflow is
412
+ * not at fault": a firing SINGLETON concurrency refused, and a run that
413
+ * passed its `runTimeoutSeconds`. Separate from `failRun` because a
414
+ * CANCELLED run is not rerunnable and must not read as a workflow defect.
415
+ */
416
+ cancelRun(runId: string, reason: string): Promise<void>;
313
417
  enqueueRun(options: EnqueueRunOptions): Promise<string>;
314
- claimAndEnqueueRun(dedupeKey: string, ttlMs: number, nowIso: string, options: EnqueueRunOptions): Promise<string | null>;
418
+ /**
419
+ * Claims the dedupe key and journals the PENDING run, bounding crash replays.
420
+ *
421
+ * Three outcomes, as {@link FireClaim}:
422
+ *
423
+ * - **`"claimed"`** with a run id: this fire is ours to run.
424
+ * - **`"duplicate"`**: an earlier delivery of this operation already
425
+ * fired: it journaled a run, or ran without one
426
+ * ({@link FIRED_WITHOUT_RUN_ID}).
427
+ * - **`"abandoned"`**: the operation has been delivered
428
+ * {@link FIRE_CRASH_BUDGET} times and has never once got as far as
429
+ * journaling a run — i.e. it is taking the process down before the write
430
+ * lands, and the read-model cursor replays it on every boot. That is the
431
+ * EPIPE boot loop (backlog item 5), and a budget is what turns it from an
432
+ * unbootable reactor into one FAILED run naming the loop.
433
+ *
434
+ * Two writes, and which one is which matters:
435
+ *
436
+ * - The **attempt count** is bumped in its own committed transaction,
437
+ * BEFORE the risky work. That is the only way a delivery that leaves no
438
+ * run behind can be counted at all, which is what the budget needs. The
439
+ * counter is never a claim signal — it only decides the budget.
440
+ * - The **claim** is `run_id`, and it is set in the SAME transaction as the
441
+ * run row, under a `WHERE run_id IS NULL` guard. The guard takes the
442
+ * row's lock, so of two concurrent deliveries of one operation the second
443
+ * blocks until the first commits and then matches no row: exactly one
444
+ * delivery wins, and the run it journaled is committed with the claim. A
445
+ * crash in between rolls BOTH back, so a claim that holds a run id always
446
+ * holds a run — and a claim without one is retried, up to the budget.
447
+ *
448
+ * Counting and claiming are deliberately not the same write: if the bump
449
+ * rode along inside the claim transaction, a run insert that takes the
450
+ * process down would roll the count back with it and the budget could never
451
+ * reach its limit — the boot loop it exists to bound.
452
+ */
453
+ claimAndEnqueueRun(dedupeKey: string, ttlMs: number, nowIso: string, options: EnqueueRunOptions): Promise<FireClaim>;
454
+ journalTriggerItems(items: {
455
+ dedupeKey?: string;
456
+ options: EnqueueRunOptions;
457
+ }[], ttlMs: number, nowIso: string): Promise<(string | undefined)[]>;
458
+ recordScheduleFire(nowIso: string, nextPollAtIso: string, options: EnqueueRunOptions): Promise<string>;
459
+ /**
460
+ * Puts a piece_store partition back to `entries` and, in the same write,
461
+ * cancels the runs the restored cursor delivers again and releases their
462
+ * claims, so no reader sees the old cursor while the claims still hold.
463
+ */
464
+ rewindPieceStore(scope: string, scopeKey: string, entries: Record<string, unknown>, redelivered?: {
465
+ runIds: string[];
466
+ reason: string;
467
+ }): Promise<void>;
468
+ /**
469
+ * Counts one delivery of an operation, and reports whether a run was ever
470
+ * journaled for it.
471
+ *
472
+ * Committed on its own: the point is to leave a trace even when whatever
473
+ * comes next takes the process down. It is NOT a claim — the row it writes
474
+ * holds no run id, and {@link claimAndEnqueueRun} is what decides, under a
475
+ * lock, which delivery gets to fill it in.
476
+ */
477
+ recordFireAttempt(workflowId: string, dedupeKey: string, ttlMs: number, nowIso: string): Promise<{
478
+ attempts: number;
479
+ runId: string | null;
480
+ }>;
481
+ /**
482
+ * The abandonment of an over-budget fire, as a visible FAILED run, linked to
483
+ * its dedupe key so a later delivery is a duplicate rather than another one.
484
+ */
485
+ journalAbandonedFire(dedupeKey: string, options: EnqueueRunOptions & {
486
+ attempts: number;
487
+ }): Promise<string>;
315
488
  private insertPendingRun;
316
489
  beginRun(runId: string, details: {
317
490
  workflowName: string;
@@ -331,6 +504,19 @@ declare class WorkflowRunStore {
331
504
  recordRunDocuments(runId: string, documentIds: string[]): Promise<void>;
332
505
  getRunDocuments(runId: string): Promise<string[]>;
333
506
  getRunDocumentsForRuns(runIds: string[]): Promise<Map<string, string[]>>;
507
+ /**
508
+ * Parks a workflow: its park row, and an ENABLED trigger_state row turned
509
+ * PARKED, in one transaction. True when a trigger_state row was parked.
510
+ */
511
+ parkWorkflow(workflowId: string, publishedVersion: number, reason: string): Promise<boolean>;
512
+ /** A disable clears a park: the park row, and a PARKED trigger row turned
513
+ * DISABLED, so re-enabling arms it whether or not the supervisor held it. */
514
+ clearParkOnDisable(workflowId: string): Promise<void>;
515
+ /** Undoes {@link parkWorkflow}; `trigger` says whether it parked a row. */
516
+ liftPark(workflowId: string, trigger: boolean): Promise<void>;
517
+ getWorkflowPark(workflowId: string): Promise<WorkflowParkRow | undefined>;
518
+ listWorkflowParks(): Promise<WorkflowParkRow[]>;
519
+ clearWorkflowPark(workflowId: string): Promise<void>;
334
520
  getTriggerState(workflowId: string): Promise<TriggerStateRow | undefined>;
335
521
  upsertTriggerState(row: TriggerStateInput): Promise<void>;
336
522
  setTriggerStatus(workflowId: string, status: string, error?: string): Promise<void>;
@@ -355,24 +541,22 @@ declare class WorkflowRunStore {
355
541
  deletePieceStore(scope: string, scopeKey: string): Promise<void>;
356
542
  }
357
543
  //#endregion
358
- //#region src/reactor/run-scope.d.ts
359
- interface ReactorConnectionScope {
360
- access: "read" | "write";
361
- }
362
- interface RunScope {
363
- runUser: {
364
- address: string;
365
- subject: AuthSubject;
366
- } | null;
367
- requireReactor: "read" | "write";
368
- connection: ReactorConnectionScope;
369
- deadline: number;
370
- journal: {
371
- recordDocuments(documentIds: string[]): Promise<void>;
372
- recordJob(jobId: string, documentIds: string[]): Promise<void>;
373
- };
544
+ //#region src/reactor/park-state.d.ts
545
+ declare class ParkState {
546
+ private readonly load;
547
+ private readonly parks;
548
+ private readonly written;
549
+ private seeded;
550
+ private seeding?;
551
+ constructor(load: () => Promise<readonly WorkflowParkRow[] | undefined>);
552
+ get(workflowId: string): Promise<WorkflowParkRow | undefined>;
553
+ known(workflowId: string): {
554
+ park?: WorkflowParkRow;
555
+ } | undefined;
556
+ set(park: WorkflowParkRow): void;
557
+ delete(workflowId: string): void;
558
+ private seed;
374
559
  }
375
- type RunUser = NonNullable<RunScope["runUser"]>;
376
560
  //#endregion
377
561
  //#region src/reactor/trigger-supervisor.d.ts
378
562
  interface PieceTriggerBinding {
@@ -400,12 +584,14 @@ interface ScheduleTriggerBinding {
400
584
  type TriggerBinding = PieceTriggerBinding | ScheduleTriggerBinding;
401
585
  interface TriggerSupervisorOptions {
402
586
  store: () => Promise<WorkflowRunStore | undefined>;
587
+ parks?: ParkState;
403
588
  resolveAuth: (connectionId: string | null | undefined, request?: ConnectionRequest) => Promise<unknown>;
404
- fire: (workflowId: string, payload: unknown, kind: string) => void;
589
+ fire: (workflowId: string, payload: unknown, kind: string, runId: string) => void;
405
590
  cacheDir: string;
406
591
  resolver?: PieceResolver;
407
592
  worker?: PieceWorker;
408
593
  models?: ModelManifestSource;
594
+ telemetry?: WorkflowTelemetry;
409
595
  reactorAccess?: (binding: PieceTriggerBinding, requireReactor: "read" | "write", runUser: RunUser | null | undefined) => Promise<ReactorTap>;
410
596
  egress?: EgressPolicy | null;
411
597
  tickMs?: number;
@@ -424,20 +610,39 @@ declare class TriggerSupervisor {
424
610
  private readonly hookTimeoutMs;
425
611
  private readonly now;
426
612
  private readonly egress;
613
+ private readonly parks;
427
614
  private timer?;
428
615
  private ops;
429
616
  private ticking;
430
617
  private warnedMissingJournal;
618
+ private stopped;
431
619
  constructor(options: TriggerSupervisorOptions);
432
620
  start(): void;
433
621
  stop(): void;
434
622
  private enqueue;
623
+ private throwIfStopped;
624
+ private store;
625
+ private fire;
435
626
  private readonly enabledOk;
436
627
  private readonly descriptors;
437
628
  private own;
438
629
  private resolver;
439
630
  private readonly enableRetries;
440
- upsert(binding: TriggerBinding): Promise<void>;
631
+ private readonly versions;
632
+ upsert(binding: TriggerBinding, publishedVersion?: number): Promise<void>;
633
+ /** Parks a workflow; true when a trigger row was parked with it. */
634
+ park(workflowId: string, publishedVersion: number, reason: string): Promise<boolean>;
635
+ /** Undoes {@link park} for that version only: a later park stands. */
636
+ liftPark(workflowId: string, publishedVersion: number, trigger: boolean): Promise<void>;
637
+ /** A disable clears the park. With no binding in memory to release a PARKED
638
+ * row through onDisable (a boot), the row is turned DISABLED here. */
639
+ releasePark(workflowId: string, flipRow: boolean): Promise<void>;
640
+ /** A re-publish past the parked version: on this lane, a park older than
641
+ * `publishedVersion` goes and a row it parked is ENABLED again, as it was
642
+ * before (only an ENABLED row is ever parked); a park as new stands. The
643
+ * next upsert of the same binding then arms rather than skipping as
644
+ * unchanged, and a retry held back by the park is due now. */
645
+ unpark(workflowId: string, publishedVersion: number): Promise<void>;
441
646
  remove(workflowId: string): Promise<void>;
442
647
  forget(workflowId: string): Promise<void>;
443
648
  private unbind;
@@ -458,6 +663,30 @@ declare class TriggerSupervisor {
458
663
  private enable;
459
664
  private renewAtAfterEnable;
460
665
  private webhookUrlOrThrow;
666
+ /**
667
+ * The park, when it holds this registration back.
668
+ *
669
+ * `policy.onFailure = PARK` is a **runtime override of the document's
670
+ * enabled-ness**: the document still says ENABLED, and re-arming from it is
671
+ * what a restart does for every workflow it finds. So the park row is the
672
+ * authority, read on this lane, and it blocks every registration of the
673
+ * version that failed or an older one — a boot re-arm, an ERROR row's
674
+ * retry. A newer version is what a re-publish is: it is never blocked, and
675
+ * {@link enable} lifts the park it outlived. A re-enable lifts it through
676
+ * the disable before it.
677
+ */
678
+ private blockingPark;
679
+ /**
680
+ * An enable a park held back. The row is left as it stands, and a pending
681
+ * retry keeps its release flag, so the enable after the park lifts releases
682
+ * a failed attempt and arms afresh; the retry is only pushed back, so it
683
+ * does not take every tick's slot. A binding this replaced is restored, so
684
+ * nothing is released later with one that was never armed.
685
+ */
686
+ private holdParked;
687
+ /** The status an enable that succeeded writes: never ENABLED while a park
688
+ * stands, whatever ran meanwhile. The registration stays recorded. */
689
+ private armedStatus;
461
690
  private deferToStoredRetry;
462
691
  private releaseRegistration;
463
692
  private enableSchedule;
@@ -471,12 +700,21 @@ declare class TriggerSupervisor {
471
700
  private renew;
472
701
  private fireSchedule;
473
702
  private poll;
474
- private fireItem;
703
+ private fireItems;
704
+ private redeliver;
705
+ private failRefused;
475
706
  }
476
707
  //#endregion
477
708
  //#region src/reactor/service.d.ts
709
+ /** Why a firing was journaled CANCELLED without running, when it was. */
710
+ type FiringRefusal = "parked" | "singleton" | "stale" | "queue-full" | "expired";
478
711
  type PersistedRunResult = WorkflowRunResult & {
479
712
  runId: string | null;
713
+ refusal?: FiringRefusal;
714
+ };
715
+ type RunResume = {
716
+ completedSteps: Map<string, ReplayedStep>;
717
+ rerunOf: string;
480
718
  };
481
719
  interface ConnectionSummary {
482
720
  id: string;
@@ -538,9 +776,11 @@ interface WebhookEndpointRecord {
538
776
  export declare class WorkflowRuntimeService {
539
777
  private readonly host;
540
778
  private readonly logger;
779
+ private readonly telemetry;
541
780
  private readonly attachments?;
542
781
  private executor?;
543
782
  private pieceWorkers?;
783
+ private unobservePool?;
544
784
  private storePromise;
545
785
  private storeError?;
546
786
  private storeOpening;
@@ -571,7 +811,10 @@ export declare class WorkflowRuntimeService {
571
811
  private endpointCount;
572
812
  private hasWebhookEndpoints;
573
813
  private readonly registeredAs;
814
+ private readonly registrationChains;
815
+ private inRegistrationOrder;
574
816
  private updateRegistration;
817
+ private registerNow;
575
818
  private applyRegistration;
576
819
  private enableSupervised;
577
820
  private registerPieceTrigger;
@@ -611,6 +854,8 @@ export declare class WorkflowRuntimeService {
611
854
  private fireUnjournaled;
612
855
  private enqueueFire;
613
856
  private fireFromTrigger;
857
+ private journalFiring;
858
+ private startFiring;
614
859
  private readonly firedLifecycle;
615
860
  private readonly firedLifecycleQueue;
616
861
  private lifecycleAlreadyFired;
@@ -627,9 +872,13 @@ export declare class WorkflowRuntimeService {
627
872
  private matchDocumentLifecycle;
628
873
  private matchDriveLifecycle;
629
874
  private triggerSupervisor?;
875
+ private readonly parks;
630
876
  supervisor(): TriggerSupervisor;
877
+ private laneFailed;
631
878
  startTriggerSupervisor(): void;
632
879
  stopTriggerSupervisor(): void;
880
+ private closed;
881
+ private throwIfClosed;
633
882
  shutdown(): void;
634
883
  triggerStates(ctx?: WorkflowCaller): Promise<TriggerStateRow[]>;
635
884
  private webhookEndpoints?;
@@ -665,6 +914,7 @@ export declare class WorkflowRuntimeService {
665
914
  private designReactorAccess;
666
915
  private readonly descriptors;
667
916
  private designWorker?;
917
+ private createDesignWorker;
668
918
  private designEgress;
669
919
  private readonly describing;
670
920
  private pieceDescriptor;
@@ -672,6 +922,7 @@ export declare class WorkflowRuntimeService {
672
922
  driveWorkflowIds(driveId: string, ctx?: WorkflowCaller): Promise<string[]>;
673
923
  runs(args: RunsArgs, ctx?: WorkflowCaller): Promise<RunRecord[]>;
674
924
  runsPage(args: RunsPageArgs, ctx?: WorkflowCaller): Promise<RunPage>;
925
+ private listRunsPage;
675
926
  run(runId: string, ctx?: WorkflowCaller): Promise<RunRecord | null>;
676
927
  connections(ctx?: WorkflowCaller): Promise<ConnectionSummary[]>;
677
928
  checkConnection(connectionId: string, ctx?: WorkflowCaller): Promise<ConnectionCheckResult>;
@@ -698,7 +949,8 @@ export declare class WorkflowRuntimeService {
698
949
  pieceCatalog(): Promise<PieceSummary[]>;
699
950
  pieceActions(packageName: string, version?: string): Promise<PieceActionsResult>;
700
951
  pieceTriggers(packageName: string, version?: string): Promise<PieceTriggersResult>;
701
- searchBlocks(query: string, limit?: number): Promise<BlockSearchResult>;
952
+ warmPieceSearch(): void;
953
+ searchPieces(query: string, filter: PieceSearchFilter): Promise<PieceSearchResult>;
702
954
  pieceDetail(packageName: string, version?: string): Promise<unknown>;
703
955
  private localPieceAt;
704
956
  blockDescriptor(block: BlockRef): Promise<unknown>;
@@ -726,13 +978,43 @@ export declare class WorkflowRuntimeService {
726
978
  private noteLastTest;
727
979
  private blockExecutor;
728
980
  private workers;
729
- fire(workflowId: string, triggerPayload?: unknown, triggerKind?: string, resume?: {
730
- completedSteps: Map<string, {
731
- output?: unknown;
732
- port?: string | null;
733
- }>;
734
- rerunOf: string;
735
- }, ctx?: WorkflowCaller, enqueuedRunId?: string): Promise<PersistedRunResult>;
981
+ fire(workflowId: string, triggerPayload?: unknown, triggerKind?: string, resume?: RunResume, ctx?: WorkflowCaller, enqueuedRunId?: string): Promise<PersistedRunResult>;
982
+ private runFired;
983
+ private readonly runGate;
984
+ private readonly heldReplies;
985
+ /** Why a trigger's firing of a PARKED workflow is refused; undefined when
986
+ * it is not parked, or when an operator started the run. */
987
+ private parkedFiring;
988
+ /** Why a firing that waited for its slot may no longer run, if it may not. */
989
+ private staleAfterWait;
990
+ /** Whether the workflow is still ENABLED at this published version. An
991
+ * unreadable document counts as unchanged, so a failure still parks. */
992
+ private stillRunsVersion;
993
+ /** A park recorded against an earlier published version than this state's. */
994
+ private outdatedPark;
995
+ /**
996
+ * A firing SINGLETON refused.
997
+ *
998
+ * Journaled as a CANCELLED run rather than dropped: a firing that vanished
999
+ * is indistinguishable from a trigger that never fired, which is the class
1000
+ * of bug this work package exists to stamp out. An already-enqueued row is
1001
+ * closed out in place, so nothing is left PENDING for a sweep to find.
1002
+ */
1003
+ private refuseClosed;
1004
+ private skipFiring;
1005
+ /**
1006
+ * `policy.onFailure` for a run that failed terminally.
1007
+ *
1008
+ * PARK is the document model's own default, so this is where enforcing the
1009
+ * knob becomes visible: a terminal failure parks the workflow, whatever its
1010
+ * trigger kind, and nothing fires it until it is re-published or
1011
+ * re-enabled. That is what PARK means, and
1012
+ * leaving a broken workflow firing every minute is what it meant before.
1013
+ *
1014
+ * NOTIFY logs at error level, which is the only notification channel this
1015
+ * engine has; it is marked as such rather than pretending to page anyone.
1016
+ */
1017
+ private applyFailureMode;
736
1018
  rerun(runId: string, ctx?: WorkflowCaller): Promise<PersistedRunResult>;
737
1019
  private rereads;
738
1020
  testStep(workflowId: string, stepId: string, ctx?: WorkflowCaller, access?: WorkflowAccessOptions): Promise<StepTestResult>;
@@ -752,6 +1034,133 @@ export declare class InvalidRunCursorError extends Error {
752
1034
  constructor();
753
1035
  }
754
1036
  //#endregion
1037
+ //#region src/reactor/singleton-lease.d.ts
1038
+ /**
1039
+ * Names this process as the workflow singleton's owner.
1040
+ *
1041
+ * Set it to a STABLE name per deployment slot (`switchboard-0`, the
1042
+ * StatefulSet pod name, the Render service id). The owner name is the
1043
+ * operator's contract: a restart under the same name re-claims its own lease
1044
+ * once the old heartbeat is stale instead of waiting out
1045
+ * {@link SINGLETON_LEASE_TTL_MS}.
1046
+ *
1047
+ * Unset, the owner is derived from a STABLE identity — the hostname and a
1048
+ * fingerprint of the journal's own storage location ({@link
1049
+ * AcquireSingletonOptions.storageId}) — not from the pid and a random suffix.
1050
+ * A random per-process owner meant every unclean kill locked the next boot out
1051
+ * for the whole {@link SINGLETON_LEASE_TTL_MS}: the dead process's lease was
1052
+ * nobody's to re-claim, and `release()` never ran. One deployment slot
1053
+ * restarting is the common case and it has to be quick; a genuine second
1054
+ * replica still differs, by hostname or by the journal it points at.
1055
+ */
1056
+ export declare const WORKFLOW_SINGLETON_OWNER_ENV = "PH_WORKFLOWS_SINGLETON_OWNER";
1057
+ /** How long a claim stays valid without a heartbeat. */
1058
+ export declare const SINGLETON_LEASE_TTL_MS = 60000;
1059
+ /** How often the holder renews it; a third of the TTL, so two renewals may be
1060
+ * lost (a GC pause, a slow database) before anyone may take over. */
1061
+ export declare const SINGLETON_HEARTBEAT_MS: number;
1062
+ /**
1063
+ * How long the holder's heartbeat must have been silent before a claim under
1064
+ * the SAME owner name takes the lease over, short of its expiry. Two renewal
1065
+ * periods: a live holder renews well inside it, and its self-fence fires
1066
+ * before it passes.
1067
+ */
1068
+ export declare const SINGLETON_STALE_HEARTBEATS = 2;
1069
+ /** Another live process holds the singleton. The refusal is the point: a host
1070
+ * that cannot own workflow execution must not compose the engine. */
1071
+ export declare class WorkflowSingletonConflictError extends Error {
1072
+ readonly owner: string;
1073
+ readonly expiresAt: string;
1074
+ readonly wouldBe: string;
1075
+ constructor(owner: string, expiresAt: string, wouldBe: string);
1076
+ }
1077
+ /**
1078
+ * Why a holder stopped owning workflow execution.
1079
+ *
1080
+ * - `taken`: a renewal matched no row, so another claim holds the lease
1081
+ * (`heldBy` names it when the row still exists).
1082
+ * - `unrenewable`: no renewal landed for long enough that another claim could
1083
+ * take it over; none was seen to.
1084
+ */
1085
+ type WorkflowSingletonLoss = {
1086
+ reason: "taken";
1087
+ heldBy: string | undefined;
1088
+ } | {
1089
+ reason: "unrenewable";
1090
+ silentMs: number;
1091
+ };
1092
+ /** A held claim, renewed from the moment it is taken. The host releases it on
1093
+ * shutdown, so the next boot does not wait out the TTL. */
1094
+ interface WorkflowSingletonLease {
1095
+ readonly owner: string;
1096
+ /** Renews once; false when the lease is no longer ours. */
1097
+ heartbeat(): Promise<boolean>;
1098
+ /** Stops renewing and drops the row if it is still ours. */
1099
+ release(): Promise<void>;
1100
+ }
1101
+ interface AcquireSingletonOptions {
1102
+ relationalDb: IRelationalDb;
1103
+ logger?: ILogger;
1104
+ /** Defaults to {@link WORKFLOW_SINGLETON_OWNER_ENV}, then
1105
+ * `<hostname>/<storageId fingerprint>`. */
1106
+ owner?: string;
1107
+ /**
1108
+ * Where this host's journal lives — a Postgres URL, an absolute PGlite
1109
+ * directory — as the stable half of the default owner name. Hashed, so a
1110
+ * connection string's credentials never reach the lease row or a log line.
1111
+ *
1112
+ * It is what separates two hosts that share a hostname but not a journal,
1113
+ * and it is stable across restarts, which is the whole point.
1114
+ */
1115
+ storageId?: string;
1116
+ ttlMs?: number;
1117
+ heartbeatMs?: number;
1118
+ /** Called once, when this process stops owning workflow execution. */
1119
+ onLost?: (loss: WorkflowSingletonLoss) => void;
1120
+ /**
1121
+ * Whether a holder that cannot renew reports itself lost before anyone
1122
+ * could take over. On by default. Off for a journal no other process can
1123
+ * open (embedded PGlite): nothing can take the lease, so a stalled renewal
1124
+ * is only logged.
1125
+ */
1126
+ selfFence?: boolean;
1127
+ env?: Record<string, string | undefined>;
1128
+ }
1129
+ /**
1130
+ * The owner name this process claims under.
1131
+ *
1132
+ * `<hostname>/<storage fingerprint>`, so it is the same name on every boot of
1133
+ * one deployment slot — a restart re-claims its OWN lease once the dead
1134
+ * process's heartbeat is stale, rather than waiting out the TTL — and a different
1135
+ * name on any host or journal that is genuinely somebody else.
1136
+ *
1137
+ * The storage location is hashed, never printed: it can be a Postgres URL with
1138
+ * credentials in it, and the owner name goes into a database row an operator
1139
+ * reads and into every log line about the lease.
1140
+ *
1141
+ * The residual case a stable name cannot tell apart is two processes on ONE
1142
+ * host over ONE journal, which is a misconfiguration those two already share
1143
+ * (one read-model directory, one run journal). It is not silent: the loser's
1144
+ * heartbeat finds the lease taken and says so by name.
1145
+ */
1146
+ export declare function singletonOwnerName(env?: Record<string, string | undefined>, storageId?: string): string;
1147
+ /**
1148
+ * Claims the workflow singleton, or refuses.
1149
+ *
1150
+ * Three steps, each one a single statement whose own outcome is the claim — a
1151
+ * prior `SELECT` would be a race:
1152
+ *
1153
+ * 1. `INSERT … ON CONFLICT DO NOTHING RETURNING` — the first ever boot.
1154
+ * 2. `UPDATE … WHERE expires_at <= now OR (owner = me AND heartbeat stale)
1155
+ * RETURNING` — a dead lease taken over once it has expired, or our own
1156
+ * slot's lease once its holder stopped renewing (a restart under a stable
1157
+ * owner name), never a live holder's. Either way the row gets this claim's
1158
+ * instance, so the previous holder's heartbeat and release no longer
1159
+ * match.
1160
+ * 3. Neither matched: someone live holds it, and we refuse by name.
1161
+ */
1162
+ export declare function acquireWorkflowSingletonLease(options: AcquireSingletonOptions): Promise<WorkflowSingletonLease>;
1163
+ //#endregion
755
1164
  //#region src/reactor/run-user.d.ts
756
1165
  export declare function publishRunUser(client: Pick<IReactorClient, "getOperations">, workflowId: string, hostIdentity?: HostIdentity, signal?: AbortSignal): Promise<RunUser | null>;
757
1166
  //#endregion
@@ -19350,6 +19759,6 @@ interface WebhookPayload {
19350
19759
  body: unknown;
19351
19760
  }
19352
19761
  //#endregion
19353
- export { type AttachmentClientLike, type BlockResolutionRecord, CORE_PIECE_NAME, type ConnectionCheckResult, type ConnectionSummary, type HostIdentity, type OAuthAttemptStatus, type OAuthAttemptView, type OAuthStart, type OutputTree, type OutputTreeNode, type PersistedRunResult, PieceRegistry, type PieceStoreRow, type PieceTriggerBinding, type RunPage, type RunRecord, type RunRow, type RunsArgs, type RunsPageArgs, type ScheduleTriggerBinding, type StepExecutionRow, type StepTestResult, type TriggerBinding, type TriggerDedupeRow, type TriggerStateRow, type WebhookConfig, type WebhookPayload, type WorkflowAccessOptions, type WorkflowCaller, type WorkflowRuntimeDB, type WorkflowRuntimeHostDeps, packagePieces };
19762
+ export { type AcquireSingletonOptions, type AttachmentClientLike, type AttachmentReadRequest, type BlockResolutionRecord, CORE_PIECE_NAME, type ConnectionCheckResult, type ConnectionSummary, type HostIdentity, type OAuthAttemptStatus, type OAuthAttemptView, type OAuthStart, type OutputTree, type OutputTreeNode, type PersistedRunResult, PieceRegistry, type PieceStoreRow, type PieceTriggerBinding, type RunPage, type RunRecord, type RunRow, type RunsArgs, type RunsPageArgs, type ScheduleTriggerBinding, type StepExecutionRow, type StepTestResult, TELEMETRY_SCOPE, type TriggerBinding, type TriggerDedupeRow, type TriggerStateRow, type WebhookConfig, type WebhookPayload, type WorkflowAccessOptions, type WorkflowCaller, type WorkflowRuntimeDB, type WorkflowRuntimeHostDeps, type WorkflowSingletonLease, type WorkflowSingletonLoss, type WorkflowTelemetryOptions, packagePieces };
19354
19763
  export {};
19355
19764
  //# sourceMappingURL=index.d.ts.map