fyflow-orchestration 0.10.0 → 0.11.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 +173 -5
- package/README.md +1 -1
- package/dist/browser/chunks/{chunk-NA6QQAZ2.js → chunk-5CVSWDCB.js} +79 -12
- package/dist/browser/index.js +539 -3
- package/dist/browser/scheduler/index.js +1 -1
- package/dist/node/chunks/{chunk-NA6QQAZ2.js → chunk-5CVSWDCB.js} +79 -12
- package/dist/node/index.js +539 -3
- package/dist/node/scheduler/index.js +1 -1
- package/dist/types/index.d.ts +1 -0
- package/dist/types/src/definition/definition-schema.d.ts +23 -0
- package/dist/types/src/definition/types.d.ts +2 -1
- package/dist/types/src/definition/validate.d.ts +41 -2
- package/dist/types/src/definition/wiring.d.ts +10 -0
- package/dist/types/src/driver/driver.d.ts +1 -1
- package/dist/types/src/fold/run-state.d.ts +17 -0
- package/package.json +2 -1
|
@@ -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
|
*/
|
|
@@ -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
|
|
@@ -324,6 +348,12 @@ export declare function settingsProblem(schema: JsonSchema | undefined, defaults
|
|
|
324
348
|
* reads `conditional`. A `"."` may not carry one — it resolves to the edge's own
|
|
325
349
|
* value, which is always there — and the remainder after the suffix is stripped must
|
|
326
350
|
* still be an id, so `"?"`, `"n??"` and `".?"` are all `null` with no extra clause.
|
|
351
|
+
*
|
|
352
|
+
* **And since v0.49 the `!error` PART** — [ADR 0131](../../doc/decisions/0131-a-reference-may-name-a-nodes-error.md),
|
|
353
|
+
* P43 (c1): `"n!error"` names node `n`'s ERROR rather than its result, in both forms and with `?` (`"n!error?"`,
|
|
354
|
+
* `["n!error"]`, `["n!error?"]`). It is a fourth field, `part`, beside `form` and `conditional` and orthogonal to both —
|
|
355
|
+
* **present only on that form** — because it changes WHAT is read of the outputs and never which outputs are named:
|
|
356
|
+
* `FD-V27`-`FD-V29` aim it as the plain reference and the driver resolves it through the same index (P43 decision 5).
|
|
327
357
|
*/
|
|
328
358
|
export declare function referenceTarget(ref: unknown): {
|
|
329
359
|
form: 'self';
|
|
@@ -337,11 +367,20 @@ export declare function referenceTarget(ref: unknown): {
|
|
|
337
367
|
form: 'item';
|
|
338
368
|
node: null;
|
|
339
369
|
conditional: false;
|
|
340
|
-
} |
|
|
370
|
+
} | AimedReference | null;
|
|
371
|
+
/**
|
|
372
|
+
* **A reference that AIMS at a node** — `"n"` or `["n"]`, either with `?`, and since v0.49 either naming the node's ERROR
|
|
373
|
+
* (`"n!error"`, `["n!error?"]`, …) — [ADR 0131](../../doc/decisions/0131-a-reference-may-name-a-nodes-error.md), P43 (c1).
|
|
374
|
+
* **`part` is PRESENT only on the error form**, so every spelling before v0.49 parses to the object it parsed to (P43
|
|
375
|
+
* prediction 3), and a reader that does not ask for `part` reads the error form as the node it aims at — which is what
|
|
376
|
+
* `FD-V27`-`FD-V29` are meant to do (P43 decision 5) and what a RESOLVER must not (`resolveReference`, the wiring check).
|
|
377
|
+
*/
|
|
378
|
+
export type AimedReference = {
|
|
341
379
|
form: 'one' | 'all';
|
|
342
380
|
node: string;
|
|
343
381
|
conditional: boolean;
|
|
344
|
-
|
|
382
|
+
part?: 'error';
|
|
383
|
+
};
|
|
345
384
|
export declare function validateDefinition(doc: FlowDefinition, registry: Registry): Finding[];
|
|
346
385
|
/** Convenience: the rule ids violated, deduplicated and sorted. */
|
|
347
386
|
export declare function violatedRules(findings: Finding[]): string[];
|
|
@@ -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[];
|
|
@@ -1841,7 +1841,7 @@ export declare class Driver {
|
|
|
1841
1841
|
private cache;
|
|
1842
1842
|
/**
|
|
1843
1843
|
* **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
|
|
1844
|
+
* 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
1845
|
* in its tasks' FIRST-RECORD order, the order the rebuild grouped them in.
|
|
1846
1846
|
*
|
|
1847
1847
|
* **`!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.11.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",
|