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.
@@ -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 segment is an OWN key of a plain object
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 mid-path (no index, by (d)), a primitive — is
19
- * `undefined`, which is what `distinct` routes to `nokey`. The value at the end is returned whatever it is.
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), and — v0.44 — the `$` prefix. *(This read *"exactly one invented token"*
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, resolved by the driver and handed to
650
- * the type's `fn` as `ctx.key`.
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` or a segment is missing. */
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**: dot-separated OBJECT keys, each segment in `FD-V16`'s
148
- * charset, over the value a gate receives. **No array index, no wildcard, no expression** — a key a flow
149
- * needs COMPUTED is computed in the task before the gate (P24 decision 5), because the driver has no
150
- * `async` and `evaluate()` in every expression language here returns a Promise (ADR 0051).
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
- } | null;
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 path),
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 path a
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
- * branch paths minted at run time, each of the branch's output shape — carried internally as
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 a branch path never meets it.
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. `1` at this version; it moves only when what a checkpoint CARRIES moves, and
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 = 1;
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 is refused `halted`.
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 1'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` |
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`** — [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)
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.10.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",