@task-master/cadence 0.0.0-stage → 0.2.0
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/LICENSE +21 -0
- package/README.md +276 -3
- package/dist/index.cjs +1957 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +717 -0
- package/dist/index.d.ts +717 -0
- package/dist/index.js +1882 -0
- package/dist/index.js.map +1 -0
- package/package.json +64 -6
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,717 @@
|
|
|
1
|
+
import { ObjectId, MongoClient, Db, Collection, ClientSession } from 'mongodb';
|
|
2
|
+
|
|
3
|
+
type Kind = 'scheduled' | 'adhoc' | 'repair';
|
|
4
|
+
type AdminState = 'active' | 'paused' | 'retired';
|
|
5
|
+
type ExecutionState = 'idle' | 'dispatching' | 'in_flight' | 'backoff' | 'quarantined' | 'blocked_unconfirmed';
|
|
6
|
+
/**
|
|
7
|
+
* `blocked` is nonterminal: it records no outcome and holds the reservation.
|
|
8
|
+
* The five terminal states are the only values `finalize()` may write.
|
|
9
|
+
*/
|
|
10
|
+
type RunState = 'dispatch_pending' | 'submitted' | 'in_progress' | 'blocked' | 'succeeded' | 'succeeded_empty' | 'partial' | 'failed' | 'terminated_confirmed';
|
|
11
|
+
type Publication = 'pending' | 'published' | 'awaiting_resolution' | 'failed';
|
|
12
|
+
type ExecutionStatus = 'not_started' | 'running' | 'finished' | 'crashed';
|
|
13
|
+
type VendorSubmission = 'none' | 'claimed' | 'intent_recorded' | 'confirmed' | 'unknown';
|
|
14
|
+
type Reservation = 'held' | 'active' | 'released';
|
|
15
|
+
type RequestState = 'open' | 'satisfied' | 'satisfied_with_repair' | 'failed' | 'blocked' | 'cancelled';
|
|
16
|
+
interface Interval {
|
|
17
|
+
from: Date;
|
|
18
|
+
to: Date;
|
|
19
|
+
}
|
|
20
|
+
type WindowDomain = 'modification_time' | 'business_date';
|
|
21
|
+
interface Window {
|
|
22
|
+
from: Date;
|
|
23
|
+
to: Date | null;
|
|
24
|
+
domain: WindowDomain;
|
|
25
|
+
}
|
|
26
|
+
type TrafficOp = 'kickoff' | 'poll' | 'download';
|
|
27
|
+
interface TrafficRule {
|
|
28
|
+
id: string;
|
|
29
|
+
effect: 'deny' | 'allow';
|
|
30
|
+
/** 0 = Sunday, in the policy timezone. */
|
|
31
|
+
days: number[];
|
|
32
|
+
/** Local wall time 'HH:MM'. `to <= from` means the interval spans midnight. */
|
|
33
|
+
from: string;
|
|
34
|
+
to: string;
|
|
35
|
+
appliesTo: 'all' | TrafficOp;
|
|
36
|
+
}
|
|
37
|
+
interface TrafficPolicy {
|
|
38
|
+
version: number;
|
|
39
|
+
/** IANA zone name. Never a fixed offset: a stored offset shifts twice a year. */
|
|
40
|
+
timezone: string;
|
|
41
|
+
enforcement: 'kickoff_only' | 'all_vendor_traffic' | 'throughput_only';
|
|
42
|
+
rules: TrafficRule[];
|
|
43
|
+
minRemainingWindowMs: number;
|
|
44
|
+
resumeJitterMs: number;
|
|
45
|
+
}
|
|
46
|
+
interface Suspension {
|
|
47
|
+
id: string;
|
|
48
|
+
from: Date;
|
|
49
|
+
/** null = indefinite. */
|
|
50
|
+
until: Date | null;
|
|
51
|
+
appliesTo: 'all' | 'scheduled';
|
|
52
|
+
reason: string;
|
|
53
|
+
requestedBy: string;
|
|
54
|
+
}
|
|
55
|
+
interface Availability {
|
|
56
|
+
/** When new work may begin being dispatched. */
|
|
57
|
+
dispatchFrom: Date | null;
|
|
58
|
+
/** When new work must stop being dispatched. */
|
|
59
|
+
dispatchUntil: Date | null;
|
|
60
|
+
/** Lower bound of the data to acquire. Not the same question as dispatchFrom. */
|
|
61
|
+
dataFrom: Date | null;
|
|
62
|
+
/** Upper bound of the data to acquire. */
|
|
63
|
+
dataUntil: Date | null;
|
|
64
|
+
/** Whether scheduled work may still run past dispatchUntil to close an incomplete tail. */
|
|
65
|
+
allowFinalCatchUp: boolean;
|
|
66
|
+
suspensions: Suspension[];
|
|
67
|
+
}
|
|
68
|
+
interface AttentionEpisode {
|
|
69
|
+
episodeId: string;
|
|
70
|
+
reason: string;
|
|
71
|
+
since: Date;
|
|
72
|
+
detail?: string;
|
|
73
|
+
}
|
|
74
|
+
interface UnitCounters {
|
|
75
|
+
consecutiveFailures: number;
|
|
76
|
+
emptyStreak: number;
|
|
77
|
+
totalRuns: number;
|
|
78
|
+
}
|
|
79
|
+
interface Unit {
|
|
80
|
+
_id: string;
|
|
81
|
+
integrationId: string;
|
|
82
|
+
adminState: AdminState;
|
|
83
|
+
executionState: ExecutionState;
|
|
84
|
+
availability: Availability;
|
|
85
|
+
watermark: {
|
|
86
|
+
scheduledThrough: Date | null;
|
|
87
|
+
basis: string | null;
|
|
88
|
+
seeded: boolean;
|
|
89
|
+
updatedAt: Date | null;
|
|
90
|
+
};
|
|
91
|
+
counters: Record<Kind, UnitCounters>;
|
|
92
|
+
cadenceMs: number;
|
|
93
|
+
/** Pure cadence, written only by the finalizer. */
|
|
94
|
+
scheduledCadenceAt: Date;
|
|
95
|
+
/** Derived index hint. Recomputed whenever availability or traffic policy changes. */
|
|
96
|
+
scheduledNextEligibleAt: Date;
|
|
97
|
+
activeRunId: string | null;
|
|
98
|
+
lastScheduledRunId: string | null;
|
|
99
|
+
lastAdhocRunId: string | null;
|
|
100
|
+
lastRepairRunId: string | null;
|
|
101
|
+
/** An array: a single field cannot hold three concurrent episodes. */
|
|
102
|
+
attention: AttentionEpisode[];
|
|
103
|
+
}
|
|
104
|
+
type SideEffectClass = 'idempotent_acquisition' | 'idempotent_effect' | 'at_most_once_effect';
|
|
105
|
+
interface IntegrationPolicy {
|
|
106
|
+
defaultSince: Date;
|
|
107
|
+
overlapBufferMs: number;
|
|
108
|
+
maxCatchUpWindowMs: number;
|
|
109
|
+
failureThreshold: number;
|
|
110
|
+
emptyStreakThreshold: number;
|
|
111
|
+
backoffBaseMs: number;
|
|
112
|
+
backoffMaxMs: number;
|
|
113
|
+
maxAttempts: number;
|
|
114
|
+
partialPolicy: 'hold' | 'advance_with_repair';
|
|
115
|
+
}
|
|
116
|
+
interface CapabilityProfile {
|
|
117
|
+
/** Requires behaviour verification before use; a clean lenient probe is not proof. */
|
|
118
|
+
until: boolean;
|
|
119
|
+
typeFilter: boolean;
|
|
120
|
+
patient: boolean;
|
|
121
|
+
}
|
|
122
|
+
interface Integration {
|
|
123
|
+
_id: string;
|
|
124
|
+
/** Cooldown is scoped here, not to a unit: a 429 is a statement about the endpoint. */
|
|
125
|
+
quotaKey: string;
|
|
126
|
+
capacity: {
|
|
127
|
+
budget: number;
|
|
128
|
+
reserved: number;
|
|
129
|
+
active: number;
|
|
130
|
+
};
|
|
131
|
+
trafficPolicy: TrafficPolicy;
|
|
132
|
+
vendorCooldownUntil: Date | null;
|
|
133
|
+
profile: CapabilityProfile;
|
|
134
|
+
sideEffectClass: SideEffectClass;
|
|
135
|
+
sideEffectClassVerifiedBy: string;
|
|
136
|
+
policy: IntegrationPolicy;
|
|
137
|
+
}
|
|
138
|
+
interface AcquisitionScope {
|
|
139
|
+
resourceTypes: string[];
|
|
140
|
+
/** Executable filter expressions, not only the hash that identifies them. */
|
|
141
|
+
typeFilters: string[];
|
|
142
|
+
typeFilterHash: string;
|
|
143
|
+
patients: string[] | null;
|
|
144
|
+
}
|
|
145
|
+
interface OperatorGrant {
|
|
146
|
+
grantedBy: string;
|
|
147
|
+
grantedAt: Date;
|
|
148
|
+
reason: string;
|
|
149
|
+
extraAttempts: number;
|
|
150
|
+
overridesBackoff: boolean;
|
|
151
|
+
/** The run this authorization was filed against. Rechecked inside admission. */
|
|
152
|
+
appliesToRunId: string | null;
|
|
153
|
+
consumedAt: Date | null;
|
|
154
|
+
}
|
|
155
|
+
interface RequestDoc {
|
|
156
|
+
_id: ObjectId;
|
|
157
|
+
/** Null once the request closes, so the partial unique index stops applying. */
|
|
158
|
+
dedupFingerprint: string | null;
|
|
159
|
+
integrationId: string;
|
|
160
|
+
unitKey: string;
|
|
161
|
+
kind: Kind;
|
|
162
|
+
window: Window;
|
|
163
|
+
scope: AcquisitionScope;
|
|
164
|
+
state: RequestState;
|
|
165
|
+
isOpen: boolean;
|
|
166
|
+
attemptCounter: number;
|
|
167
|
+
maxAttempts: number;
|
|
168
|
+
nextAttemptAt: Date;
|
|
169
|
+
activeRunId: string | null;
|
|
170
|
+
lastRunId: string | null;
|
|
171
|
+
operatorGrant: OperatorGrant | null;
|
|
172
|
+
/** The repair obligation this request was raised to discharge, if any. */
|
|
173
|
+
repairId: ObjectId | null;
|
|
174
|
+
createdAt: Date;
|
|
175
|
+
updatedAt: Date;
|
|
176
|
+
}
|
|
177
|
+
/**
|
|
178
|
+
* Written at admission. Everything read later by `advanceMarker` lives here or on
|
|
179
|
+
* the unit loaded inside the finalization transaction — never on a field nothing writes.
|
|
180
|
+
*/
|
|
181
|
+
interface AdmissionSnapshot {
|
|
182
|
+
dispatchUntil: Date | null;
|
|
183
|
+
dataUntil: Date | null;
|
|
184
|
+
priorMarker: Date | null;
|
|
185
|
+
trafficPolicyVersion: number;
|
|
186
|
+
sideEffectClass: SideEffectClass;
|
|
187
|
+
sideEffectClassVerifiedBy: string;
|
|
188
|
+
}
|
|
189
|
+
interface StallState {
|
|
190
|
+
count: number;
|
|
191
|
+
since: Date | null;
|
|
192
|
+
/** Operations currently denied. The stall closes only when this empties. */
|
|
193
|
+
blockedOps: string[];
|
|
194
|
+
/** Closed intervals, so a deadline can intersect rather than subtract a lifetime total. */
|
|
195
|
+
intervals: Interval[];
|
|
196
|
+
}
|
|
197
|
+
type ManifestEntryState = 'pending' | 'claimed' | 'done' | 'failed';
|
|
198
|
+
interface ManifestEntry {
|
|
199
|
+
id: string;
|
|
200
|
+
resourceType: string;
|
|
201
|
+
url: string;
|
|
202
|
+
count: number | null;
|
|
203
|
+
state: ManifestEntryState;
|
|
204
|
+
claimedBy: string | null;
|
|
205
|
+
claimExpiresAt: Date | null;
|
|
206
|
+
attempts: number;
|
|
207
|
+
bytes: number | null;
|
|
208
|
+
}
|
|
209
|
+
interface Manifest {
|
|
210
|
+
transactionTime: Date;
|
|
211
|
+
entries: ManifestEntry[];
|
|
212
|
+
/**
|
|
213
|
+
* Only the vendor can report partial *coverage*, because only it knows which part of
|
|
214
|
+
* the window it actually searched. A file we failed to download is not this.
|
|
215
|
+
*/
|
|
216
|
+
partial: {
|
|
217
|
+
verifiedThrough: Date;
|
|
218
|
+
failedFrom: Date;
|
|
219
|
+
failedTo: Date;
|
|
220
|
+
} | null;
|
|
221
|
+
}
|
|
222
|
+
interface RunDoc {
|
|
223
|
+
_id: string;
|
|
224
|
+
requestId: ObjectId;
|
|
225
|
+
integrationId: string;
|
|
226
|
+
unitKey: string;
|
|
227
|
+
kind: Kind;
|
|
228
|
+
attemptNumber: number;
|
|
229
|
+
window: Window;
|
|
230
|
+
scope: AcquisitionScope;
|
|
231
|
+
state: RunState;
|
|
232
|
+
publication: Publication;
|
|
233
|
+
execution: ExecutionStatus;
|
|
234
|
+
vendorSubmission: VendorSubmission;
|
|
235
|
+
reservation: Reservation;
|
|
236
|
+
admittedAt: Date;
|
|
237
|
+
publishedAt: Date | null;
|
|
238
|
+
taskId: string | null;
|
|
239
|
+
appliedAt: Date | null;
|
|
240
|
+
completedAt: Date | null;
|
|
241
|
+
outcome: TerminalOutcome | null;
|
|
242
|
+
blocked: {
|
|
243
|
+
reason: BlockReason;
|
|
244
|
+
since: Date;
|
|
245
|
+
evidenceNeeded: string;
|
|
246
|
+
} | null;
|
|
247
|
+
stall: StallState;
|
|
248
|
+
counterSnapshot: {
|
|
249
|
+
consecutiveFailures: number;
|
|
250
|
+
emptyStreak: number;
|
|
251
|
+
};
|
|
252
|
+
admissionSnapshot: AdmissionSnapshot;
|
|
253
|
+
executionOwner: string | null;
|
|
254
|
+
executionToken: string | null;
|
|
255
|
+
executionClaimExpiresAt: Date | null;
|
|
256
|
+
submissionAttempts: number;
|
|
257
|
+
vendorJobRef: string | null;
|
|
258
|
+
pollingLocation: string | null;
|
|
259
|
+
/** The vendor's clock, not ours: our stalls do not extend it. */
|
|
260
|
+
pollingExpiresAt: Date | null;
|
|
261
|
+
polledAt: Date | null;
|
|
262
|
+
manifest: Manifest | null;
|
|
263
|
+
/** Evidence from a worker whose claim expired: recorded, never treated as ownership. */
|
|
264
|
+
orphanedSubmissions: {
|
|
265
|
+
jobRef: string;
|
|
266
|
+
at: Date;
|
|
267
|
+
by: string;
|
|
268
|
+
}[];
|
|
269
|
+
lastProgressAt: Date;
|
|
270
|
+
/** The last progress the vendor reported, so a repeated poll is not mistaken for progress. */
|
|
271
|
+
lastProgressNote: string | null;
|
|
272
|
+
}
|
|
273
|
+
type FailureClass = 'transient_transport' | 'throttled' | 'auth' | 'invalid_config' | 'invalid_manifest' | 'vendor_error';
|
|
274
|
+
interface Failure {
|
|
275
|
+
class: FailureClass;
|
|
276
|
+
message: string;
|
|
277
|
+
retryAfterMs?: number;
|
|
278
|
+
}
|
|
279
|
+
/**
|
|
280
|
+
* Discriminated union, so a missing branch in `finalize()` is a compile error rather
|
|
281
|
+
* than a silent fall-through past the switch.
|
|
282
|
+
*/
|
|
283
|
+
type TerminalOutcome = {
|
|
284
|
+
kind: 'succeeded';
|
|
285
|
+
transactionTime: Date;
|
|
286
|
+
verifiedBusinessDateThrough?: Date;
|
|
287
|
+
} | {
|
|
288
|
+
kind: 'succeeded_empty';
|
|
289
|
+
transactionTime: Date;
|
|
290
|
+
} | {
|
|
291
|
+
kind: 'partial';
|
|
292
|
+
transactionTime: Date;
|
|
293
|
+
verifiedPortion: Interval;
|
|
294
|
+
failedPortion: Interval;
|
|
295
|
+
} | {
|
|
296
|
+
kind: 'failed';
|
|
297
|
+
failure: Failure;
|
|
298
|
+
} | {
|
|
299
|
+
kind: 'terminated_confirmed';
|
|
300
|
+
};
|
|
301
|
+
type TerminalOutcomeKind = TerminalOutcome['kind'];
|
|
302
|
+
type BlockReason = 'unconfirmed_termination' | 'unresolved_submission' | 'needs_investigation';
|
|
303
|
+
interface OutboxDoc {
|
|
304
|
+
_id: ObjectId;
|
|
305
|
+
runId: string;
|
|
306
|
+
integrationId: string;
|
|
307
|
+
payload: {
|
|
308
|
+
runId: string;
|
|
309
|
+
unitKey: string;
|
|
310
|
+
kind: Kind;
|
|
311
|
+
};
|
|
312
|
+
state: 'pending' | 'publishing' | 'published' | 'awaiting_resolution' | 'failed';
|
|
313
|
+
nextAttemptAt: Date;
|
|
314
|
+
claimToken: string | null;
|
|
315
|
+
claimedBy: string | null;
|
|
316
|
+
claimedAt: Date | null;
|
|
317
|
+
claimExpiresAt: Date | null;
|
|
318
|
+
}
|
|
319
|
+
interface CoverageDoc {
|
|
320
|
+
_id: ObjectId;
|
|
321
|
+
unitKey: string;
|
|
322
|
+
runId: string;
|
|
323
|
+
kind: Kind;
|
|
324
|
+
interval: Interval;
|
|
325
|
+
scope: AcquisitionScope;
|
|
326
|
+
}
|
|
327
|
+
interface RepairDoc {
|
|
328
|
+
_id: ObjectId;
|
|
329
|
+
integrationId: string;
|
|
330
|
+
unitKey: string;
|
|
331
|
+
interval: Interval;
|
|
332
|
+
scope: AcquisitionScope;
|
|
333
|
+
cause: 'partial_export' | 'catch_up_overflow' | 'dispatch_window_closed';
|
|
334
|
+
state: 'open' | 'resolved' | 'accepted';
|
|
335
|
+
createdAt: Date;
|
|
336
|
+
}
|
|
337
|
+
|
|
338
|
+
declare const DEFAULTS: {
|
|
339
|
+
/** How long a publisher may hold an outbox entry before reclamation. */
|
|
340
|
+
readonly outboxClaimTtlMs: 60000;
|
|
341
|
+
/** How long a worker may hold a submission claim before reconciliation resolves it. */
|
|
342
|
+
readonly submissionClaimTtlMs: 600000;
|
|
343
|
+
/** No observable progress for this long makes a run a candidate for termination. */
|
|
344
|
+
readonly noProgressDeadlineMs: 3600000;
|
|
345
|
+
};
|
|
346
|
+
declare function defaultIntegrationPolicy(overrides?: Partial<IntegrationPolicy>): IntegrationPolicy;
|
|
347
|
+
declare function defaultTrafficPolicy(overrides?: Partial<TrafficPolicy>): TrafficPolicy;
|
|
348
|
+
|
|
349
|
+
interface Cadence {
|
|
350
|
+
client: MongoClient;
|
|
351
|
+
db: Db;
|
|
352
|
+
integrations: Collection<Integration>;
|
|
353
|
+
units: Collection<Unit>;
|
|
354
|
+
requests: Collection<RequestDoc>;
|
|
355
|
+
runs: Collection<RunDoc>;
|
|
356
|
+
outbox: Collection<OutboxDoc>;
|
|
357
|
+
coverage: Collection<CoverageDoc>;
|
|
358
|
+
repairs: Collection<RepairDoc>;
|
|
359
|
+
}
|
|
360
|
+
declare function connect(uri: string, dbName: string): Promise<Cadence>;
|
|
361
|
+
declare function ensureIndexes(c: Cadence): Promise<void>;
|
|
362
|
+
|
|
363
|
+
declare class ProgrammingError extends Error {
|
|
364
|
+
}
|
|
365
|
+
/**
|
|
366
|
+
* The allowlist. `finalize()` tests membership rather than rejecting two known
|
|
367
|
+
* uncertainty values, so an unsupported outcome cannot reach the application steps.
|
|
368
|
+
*/
|
|
369
|
+
declare const TERMINAL_OUTCOME_KINDS: readonly ["succeeded", "succeeded_empty", "partial", "failed", "terminated_confirmed"];
|
|
370
|
+
declare function assertTerminal(outcome: {
|
|
371
|
+
kind: string;
|
|
372
|
+
}): asserts outcome is TerminalOutcome;
|
|
373
|
+
/** The run state a terminal outcome persists. Total over the union. */
|
|
374
|
+
declare function terminalRunState(kind: TerminalOutcomeKind): RunState;
|
|
375
|
+
interface RequestDisposition {
|
|
376
|
+
state: RequestState;
|
|
377
|
+
isOpen: boolean;
|
|
378
|
+
}
|
|
379
|
+
declare function requestDispositionFor(outcome: TerminalOutcome, opts: {
|
|
380
|
+
safe: boolean;
|
|
381
|
+
attemptsRemaining: boolean;
|
|
382
|
+
}): RequestDisposition;
|
|
383
|
+
declare function isRepetitionSafe(cls: string): boolean;
|
|
384
|
+
declare function countsTowardQuarantine(cls: string): boolean;
|
|
385
|
+
|
|
386
|
+
declare function runId(requestId: string, attemptNumber: number): string;
|
|
387
|
+
|
|
388
|
+
type Admissibility = {
|
|
389
|
+
admissible: true;
|
|
390
|
+
} | {
|
|
391
|
+
admissible: false;
|
|
392
|
+
reason: AdmissibilityReason;
|
|
393
|
+
until: Date | null;
|
|
394
|
+
};
|
|
395
|
+
type AdmissibilityReason = 'admin_state' | 'vendor_cooldown' | 'before_dispatch_from' | 'after_dispatch_until' | 'unit_complete' | 'suspended' | 'vendor_traffic_window' | 'insufficient_remaining_window';
|
|
396
|
+
/**
|
|
397
|
+
* Pure, per kind. Re-evaluated inside the admission transaction; the stored
|
|
398
|
+
* `scheduledNextEligibleAt` is only an index hint.
|
|
399
|
+
*/
|
|
400
|
+
declare function admissibility(unit: Unit, integration: Integration, now: Date, kind: Kind): Admissibility;
|
|
401
|
+
|
|
402
|
+
interface WindowPlan {
|
|
403
|
+
window: Window;
|
|
404
|
+
/** True when the catch-up cap was applied. */
|
|
405
|
+
capped: boolean;
|
|
406
|
+
/**
|
|
407
|
+
* True when a cap was needed but cannot be expressed to the vendor. Splitting our
|
|
408
|
+
* bookkeeping does not shrink the export the server will produce: without a verified
|
|
409
|
+
* upper bound the kickoff still carries only `_since`. Bounded sizing is unavailable
|
|
410
|
+
* and the oversized export is an accepted, visible risk.
|
|
411
|
+
*/
|
|
412
|
+
capUnenforceable: boolean;
|
|
413
|
+
/**
|
|
414
|
+
* The part this window stops short of. It is **not** a repair obligation: the marker
|
|
415
|
+
* only advances to the capped boundary, so the next scheduled window resumes exactly
|
|
416
|
+
* here. Filing a repair for it would double-book work the cadence already owes.
|
|
417
|
+
*/
|
|
418
|
+
deferred: {
|
|
419
|
+
from: Date;
|
|
420
|
+
to: Date;
|
|
421
|
+
} | null;
|
|
422
|
+
}
|
|
423
|
+
declare function computeWindow(unit: Unit, integration: Integration, now: Date): WindowPlan;
|
|
424
|
+
|
|
425
|
+
interface TrafficState {
|
|
426
|
+
denied: boolean;
|
|
427
|
+
/** When the current denial lifts. Null when not denied. */
|
|
428
|
+
opensAt: Date | null;
|
|
429
|
+
/** Time until the next denial begins. Infinity when none is scheduled. */
|
|
430
|
+
remainingMs: number;
|
|
431
|
+
}
|
|
432
|
+
declare function trafficStateAt(policy: TrafficPolicy, now: Date, op: TrafficOp): TrafficState;
|
|
433
|
+
|
|
434
|
+
/** The unit's data tail is closed when the marker has reached the data boundary. */
|
|
435
|
+
declare function isUnitComplete(unit: Unit): boolean;
|
|
436
|
+
|
|
437
|
+
interface Proposal {
|
|
438
|
+
integrationId: string;
|
|
439
|
+
unitKey: string;
|
|
440
|
+
kind: Kind;
|
|
441
|
+
window: Window;
|
|
442
|
+
scope: AcquisitionScope;
|
|
443
|
+
/** Set when an existing open request is being retried rather than a new one created. */
|
|
444
|
+
reuseRequestId: ObjectId | null;
|
|
445
|
+
/** True when the operator grant on the reused request will be consumed at admission. */
|
|
446
|
+
consumesGrant: boolean;
|
|
447
|
+
effectiveBudget: number;
|
|
448
|
+
capUnenforceable: boolean;
|
|
449
|
+
deferred: {
|
|
450
|
+
from: Date;
|
|
451
|
+
to: Date;
|
|
452
|
+
} | null;
|
|
453
|
+
/** The repair obligation this proposal discharges, if any. */
|
|
454
|
+
repairId: ObjectId | null;
|
|
455
|
+
}
|
|
456
|
+
interface PlanDiagnostics {
|
|
457
|
+
unitKey: string;
|
|
458
|
+
reason: string;
|
|
459
|
+
}
|
|
460
|
+
interface PlanResult {
|
|
461
|
+
proposals: Proposal[];
|
|
462
|
+
skipped: PlanDiagnostics[];
|
|
463
|
+
}
|
|
464
|
+
/**
|
|
465
|
+
* A grant is live only while it is unconsumed **and** still bound to the run it was
|
|
466
|
+
* filed against. `againstRunId` is explicit because the finalizer asks about the run it
|
|
467
|
+
* is applying, while the planner asks about the last run that closed.
|
|
468
|
+
*/
|
|
469
|
+
declare function grantIsLive(request: RequestDoc, againstRunId?: string | null): boolean;
|
|
470
|
+
/** Attempt budget including a live operator grant. */
|
|
471
|
+
declare function attemptBudget(request: RequestDoc, againstRunId?: string | null): number;
|
|
472
|
+
/** Pure of writes. Reads only; `admit()` re-asserts everything decided here. */
|
|
473
|
+
declare function plan(c: Cadence, integrationId: string, now: Date): Promise<PlanResult>;
|
|
474
|
+
|
|
475
|
+
type AdmitResult = {
|
|
476
|
+
admitted: true;
|
|
477
|
+
runId: string;
|
|
478
|
+
requestId: ObjectId;
|
|
479
|
+
attemptNumber: number;
|
|
480
|
+
} | {
|
|
481
|
+
admitted: false;
|
|
482
|
+
reason: string;
|
|
483
|
+
};
|
|
484
|
+
declare function admit(c: Cadence, p: Proposal, now: Date): Promise<AdmitResult>;
|
|
485
|
+
declare function backoffMs(attempt: number, integration: Integration): number;
|
|
486
|
+
|
|
487
|
+
declare class EnqueueUncertain extends Error {
|
|
488
|
+
readonly cadenceCode = "cadence/enqueue_uncertain";
|
|
489
|
+
}
|
|
490
|
+
declare class EnqueueRejected extends Error {
|
|
491
|
+
readonly cadenceCode = "cadence/enqueue_rejected";
|
|
492
|
+
}
|
|
493
|
+
declare const isEnqueueRejected: (e: unknown) => e is EnqueueRejected;
|
|
494
|
+
declare const isEnqueueUncertain: (e: unknown) => e is EnqueueUncertain;
|
|
495
|
+
interface Queue {
|
|
496
|
+
enqueue(payload: OutboxDoc['payload'], opts: {
|
|
497
|
+
idempotencyKey: string;
|
|
498
|
+
}): Promise<{
|
|
499
|
+
taskId: string;
|
|
500
|
+
}>;
|
|
501
|
+
}
|
|
502
|
+
interface PublishOptions {
|
|
503
|
+
instanceId: string;
|
|
504
|
+
claimTtlMs: number;
|
|
505
|
+
}
|
|
506
|
+
type PublishResult = {
|
|
507
|
+
published: true;
|
|
508
|
+
runId: string;
|
|
509
|
+
taskId: string;
|
|
510
|
+
} | {
|
|
511
|
+
published: false;
|
|
512
|
+
reason: 'nothing_pending' | 'claim_lost' | 'rejected' | 'uncertain';
|
|
513
|
+
};
|
|
514
|
+
/**
|
|
515
|
+
* Moving the reservation is idempotent and guarded on the run's own reservation state,
|
|
516
|
+
* so whichever of the publisher and the worker arrives first performs it exactly once.
|
|
517
|
+
*/
|
|
518
|
+
declare function activateReservation(c: Cadence, runId: string, integrationId: string, session?: ClientSession): Promise<boolean>;
|
|
519
|
+
declare function publishOutbox(c: Cadence, queue: Queue, now: Date, opts: PublishOptions): Promise<PublishResult>;
|
|
520
|
+
|
|
521
|
+
interface Vendor {
|
|
522
|
+
kickoff(run: RunDoc): Promise<{
|
|
523
|
+
jobRef: string;
|
|
524
|
+
contentLocation: string;
|
|
525
|
+
}>;
|
|
526
|
+
findByClientRequestId?(runId: string): Promise<{
|
|
527
|
+
jobRef: string;
|
|
528
|
+
contentLocation: string;
|
|
529
|
+
} | null>;
|
|
530
|
+
}
|
|
531
|
+
interface WorkerOptions {
|
|
532
|
+
workerId: string;
|
|
533
|
+
claimTtlMs: number;
|
|
534
|
+
}
|
|
535
|
+
type SubmitResult = {
|
|
536
|
+
status: 'submitted';
|
|
537
|
+
jobRef: string;
|
|
538
|
+
} | {
|
|
539
|
+
status: 'already_confirmed';
|
|
540
|
+
} | {
|
|
541
|
+
status: 'not_owner';
|
|
542
|
+
} | {
|
|
543
|
+
status: 'escalated';
|
|
544
|
+
reason: string;
|
|
545
|
+
} | {
|
|
546
|
+
status: 'deferred';
|
|
547
|
+
reason: string;
|
|
548
|
+
retryAt: Date | null;
|
|
549
|
+
} | {
|
|
550
|
+
status: 'claim_lost';
|
|
551
|
+
contacted: boolean;
|
|
552
|
+
} | {
|
|
553
|
+
status: 'orphaned';
|
|
554
|
+
jobRef: string;
|
|
555
|
+
};
|
|
556
|
+
declare function submitKickoff(c: Cadence, vendor: Vendor, integration: Integration, runId: string, now: Date, opts: WorkerOptions): Promise<SubmitResult>;
|
|
557
|
+
/** A claim never returns to `none` once intent was recorded: the vendor may have been reached. */
|
|
558
|
+
declare function markUnknown(c: Cadence, runId: string): Promise<void>;
|
|
559
|
+
/** Test and reconciliation helper: expire a submission claim without touching the vendor. */
|
|
560
|
+
declare function expireSubmissionClaim(c: Cadence, runId: string, at: Date): Promise<void>;
|
|
561
|
+
|
|
562
|
+
interface PollEntry {
|
|
563
|
+
resourceType: string;
|
|
564
|
+
url: string;
|
|
565
|
+
count: number | null;
|
|
566
|
+
}
|
|
567
|
+
type PollOutcome = {
|
|
568
|
+
status: 'accepted';
|
|
569
|
+
progress?: string;
|
|
570
|
+
expiresAt?: Date;
|
|
571
|
+
} | {
|
|
572
|
+
status: 'complete';
|
|
573
|
+
transactionTime: Date;
|
|
574
|
+
entries: PollEntry[];
|
|
575
|
+
/** Vendor-reported coverage gap. Only the vendor can report this. */
|
|
576
|
+
partial?: {
|
|
577
|
+
verifiedThrough: Date;
|
|
578
|
+
failedFrom: Date;
|
|
579
|
+
failedTo: Date;
|
|
580
|
+
};
|
|
581
|
+
} | {
|
|
582
|
+
status: 'throttled';
|
|
583
|
+
retryAfterMs: number;
|
|
584
|
+
} | {
|
|
585
|
+
status: 'expired';
|
|
586
|
+
} | {
|
|
587
|
+
status: 'failed';
|
|
588
|
+
failure: Failure;
|
|
589
|
+
};
|
|
590
|
+
interface PollingVendor {
|
|
591
|
+
poll(run: RunDoc): Promise<PollOutcome>;
|
|
592
|
+
}
|
|
593
|
+
interface FileSink {
|
|
594
|
+
fetch(entry: ManifestEntry, run: RunDoc): Promise<{
|
|
595
|
+
bytes: number;
|
|
596
|
+
count: number;
|
|
597
|
+
}>;
|
|
598
|
+
}
|
|
599
|
+
interface ExecuteOptions {
|
|
600
|
+
workerId: string;
|
|
601
|
+
entryClaimTtlMs: number;
|
|
602
|
+
}
|
|
603
|
+
type PollStep = {
|
|
604
|
+
status: 'working';
|
|
605
|
+
} | {
|
|
606
|
+
status: 'manifest_ready';
|
|
607
|
+
entries: number;
|
|
608
|
+
} | {
|
|
609
|
+
status: 'deferred';
|
|
610
|
+
reason: string;
|
|
611
|
+
retryAt: Date | null;
|
|
612
|
+
} | {
|
|
613
|
+
status: 'not_pollable';
|
|
614
|
+
} | {
|
|
615
|
+
status: 'terminal';
|
|
616
|
+
outcome: TerminalOutcome;
|
|
617
|
+
};
|
|
618
|
+
declare function pollRun(c: Cadence, vendor: PollingVendor, integration: Integration, runId: string, now: Date, opts: ExecuteOptions): Promise<PollStep>;
|
|
619
|
+
type DownloadStep = {
|
|
620
|
+
status: 'downloaded';
|
|
621
|
+
entryId: string;
|
|
622
|
+
} | {
|
|
623
|
+
status: 'entry_failed';
|
|
624
|
+
entryId: string;
|
|
625
|
+
message: string;
|
|
626
|
+
} | {
|
|
627
|
+
status: 'nothing_claimable';
|
|
628
|
+
} | {
|
|
629
|
+
status: 'deferred';
|
|
630
|
+
reason: string;
|
|
631
|
+
retryAt: Date | null;
|
|
632
|
+
};
|
|
633
|
+
declare function downloadNext(c: Cadence, sink: FileSink, integration: Integration, runId: string, now: Date, opts: ExecuteOptions): Promise<DownloadStep>;
|
|
634
|
+
/**
|
|
635
|
+
* Null while any entry is still outstanding.
|
|
636
|
+
*
|
|
637
|
+
* A file we failed to download is deliberately *not* reported as `partial`. `partial`
|
|
638
|
+
* carries time intervals, and a per-file failure says nothing about which part of the
|
|
639
|
+
* window was covered — it is a failed attempt at the whole window, retryable against
|
|
640
|
+
* the same request. Only a vendor-reported coverage gap produces `partial`.
|
|
641
|
+
*/
|
|
642
|
+
declare function completionOutcome(run: RunDoc): TerminalOutcome | null;
|
|
643
|
+
declare function outcomeFor(c: Cadence, runId: string): Promise<TerminalOutcome | null>;
|
|
644
|
+
|
|
645
|
+
type FinalizeResult = {
|
|
646
|
+
applied: true;
|
|
647
|
+
runState: string;
|
|
648
|
+
requestState: string;
|
|
649
|
+
} | {
|
|
650
|
+
applied: false;
|
|
651
|
+
reason: string;
|
|
652
|
+
};
|
|
653
|
+
/**
|
|
654
|
+
* The single transition that ends a run. It must write the outcome: a run that is
|
|
655
|
+
* applied but still reports `blocked` has had its effects consumed while continuing to
|
|
656
|
+
* look unfinished, which is indistinguishable from a stuck run to every other reader.
|
|
657
|
+
*/
|
|
658
|
+
declare function finalize(c: Cadence, runId: string, outcome: TerminalOutcome, now: Date): Promise<FinalizeResult>;
|
|
659
|
+
|
|
660
|
+
/**
|
|
661
|
+
* Blocking is **not** a terminal transition. The run keeps its reservation, the unit
|
|
662
|
+
* keeps its occupancy, and the request stays open — because the work is still owed and
|
|
663
|
+
* nothing has been decided. `appliedAt` therefore stays null so the run can still be
|
|
664
|
+
* finalized later, which is what makes "blocked run later succeeds" possible.
|
|
665
|
+
*/
|
|
666
|
+
declare function blockRun(c: Cadence, runId: string, reason: BlockReason, evidenceNeeded: string, now: Date): Promise<boolean>;
|
|
667
|
+
declare function unblockRun(c: Cadence, runId: string, now: Date): Promise<boolean>;
|
|
668
|
+
|
|
669
|
+
interface ReconcileOptions {
|
|
670
|
+
noProgressDeadlineMs: number;
|
|
671
|
+
/** How long an uncertain publication waits before it is escalated rather than resolved. */
|
|
672
|
+
publicationResolutionGraceMs: number;
|
|
673
|
+
}
|
|
674
|
+
interface ReconcileReport {
|
|
675
|
+
submissionClaimsReleased: number;
|
|
676
|
+
submissionsAdopted: number;
|
|
677
|
+
submissionsEscalated: number;
|
|
678
|
+
outboxClaimsReclaimed: number;
|
|
679
|
+
publicationsResolved: number;
|
|
680
|
+
publicationsEscalated: number;
|
|
681
|
+
runsTerminated: number;
|
|
682
|
+
runsBlocked: number;
|
|
683
|
+
}
|
|
684
|
+
interface ReconcileDeps {
|
|
685
|
+
vendor?: Vendor & {
|
|
686
|
+
cancel?(run: RunDoc): Promise<boolean>;
|
|
687
|
+
};
|
|
688
|
+
/** Optional: lets an uncertain publication be resolved instead of escalated. */
|
|
689
|
+
queue?: Queue & {
|
|
690
|
+
findByIdempotencyKey?(key: string): Promise<{
|
|
691
|
+
taskId: string;
|
|
692
|
+
} | null>;
|
|
693
|
+
};
|
|
694
|
+
}
|
|
695
|
+
declare function reconcile(c: Cadence, now: Date, opts: ReconcileOptions, deps?: ReconcileDeps): Promise<ReconcileReport>;
|
|
696
|
+
/** Convenience for drivers that sweep on a fixed interval. */
|
|
697
|
+
declare function nextSweepAt(now: Date, intervalMs: number): Date;
|
|
698
|
+
|
|
699
|
+
/**
|
|
700
|
+
* Attention is a list, not a flag. Three unrelated problems can be true at once, and a
|
|
701
|
+
* single field forces each new one to overwrite the last — so clearing the one that was
|
|
702
|
+
* fixed silently clears the two that were not.
|
|
703
|
+
*/
|
|
704
|
+
declare function raiseAttention(c: Cadence, unitKey: string, reason: string, now: Date, detail?: string): Promise<boolean>;
|
|
705
|
+
/** Clears only the named episode, leaving any other open episodes untouched. */
|
|
706
|
+
declare function clearAttention(c: Cadence, unitKey: string, reason: string): Promise<void>;
|
|
707
|
+
declare function attentionReasons(c: Cadence, unitKey: string): Promise<string[]>;
|
|
708
|
+
|
|
709
|
+
declare function refreshEligibility(c: Cadence, unitKey: string, now: Date): Promise<Date>;
|
|
710
|
+
declare function refreshIntegrationEligibility(c: Cadence, integrationId: string, now: Date): Promise<void>;
|
|
711
|
+
declare function patchAvailability(c: Cadence, unitKey: string, patch: Partial<Omit<Availability, 'suspensions'>>, now: Date): Promise<void>;
|
|
712
|
+
declare function addSuspension(c: Cadence, unitKey: string, suspension: Suspension, now: Date): Promise<void>;
|
|
713
|
+
declare function removeSuspension(c: Cadence, unitKey: string, suspensionId: string, now: Date): Promise<void>;
|
|
714
|
+
declare function setTrafficPolicy(c: Cadence, integrationId: string, policy: Integration['trafficPolicy'], now: Date): Promise<void>;
|
|
715
|
+
|
|
716
|
+
export { DEFAULTS, EnqueueRejected, EnqueueUncertain, ProgrammingError, TERMINAL_OUTCOME_KINDS, activateReservation, addSuspension, admissibility, admit, assertTerminal, attemptBudget, attentionReasons, backoffMs, blockRun, clearAttention, completionOutcome, computeWindow, connect, countsTowardQuarantine, defaultIntegrationPolicy, defaultTrafficPolicy, downloadNext, ensureIndexes, expireSubmissionClaim, finalize, grantIsLive, isEnqueueRejected, isEnqueueUncertain, isRepetitionSafe, isUnitComplete, markUnknown, nextSweepAt, outcomeFor, patchAvailability, plan, pollRun, publishOutbox, raiseAttention, reconcile, refreshEligibility, refreshIntegrationEligibility, removeSuspension, requestDispositionFor, runId, setTrafficPolicy, submitKickoff, terminalRunState, trafficStateAt, unblockRun };
|
|
717
|
+
export type { AcquisitionScope, Admissibility, AdmissibilityReason, AdmissionSnapshot, AdmitResult, AttentionEpisode, Availability, Cadence, CapabilityProfile, CoverageDoc, DownloadStep, ExecuteOptions, Failure, FailureClass, FileSink, FinalizeResult, Integration, IntegrationPolicy, Interval, Kind, Manifest, ManifestEntry, ManifestEntryState, OperatorGrant, OutboxDoc, PlanDiagnostics, PlanResult, PollEntry, PollOutcome, PollStep, PollingVendor, Proposal, PublishOptions, PublishResult, Queue, ReconcileDeps, ReconcileOptions, ReconcileReport, RepairDoc, RequestDisposition, RequestDoc, RequestState, Reservation, RunDoc, RunState, StallState, SubmitResult, Suspension, TerminalOutcome, TrafficOp, TrafficPolicy, TrafficRule, TrafficState, Unit, UnitCounters, Vendor, VendorSubmission, Window, WindowDomain, WindowPlan, WorkerOptions };
|