fyflow-orchestration 0.10.0 → 0.12.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/AGENTS.md +249 -53
- package/README.md +5 -5
- package/dist/browser/chunks/{chunk-NA6QQAZ2.js → chunk-4JFQX7DL.js} +164 -49
- package/dist/browser/index.js +546 -3
- package/dist/browser/scheduler/index.js +1 -1
- package/dist/node/chunks/{chunk-NA6QQAZ2.js → chunk-4JFQX7DL.js} +164 -49
- package/dist/node/index.js +546 -3
- package/dist/node/scheduler/index.js +1 -1
- package/dist/types/index.d.ts +1 -0
- package/dist/types/src/definition/assist.d.ts +1 -1
- package/dist/types/src/definition/condition.d.ts +21 -3
- package/dist/types/src/definition/definition-schema.d.ts +23 -0
- package/dist/types/src/definition/types.d.ts +8 -5
- package/dist/types/src/definition/validate.d.ts +50 -6
- package/dist/types/src/definition/wiring.d.ts +15 -5
- package/dist/types/src/driver/driver.d.ts +17 -6
- package/dist/types/src/fold/run-state.d.ts +17 -0
- package/package.json +2 -1
|
@@ -11,12 +11,30 @@
|
|
|
11
11
|
* but types.
|
|
12
12
|
*/
|
|
13
13
|
import type { PredicateLeaf, When } from './types.js';
|
|
14
|
+
/**
|
|
15
|
+
* **One step of a key path** — a KEY (an own key of a plain object) or, since v0.53, an INDEX (an element of a real
|
|
16
|
+
* array). [ADR 0137](../../doc/decisions/0137-a-key-path-indexes-an-array-by-a-bracket-suffix-and-a-plain-segment-keeps-its-meaning.md).
|
|
17
|
+
*/
|
|
18
|
+
export type KeyPathStep = {
|
|
19
|
+
readonly key: string;
|
|
20
|
+
} | {
|
|
21
|
+
readonly index: number;
|
|
22
|
+
};
|
|
23
|
+
/**
|
|
24
|
+
* **A key path's STEPS, in order** — `files[0].series` is `files`, `[0]`, `series`. Split on `.` as it always was
|
|
25
|
+
* (neither a key nor an index holds one), then each segment's bracket suffix, where it has one the grammar spells,
|
|
26
|
+
* into its indexes. The one parse `readKeyPath` and the wiring check (`requireAlong`, `keyPathRefusal`) both walk, so
|
|
27
|
+
* the run and the check cannot read a path differently. Total: any string has steps.
|
|
28
|
+
*/
|
|
29
|
+
export declare function keyPathSteps(path: string): KeyPathStep[];
|
|
14
30
|
/**
|
|
15
31
|
* **What a key path NAMES on a value — the meaning of stop-and-ask (d)'s grammar**, one definition for the
|
|
16
|
-
* driver that resolves it (W93, where a branch enters a gate) and the tests that pin it. Each
|
|
32
|
+
* driver that resolves it (W93, where a branch enters a gate) and the tests that pin it. Each KEY step is an OWN key of a plain object
|
|
17
33
|
* (`hasOwnProperty`, never `in`, which walks the prototype — W65's conformity reader, three keyword sites);
|
|
18
|
-
* anything else — a missing key, `null`, an ARRAY
|
|
19
|
-
* `undefined`, which is what `distinct` routes to `nokey`.
|
|
34
|
+
* anything else — a missing key, `null`, an ARRAY under a key step (a plain numeric segment is a KEY, by (c1)), a
|
|
35
|
+
* primitive — is `undefined`, which is what `distinct` routes to `nokey`. **An INDEX step `[n]` (v0.53, ADR 0137) is an
|
|
36
|
+
* OWN element of a REAL array** (`Array.isArray`, `n < length`, not a hole) and of nothing else: a plain object holding a key `"n"`, an
|
|
37
|
+
* array-like object, a typed array and a primitive are all `undefined`. The value at the end is returned whatever it is.
|
|
20
38
|
*/
|
|
21
39
|
export declare function readKeyPath(value: unknown, path: string): unknown;
|
|
22
40
|
/**
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import { type Registry } from './types.js';
|
|
2
|
+
/**
|
|
3
|
+
* **What `definitionSchema()` returns** — a plain, JSON-serialisable JSON Schema draft 2020-12 document, owned by the
|
|
4
|
+
* caller: a new value on every call, so mutating one changes no other.
|
|
5
|
+
*/
|
|
6
|
+
export type DefinitionSchema = {
|
|
7
|
+
$schema: string;
|
|
8
|
+
} & Record<string, unknown>;
|
|
9
|
+
/**
|
|
10
|
+
* **A flow definition's shape as a JSON Schema, draft 2020-12** — P43 (a1), ADR 0132; the registry form W211's. A
|
|
11
|
+
* plain object, a NEW one on every call, JSON-serialisable.
|
|
12
|
+
*
|
|
13
|
+
* - **No argument: the STATIC shape.** It carries every rule a node, an edge or a value decides by its own shape and
|
|
14
|
+
* names `validateDefinition` as the authority for the rest; what it refuses, `validateDefinition` refuses under
|
|
15
|
+
* EVERY registry.
|
|
16
|
+
* - **A registry: the shape SPECIALISED to it** (`spec/flow-definition.md` section 1, v0.51). The registry is first held
|
|
17
|
+
* to `checkRegistry` — the check `new Driver` runs over the registry it is handed — and one that check refuses THROWS
|
|
18
|
+
* that refusal, never specialised. Then the static shape gains what the registry decides of ONE node: a task's
|
|
19
|
+
* `type`, `pool`, `settings`, a transform-only type's `transform`, `workerGroups`, `transform.lang`, a predicate
|
|
20
|
+
* name, a gate's `type`, `settings` and — for a STATIC gate type — `route` (`specialise`, below). What it refuses,
|
|
21
|
+
* `validateDefinition(flow, registry)` refuses against THAT registry.
|
|
22
|
+
*/
|
|
23
|
+
export declare function definitionSchema(registry?: Registry): DefinitionSchema;
|
|
@@ -38,10 +38,11 @@ export type TerminalState = 'done' | 'failed' | 'user_action' | 'cancelled';
|
|
|
38
38
|
* | `"$payload"` | **the value the RUN entered with** — what `start()` was handed, from any node and any edge (v0.44, [ADR 0117](../../doc/decisions/0117-a-reference-may-name-what-reached-the-run.md)). Always there, so no `?` and no array form. `$` is outside `FD-V16`'s charset, and the whole `$` prefix is reserved: `"$item"` — a map instance's item — is W191's, and any other `$` spelling is `FD-V26` |
|
|
39
39
|
* | `"score"` | that node's output **on this node's own branch path**. Exactly one, or the run stops (`FD-R3`) |
|
|
40
40
|
* | `["score"]` | that node's outputs as an **array**, in ascending segment-wise-numeric `branchPath` order. Legal only where the reader is outside a region containing the named node (`FD-V28`) |
|
|
41
|
+
* | `"score!error"` | **that node's ERROR** rather than its result, on either form and with `?` last (`["score!error?"]`): the effective outcome's `error` string, `null` where it succeeded — v0.49, [ADR 0131](../../doc/decisions/0131-a-reference-may-name-a-nodes-error.md). Aimed as `"score"` is; `!` is outside `FD-V16`'s charset |
|
|
41
42
|
*
|
|
42
43
|
* **The array form uses JSON's own array syntax rather than a sigil**, so the
|
|
43
44
|
* grammar invents tokens only for what has no node id: `"."`, the `?` modifier
|
|
44
|
-
* (v0.13),
|
|
45
|
+
* (v0.13), — v0.44 — the `$` prefix, and — v0.49 — the `!error` part. *(This read *"exactly one invented token"*
|
|
45
46
|
* until v0.13 and stayed so until W190.)* A `string` covers every token, so the
|
|
46
47
|
* TYPE does not move; `referenceTarget`'s parse does.
|
|
47
48
|
*/
|
|
@@ -104,7 +105,8 @@ export interface PredicateLeaf {
|
|
|
104
105
|
* A KEY PATH over the `DecisionContext` itself, read by `readKeyPath` — the same resolution a
|
|
105
106
|
* gate's `settings.key` gets, measured unchanged at this scope. **Its first segment is `outcome`
|
|
106
107
|
* or `needs` and nothing else** (`FD-V43`), because a first segment that is neither resolves to
|
|
107
|
-
* `undefined` in silence and a typo would be a wrong key rather than a refusal.
|
|
108
|
+
* `undefined` in silence and a typo would be a wrong key rather than a refusal. A key past the root may
|
|
109
|
+
* carry array indexes — `outcome.result.items[0].score` — and the root never does (v0.53, ADR 0137).
|
|
108
110
|
*/
|
|
109
111
|
path: string;
|
|
110
112
|
op: PredicateOp;
|
|
@@ -646,8 +648,9 @@ export interface GateNode {
|
|
|
646
648
|
/**
|
|
647
649
|
* **What the gate's type is configured with** — a plain object its type's `settingsSchema` accepts
|
|
648
650
|
* (`FD-V40`), `{}` when absent. **`key` is the one setting the LIBRARY reads**: where present it is a
|
|
649
|
-
* KEY PATH (`keyPathProblem`) over the value the gate receives
|
|
650
|
-
*
|
|
651
|
+
* KEY PATH (`keyPathProblem`) over the value the gate receives — dotted object keys, each optionally
|
|
652
|
+
* followed by array indexes `[n]` since v0.53 (`files[0].series`, ADR 0137) — resolved by the driver and
|
|
653
|
+
* handed to the type's `fn` as `ctx.key`.
|
|
651
654
|
*/
|
|
652
655
|
settings?: Readonly<Record<string, unknown>>;
|
|
653
656
|
/** Each carries `to` and, optionally, `route` — and nothing else (`FD-V41`). */
|
|
@@ -662,7 +665,7 @@ export interface GateNode {
|
|
|
662
665
|
* to be.)*
|
|
663
666
|
*/
|
|
664
667
|
export interface GateContext {
|
|
665
|
-
/** `settings.key` resolved over `input` by `readKeyPath` — `undefined` where the gate declares no `key
|
|
668
|
+
/** `settings.key` resolved over `input` by `readKeyPath` — `undefined` where the gate declares no `key`, a key is missing, or an index `[n]` is not an element of a real array. */
|
|
666
669
|
readonly key: unknown;
|
|
667
670
|
/** The value that reached the gate — what leaves it, unchanged, on the route `fn` returns. */
|
|
668
671
|
readonly input: unknown;
|
|
@@ -19,6 +19,19 @@
|
|
|
19
19
|
*/
|
|
20
20
|
import type { Finding, FlowDefinition, GateType, GateTypes, JsonSchema, StaticGateType, LanguageAdapter, Languages, NodeTypeEntry, NodeTypes, Pools, Registry, WorkerEntry, Workers } from './types.js';
|
|
21
21
|
export { readKeyPath } from './condition.js';
|
|
22
|
+
declare const KINDS: readonly ["task", "fanout", "map", "join", "end", "gate", "ask"];
|
|
23
|
+
/**
|
|
24
|
+
* **`FD-V16`'s charset — a flow's and a node's id** ([spec/task-id.md](../../spec/task-id.md)'s) — v0.50 (W210,
|
|
25
|
+
* [ADR 0132](../../doc/decisions/0132-a-definitions-shape-is-a-schema-built-from-the-validator.md)), so
|
|
26
|
+
* `definitionSchema()` builds its `pattern` from the validator's expression. **A COPY** — `compile()` on it, or a
|
|
27
|
+
* consumer's edit, moves no verdict (W210's conformity reader, S2: the live object did).
|
|
28
|
+
*/
|
|
29
|
+
declare const ID_RE_COPY: RegExp;
|
|
30
|
+
/** **The seven node kinds `FD-V24` admits** — v0.50 (W210, ADR 0132), for `definitionSchema()`'s `kind` enum; a FROZEN copy. */
|
|
31
|
+
declare const KINDS_COPY: readonly (typeof KINDS)[number][];
|
|
32
|
+
export { ID_RE_COPY as ID_RE, KINDS_COPY as KINDS };
|
|
33
|
+
/** **The terminal states an edge's `on` may name** (`FD-V18`) — a copy of the validator's own list, v0.50 (W210, ADR 0132). */
|
|
34
|
+
export declare const ROUTABLE_STATES: readonly string[];
|
|
22
35
|
/**
|
|
23
36
|
* **The six keys a `task` declares that an `ask` REFUSES, each by `FD-V47` and by nothing else** — v0.42, W179,
|
|
24
37
|
* P35 stop-and-ask (a) and decision 6. Every one is read by a task's WORKER or its scheduler task — a type and its
|
|
@@ -49,6 +62,17 @@ export declare const TASK_KEYS_DECLARED: readonly string[];
|
|
|
49
62
|
* P16 decision 3's silent-key hole one row over.
|
|
50
63
|
*/
|
|
51
64
|
export declare const NODE_KEYS_DECLARED: Readonly<Record<string, readonly string[]>>;
|
|
65
|
+
/**
|
|
66
|
+
* **The REQUIRED half of each kind's keys, the edge's and the document's** — `FD-V23`'s three lists, copied, v0.50
|
|
67
|
+
* (W210, [ADR 0132](../../doc/decisions/0132-a-definitions-shape-is-a-schema-built-from-the-validator.md)):
|
|
68
|
+
* `definitionSchema()` reads its `required` from these, so a key the validator starts requiring is one the schema
|
|
69
|
+
* requires, and a key it stops requiring one the schema stops requiring. Every document key is required.
|
|
70
|
+
*/
|
|
71
|
+
export declare const NODE_KEYS_REQUIRED: Readonly<Record<string, readonly string[]>>;
|
|
72
|
+
/** The edge's required keys — `FD-V23`'s *an edge without `to`*, copied (v0.50, W210). */
|
|
73
|
+
export declare const EDGE_KEYS_REQUIRED: readonly string[];
|
|
74
|
+
/** The document's keys, every one required (`FD-V23`) and none other declared (`FD-V17`) — copied, v0.50 (W210). */
|
|
75
|
+
export declare const DOC_KEYS_DECLARED: readonly string[];
|
|
52
76
|
/**
|
|
53
77
|
* **The two keys a `retryPolicy` carries, and no others** — `FD-V30`. The scheduler's own
|
|
54
78
|
* constructor at 0.5.2 destructures exactly these; a key beside them is a typo the scheduler
|
|
@@ -144,10 +168,15 @@ export declare function poolsOf(x: Pools | undefined): ReadonlyMap<string, {
|
|
|
144
168
|
*/
|
|
145
169
|
export declare function languagesOf(x: Languages | undefined): ReadonlyMap<string, LanguageAdapter>;
|
|
146
170
|
/**
|
|
147
|
-
* **A KEY PATH — P24 stop-and-ask (d), answered
|
|
148
|
-
*
|
|
149
|
-
*
|
|
150
|
-
* `
|
|
171
|
+
* **A KEY PATH — P24 stop-and-ask (d), answered; an array INDEX since v0.53** (P44 (c1),
|
|
172
|
+
* [ADR 0137](../../doc/decisions/0137-a-key-path-indexes-an-array-by-a-bracket-suffix-and-a-plain-segment-keeps-its-meaning.md)):
|
|
173
|
+
* dot-separated SEGMENTS over the value a gate receives, each an OBJECT key in `FD-V16`'s charset followed by zero or
|
|
174
|
+
* more bracket indexes `[n]` — `n` is `0` or `[1-9][0-9]{0,8}`, no leading zero, at most 999,999,999. **An index is a
|
|
175
|
+
* SUFFIX of a segment and never leads the path**, so the first step is always a key. A plain numeric segment (`xs.1`)
|
|
176
|
+
* is still a KEY. **No quoted key, no wildcard, no expression** — a key a flow needs COMPUTED is computed in the task
|
|
177
|
+
* before the gate (P24 decision 5), because the driver has no `async` and `evaluate()` in every expression language
|
|
178
|
+
* here returns a Promise (ADR 0051). **Its `source` is package surface and moved at v0.53**; every string it matched
|
|
179
|
+
* before it still matches, and resolves as before, since none held `[`.
|
|
151
180
|
*/
|
|
152
181
|
export declare const KEY_PATH_RE: RegExp;
|
|
153
182
|
/**
|
|
@@ -324,6 +353,12 @@ export declare function settingsProblem(schema: JsonSchema | undefined, defaults
|
|
|
324
353
|
* reads `conditional`. A `"."` may not carry one — it resolves to the edge's own
|
|
325
354
|
* value, which is always there — and the remainder after the suffix is stripped must
|
|
326
355
|
* still be an id, so `"?"`, `"n??"` and `".?"` are all `null` with no extra clause.
|
|
356
|
+
*
|
|
357
|
+
* **And since v0.49 the `!error` PART** — [ADR 0131](../../doc/decisions/0131-a-reference-may-name-a-nodes-error.md),
|
|
358
|
+
* P43 (c1): `"n!error"` names node `n`'s ERROR rather than its result, in both forms and with `?` (`"n!error?"`,
|
|
359
|
+
* `["n!error"]`, `["n!error?"]`). It is a fourth field, `part`, beside `form` and `conditional` and orthogonal to both —
|
|
360
|
+
* **present only on that form** — because it changes WHAT is read of the outputs and never which outputs are named:
|
|
361
|
+
* `FD-V27`-`FD-V29` aim it as the plain reference and the driver resolves it through the same index (P43 decision 5).
|
|
327
362
|
*/
|
|
328
363
|
export declare function referenceTarget(ref: unknown): {
|
|
329
364
|
form: 'self';
|
|
@@ -337,11 +372,20 @@ export declare function referenceTarget(ref: unknown): {
|
|
|
337
372
|
form: 'item';
|
|
338
373
|
node: null;
|
|
339
374
|
conditional: false;
|
|
340
|
-
} |
|
|
375
|
+
} | AimedReference | null;
|
|
376
|
+
/**
|
|
377
|
+
* **A reference that AIMS at a node** — `"n"` or `["n"]`, either with `?`, and since v0.49 either naming the node's ERROR
|
|
378
|
+
* (`"n!error"`, `["n!error?"]`, …) — [ADR 0131](../../doc/decisions/0131-a-reference-may-name-a-nodes-error.md), P43 (c1).
|
|
379
|
+
* **`part` is PRESENT only on the error form**, so every spelling before v0.49 parses to the object it parsed to (P43
|
|
380
|
+
* prediction 3), and a reader that does not ask for `part` reads the error form as the node it aims at — which is what
|
|
381
|
+
* `FD-V27`-`FD-V29` are meant to do (P43 decision 5) and what a RESOLVER must not (`resolveReference`, the wiring check).
|
|
382
|
+
*/
|
|
383
|
+
export type AimedReference = {
|
|
341
384
|
form: 'one' | 'all';
|
|
342
385
|
node: string;
|
|
343
386
|
conditional: boolean;
|
|
344
|
-
|
|
387
|
+
part?: 'error';
|
|
388
|
+
};
|
|
345
389
|
export declare function validateDefinition(doc: FlowDefinition, registry: Registry): Finding[];
|
|
346
390
|
/** Convenience: the rule ids violated, deduplicated and sorted. */
|
|
347
391
|
export declare function violatedRules(findings: Finding[]): string[];
|
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
* module derives the SCHEMA of that value from the producer side of each arc that reaches it, one
|
|
10
10
|
* verdict per arc, in five shapes: an ordinary **edge** (the producer's `outputSchema`), a fan-out
|
|
11
11
|
* **branch** (the same value the fan-out received — `JP-R11`), a map **item** (one element of the
|
|
12
|
-
* `over` array the map received), a join's **record** (`JP-R12`'s, keyed by branch
|
|
12
|
+
* `over` array the map received), a join's **record** (`JP-R12`'s, keyed by each branch's own key),
|
|
13
13
|
* and a **needs** composition (`FD-C1`'s table: `"."` is the edge's value, a node id is that node's
|
|
14
14
|
* output, `[id]` an array of them, a `?` makes the key optional — and over a map's item, one
|
|
15
15
|
* composed object per element, evaluated per element as the run does). The ENTRY has no arc: its
|
|
@@ -42,14 +42,14 @@
|
|
|
42
42
|
* **A join successor's input is a DIFFERENT question** (decision 8), and the subset cannot say
|
|
43
43
|
* *any key, each of shape S* — measured at W73's declaration: `additionalProperties: <schema>` is
|
|
44
44
|
* refused by `schemaProblem`. So the record's shape is THIS MODULE's knowledge and not a keyword's:
|
|
45
|
-
* for a `fanout` region the record schema is exact in its KEYS (every declared branch
|
|
46
|
-
* property, no other key) and REQUIRES none of them — a branch that is lost has no entry, and a
|
|
45
|
+
* for a `fanout` region the record schema is exact in its KEYS (every declared branch ENTRY NODE ID a
|
|
46
|
+
* property, no other key — v0.25, ADR 0138; a branch path until 0.12.0) and REQUIRES none of them — a branch that is lost has no entry, and a
|
|
47
47
|
* branch is lost by three roads no document shows (an `optional` task failing, a person resolving a
|
|
48
48
|
* suspended task `failed`, a policy firing before it settles — `JP-R12`, `spec/join-policy.md`
|
|
49
49
|
* section 2), so a consumer requiring a branch key is `no`; and for a `map` region it is an object whose keys are
|
|
50
|
-
*
|
|
50
|
+
* ITEM INDEXES minted at run time (`"0"`, `"1"`, …), each of the branch's output shape — carried internally as
|
|
51
51
|
* `additionalProperties: <schema>` with a `branchKeys` marker, which `fits` reads and no author may
|
|
52
|
-
* write. A consumer naming a property that is not
|
|
52
|
+
* write. A consumer naming a property that is not an item index never meets it.
|
|
53
53
|
*
|
|
54
54
|
* **A transformed arc is verified on a SAMPLE, and the verdict says which sample** (ADR 0056 rule
|
|
55
55
|
* 3, [Q301](../../doc/questions/q301.md)): the producer's first declared example, else the
|
|
@@ -127,7 +127,17 @@ export interface WiringVerdict {
|
|
|
127
127
|
/** The relation's own reason, in the words `fact-3-controls.log` prints. */
|
|
128
128
|
why: string;
|
|
129
129
|
sample?: WiringSample;
|
|
130
|
+
/**
|
|
131
|
+
* **Why a `transform-fails` verdict failed — present on that kind and ABSENT on every other** (v0.48,
|
|
132
|
+
* [W208](../../doc/work-items/w208-a-transforms-cause-and-when-an-ask-was-asked.md), P43 (d1), decision 6): `'threw'` where the transform did not produce a result — the language's worker half failing to import, having
|
|
133
|
+
* no default export, its `compile` throwing or its `evaluate` throwing, alike — and `'schema'` where it produced one
|
|
134
|
+
* and the consumer's `inputSchema` refused it. `why` says the same in words and is unmoved; this says it as data.
|
|
135
|
+
* Additive in 0.11.0: `VerdictKind`, `VERDICT_KINDS` and every count are unmoved.
|
|
136
|
+
*/
|
|
137
|
+
cause?: TransformFailureCause;
|
|
130
138
|
}
|
|
139
|
+
/** What a `transform-fails` verdict's {@link WiringVerdict.cause} names: the transform threw, or its result failed the consumer's schema. */
|
|
140
|
+
export type TransformFailureCause = 'threw' | 'schema';
|
|
131
141
|
export interface WiringReport {
|
|
132
142
|
flowId: string;
|
|
133
143
|
verdicts: WiringVerdict[];
|
|
@@ -276,10 +276,19 @@ export interface RunPauseOptions {
|
|
|
276
276
|
}
|
|
277
277
|
/**
|
|
278
278
|
* **What a checkpoint's header says, and the number a resume refuses on** — `RN-R16`,
|
|
279
|
-
* ADR 0064 rule 3. `
|
|
279
|
+
* ADR 0064 rule 3. `2` at this version; it moves only when what a checkpoint CARRIES moves, and
|
|
280
280
|
* a resume refuses a format it does not know — `ResumeRefused` with `reason: 'format'` (`RN-R23`, W89).
|
|
281
|
+
*
|
|
282
|
+
* **`1` until 0.12.0, and it moved because a join's collection moved** — `RN-R16` v0.36,
|
|
283
|
+
* [ADR 0138](../../doc/decisions/0138-a-join-hands-on-each-branch-under-its-own-key-and-a-checkpoint-of-the-old-keying-is-refused-by-format.md)
|
|
284
|
+
* (P44 (b), the maintainer's: no backward compatibility). A collection reaches a checkpoint through an `asked` element's
|
|
285
|
+
* `input`, a `gated` decision taken on a key path into it, and every fed outcome whose worker read it (P44 fact 4), so a
|
|
286
|
+
* format-1 run replayed under the own-key collection would refuse `diverged`, re-route a gate, or carry results computed
|
|
287
|
+
* from keys that no longer exist. **This driver carries ONE keying and reads no format 1**: every 0.11.0 checkpoint — a
|
|
288
|
+
* join in it or none — is refused `format` by `resume()`, `runtime.resume` and `inputOf`, before anything is replayed;
|
|
289
|
+
* and a 0.11.0 driver refuses this one's the same way.
|
|
281
290
|
*/
|
|
282
|
-
export declare const CHECKPOINT_FORMAT =
|
|
291
|
+
export declare const CHECKPOINT_FORMAT = 2;
|
|
283
292
|
/**
|
|
284
293
|
* **The header — the facts a run's EVENTS cannot regenerate** (`RN-R15`, ADR 0064 rule 2, P23
|
|
285
294
|
* decision 4). Every other fact about a run is in its events, which the driver regenerates from
|
|
@@ -343,7 +352,8 @@ export interface Checkpoint {
|
|
|
343
352
|
* **Widened by W158 with `cancelled`, and that is BREAKING for a consumer switching on `reason` exhaustively** —
|
|
344
353
|
* `resumed`'s and `gated`'s precedent (ADR 0094 consequence 1). **And W171 RENAMED `stopped` to `halted`** (ADR 0102, P34
|
|
345
354
|
* stop-and-ask (f)) — BREAKING, and loudly: a consumer's `reason === 'stopped'` no longer compiles, so it cannot silently
|
|
346
|
-
* come to mean P34's resumable stop. A 0.7.0 checkpoint holding a `stopped` element
|
|
355
|
+
* come to mean P34's resumable stop. A 0.7.0 checkpoint holding a `stopped` element was refused `halted`; since
|
|
356
|
+
* `CHECKPOINT_FORMAT` 2 (ADR 0138) it is format 1 and refused `format` first.
|
|
347
357
|
*/
|
|
348
358
|
export type ResumeRefusalReason = 'format' | 'run' | 'flow' | 'halted' | 'cancelled' | 'diverged';
|
|
349
359
|
/**
|
|
@@ -415,7 +425,7 @@ export interface NodeInput {
|
|
|
415
425
|
*
|
|
416
426
|
* | reason | when | `index` |
|
|
417
427
|
* |---|---|---|
|
|
418
|
-
* | `format` | the run is not `{ header, events[] }`, its `header.format` is not {@link CHECKPOINT_FORMAT}, its header's three fields are not format
|
|
428
|
+
* | `format` | the run is not `{ header, events[] }`, its `header.format` is not {@link CHECKPOINT_FORMAT}, its header's three fields are not the format's types, its `runId` is not a run id (`ID-R2`), or its entry payload does not clone — `resumeRefusal`'s header half, the one function | `null` |
|
|
419
429
|
* | `flow` | `header.flowId` or `header.version` is not the definition's — no migration | `null` |
|
|
420
430
|
* | `unknown` | the target cannot name anything in this run: a node id the definition lacks, a branch path that is not `spec/task-id.md`'s grammar, or a task id that does not parse, names another run, an attempt other than `0`, or a node that is neither a task nor an ask | `null` |
|
|
421
431
|
* | `not-reached` | the replay did not hand the target anything within the stored prefix a reading verifies — which ends at the first `halted`, `stopped` or `cancelRequested` element, or at the stored events' end | the prefix's length |
|
|
@@ -1050,7 +1060,8 @@ export declare class Driver {
|
|
|
1050
1060
|
private readonly firedJoins;
|
|
1051
1061
|
/**
|
|
1052
1062
|
* **What each branch carried into its join, keyed by region and then by
|
|
1053
|
-
* `branchPath`** —
|
|
1063
|
+
* `branchPath`** — the FULL path, here where it is recorded; the collection a join hands on is keyed by each
|
|
1064
|
+
* branch's OWN key, derived from these paths by `collectArrivals` at the exit (ADR 0138) —[ADR 0037](../../doc/decisions/0037-what-a-branch-receives-is-a-property-of-the-fan-out-and-what-a-join-carries-is-a-property-of-the-region.md)
|
|
1054
1065
|
* rule 4, and `JP-R11` in [spec/join-policy.md](../../spec/join-policy.md)
|
|
1055
1066
|
* section 4.
|
|
1056
1067
|
*
|
|
@@ -1841,7 +1852,7 @@ export declare class Driver {
|
|
|
1841
1852
|
private cache;
|
|
1842
1853
|
/**
|
|
1843
1854
|
* **One task's entry, made what its effective outcome now says** — `outputs()`'s catch-up, for a task one of whose records
|
|
1844
|
-
* was just read. An entry is `{ path, result }` with `result` the record's own object (`RN-R13`); a node's list is kept
|
|
1855
|
+
* was just read. An entry is `{ path, result, error }` with `result` the record's own object (`RN-R13`) and `error` its string or `null` (v0.49, ADR 0131); a node's list is kept
|
|
1845
1856
|
* in its tasks' FIRST-RECORD order, the order the rebuild grouped them in.
|
|
1846
1857
|
*
|
|
1847
1858
|
* **`!eff` — a suspended node contributes no entry.** The first record of a `user_action` task has none, and its
|
|
@@ -124,6 +124,14 @@ export interface NodeRun {
|
|
|
124
124
|
* additive: a consumer building a `NodeRun` literal is unaffected.
|
|
125
125
|
*/
|
|
126
126
|
input?: unknown;
|
|
127
|
+
/**
|
|
128
|
+
* **WHEN an ask was asked** — `RN-R36`, v0.35,
|
|
129
|
+
* [ADR 0130](../../doc/decisions/0130-a-regenerated-asked-element-keeps-the-stored-runs-time.md), W208, P43 (e1): its
|
|
130
|
+
* `asked` element's `observedAt`, KEPT after the answer as {@link NodeRun.input} is. **Present only on an ask's node, and
|
|
131
|
+
* only where its element carried one** — an element written before 0.11.0 carries none, so its entry has none. OPTIONAL
|
|
132
|
+
* and additive.
|
|
133
|
+
*/
|
|
134
|
+
askedAt?: number;
|
|
127
135
|
}
|
|
128
136
|
export interface RegionRun {
|
|
129
137
|
/** Branch paths opened, in the order the driver emitted them (`JP-R5`). */
|
|
@@ -351,11 +359,20 @@ export type FoldInput = {
|
|
|
351
359
|
* (`RN-R19`): the replay re-enters the ask and compares the input it composes with the stored one (`RN-R20`). **The
|
|
352
360
|
* first kind whose payload is a value of ANY shape**, so it is deep-copied on the way out (`freezeInput`, `RN-R17`).
|
|
353
361
|
* **A new kind, BREAKING in 0.8.0 for a consumer switching on `kind` exhaustively** (P35 decision 8).
|
|
362
|
+
*
|
|
363
|
+
* **`observedAt` — WHEN the ask was asked** (v0.35, `RN-R37`,
|
|
364
|
+
* [ADR 0130](../../doc/decisions/0130-a-regenerated-asked-element-keeps-the-stored-runs-time.md), W208, P43 (e1)): the
|
|
365
|
+
* driver's injected `now` where the branch entered the ask — the clock an outcome record's `observedAt` is read from.
|
|
366
|
+
* **A replay KEEPS the stored run's** (`RN-R19`): within the stored prefix the regenerated element takes the stored
|
|
367
|
+
* element's `observedAt`, or carries none where the stored one carries none, so it compares equal (`RN-R20`); past the
|
|
368
|
+
* stored tail it is `now()`. **OPTIONAL**: an element written before 0.11.0 has none, and a consumer building one
|
|
369
|
+
* literally is unaffected. `CHECKPOINT_FORMAT` does not move.
|
|
354
370
|
*/
|
|
355
371
|
| {
|
|
356
372
|
kind: 'asked';
|
|
357
373
|
taskId: string;
|
|
358
374
|
input: unknown;
|
|
375
|
+
observedAt?: number;
|
|
359
376
|
} | {
|
|
360
377
|
kind: 'pathEnded';
|
|
361
378
|
reason: 'end' | 'no-eligible-edge';
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "fyflow-orchestration",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.12.0",
|
|
4
4
|
"description": "Flow orchestration over fyflow-scheduler: sequence, decision, fan-out and join",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"workflow",
|
|
@@ -124,6 +124,7 @@
|
|
|
124
124
|
},
|
|
125
125
|
"license": "MIT",
|
|
126
126
|
"devDependencies": {
|
|
127
|
+
"@cfworker/json-schema": "4.1.1",
|
|
127
128
|
"@types/node": "^24.13.3",
|
|
128
129
|
"esbuild": "^0.25.12",
|
|
129
130
|
"fyflow-scheduler": "0.6.0",
|