fyflow-orchestration 0.7.0 → 0.9.0

package/dist/types/src/definition/validate.d.ts

@@ -1,9 +1,12 @@
 /**
  * The definition validator — `spec/flow-definition.md` section 5.
  *
- * Thirty-seven refusals — `FD-V14`, `FD-V15` and, since v0.19 (W65, ADR 0054), `FD-V5` and `FD-V34`
- * deliberately absent — the number `check-spec` prints as *C4 covered 37 definition refusals*, derived
- * from the ids in this file. *(34 until W92 added `FD-V39`-`FD-V41`, the GATE's three, v0.23. This read
+ * Forty-five refusals — `FD-V14`, `FD-V15` and, since v0.19 (W65, ADR 0054), `FD-V5` and `FD-V34`
+ * deliberately absent — the number `check-spec` prints as *C4 covered 45 definition refusals*, derived
+ * from the ids in this file. *(44 until W191 added `FD-V49`, `"$item"` outside any map instance, v0.45 — 42 until W179 added `FD-V47` and `FD-V48`, the ASK's two, v0.42 — and this
+ * sentence read **thirty-seven** from W92 until W179, stale by five through v0.27's `FD-V42`-`FD-V45` and
+ * v0.28's `FD-V46`, the increment again applied to a number nothing was tracking. 34 until W92 added
+ * `FD-V39`-`FD-V41`, the GATE's three, v0.23. This read
  * 23 before W45 and 24 after it: the increment was applied to a number nothing was tracking, and
  * it had been wrong by three for several plans. W45's conformity reader. **27 until W58 added
  * `FD-V30` and `FD-V31`, 29 until W59 added `FD-V32`-`FD-V34`, 32 until W61 added
@@ -14,7 +17,17 @@
  *
  * ADR 0002 rule 3: this runs in full, at instantiation, before any task is queued.
  */
-import type { Finding, FlowDefinition, GateType, GateTypes, JsonSchema, LanguageAdapter, Languages, NodeTypeEntry, NodeTypes, Pools, Registry, WorkerEntry, Workers } from './types.js';
+import type { Finding, FlowDefinition, GateType, GateTypes, JsonSchema, StaticGateType, LanguageAdapter, Languages, NodeTypeEntry, NodeTypes, Pools, Registry, WorkerEntry, Workers } from './types.js';
+export { readKeyPath } from './condition.js';
+/**
+ * **The six keys a `task` declares that an `ask` REFUSES, each by `FD-V47` and by nothing else** — v0.42, W179,
+ * 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
+ * pool, `optional`, `retryPolicy` and `workerGroups` are handed to the scheduler, and a `transform` is evaluated in
+ * the type's worker wrapper (`FD-C6`) — and an ask has neither: it is never dispatched. **One rule owns them on an
+ * ask**, `FD-V41`'s precedent for `route` on every edge, so `FD-V17`'s message (*undeclared*) does not say the wrong
+ * thing beside the right one. Exported so `test/definition/ask.test.ts` compares it to the spec's row both ways.
+ */
+export declare const ASK_REFUSED_KEYS: readonly string[];
 /**
  * **The keys `FD-V17` refuses against, exported so a test can compare them to
  * `spec/flow-definition.md` section 3s own Edge key table** — W42s conformity reader.
@@ -145,14 +158,10 @@ export declare const KEY_PATH_RE: RegExp;
  */
 export declare function keyPathProblem(v: unknown): string | null;
 /**
- * **What a key path NAMES on a value — the meaning of stop-and-ask (d)'s grammar**, one definition for the
- * 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
- * (`hasOwnProperty`, never `in`, which walks the prototype — W65's conformity reader, three keyword sites);
- * anything else — a missing key, `null`, an ARRAY mid-path (no index, by (d)), a primitive — is
- * `undefined`, which is what `distinct` routes to `nokey`. The value at the end is returned whatever it is.
+ * A gate type's own members — the interface's seven, and no other own key (a typo is the silent kind).
+ * `routesFor` and `settingsProblem` since v0.30 (ADR 0092): a type carries `routes` and `defaultRoute`
+ * (`keyResolvedRoutes?` beside them) OR `routesFor`, exactly one of the two.
  */
-export declare function readKeyPath(value: unknown, path: string): unknown;
-/** A gate type's own members — the interface's five, and no other own key (a typo is the silent kind). */
 export declare const GATE_TYPE_KEYS: readonly string[];
 /**
  * **Why a value is not a `GateType`, or `null`** — one predicate for the validator (`FD-V39`'s second
@@ -160,11 +169,27 @@ export declare const GATE_TYPE_KEYS: readonly string[];
  * so the two cannot disagree about what a gate type IS. `distinct` is held to it like any other.
  */
 export declare function gateTypeProblem(t: unknown): string | null;
+/**
+ * **A gate's RESOLVED route set, or why it has none** — ADR 0092 rule 3, the ONE function between a gate's
+ * routes and every reader of them: `FD-V41`'s count, `FD-R5`'s undeclared-route stop, the edge an edge with no
+ * `route` carries (`gateEdge`), and the wiring check's default and guarantee. A `StaticGateType` resolves to
+ * its own three members; a `DerivedGateType` to what its `routesFor` returns for THIS gate's settings.
+ *
+ * **Pure and TOTAL**: it never throws. Settings that are not a plain object, a `routesFor` that throws, and a
+ * set that fails `FD-V39`'s route clauses (`routeSetProblem`, the predicate a static type is held to) or
+ * carries a key beside the three are each a `{ problem }`. `routesFor` is handed a COPY of the settings, so a
+ * type writing into them moves nothing in the definition, and what it returned is copied and frozen, so a
+ * type mutating its own result later moves nothing a reader cached. Call it with the type `gateTypeProblem`
+ * accepted — the validator, the driver and the wiring check each do.
+ */
+export declare function routesOf(type: GateType, settings: unknown): Pick<StaticGateType, 'routes' | 'defaultRoute' | 'keyResolvedRoutes'> | {
+    readonly problem: string;
+};
 /**
  * **`distinct` — the one BUILT-IN gate type, and it is written against the public interface and nothing
  * else** (P24 decision 2): nothing in the validator, the wiring check or the driver names it; they read
- * `routes`, `defaultRoute`, `settingsSchema`, `keyResolvedRoutes` and `fn` off whatever type a gate names. It
- * keeps the FIRST
+ * the gate's route set through `routesOf`, and `settingsSchema`, `settingsProblem` and `fn`, off whatever type
+ * a gate names. A `StaticGateType` — its routes are the same for every gate (ADR 0092). It keeps the FIRST
  * branch to reach the gate per key and routes every later one with the same key to `duplicate`.
  *
  * - `first` (the DEFAULT) — the key has not been seen at this gate in this run;
@@ -178,8 +203,12 @@ export declare function gateTypeProblem(t: unknown): string | null;
  * key. Memory holds one entry per key seen; `fn` writes it and nothing else does. Its life is the RUN's —
  * one memory per gate, created empty with the driver and rebuilt by replay on resume (W93, `RN-R26`).
  */
-export declare const distinct: GateType;
-/** **The built-in gate types, by name** — `distinct` and nothing else (P24 Scope/Out: the interface ships, a second built-in does not). */
+export declare const distinct: StaticGateType;
+/**
+ * **The built-in gate types, by name** — `distinct` (P24), and since W154 `if` and `switch` (P32 decision 1), all
+ * three written against the public interface a consumer's type is. A consumer type named as any of them is refused,
+ * never merged (`NameCollision`, `FD-V39`).
+ */
 export declare const BUILT_IN_GATE_TYPES: Readonly<Record<string, GateType>>;
 /**
  * **Every gate type a flow may name: the built-ins, then the consumer's** — `Registry.gateTypes`' own
@@ -264,17 +293,28 @@ export declare function effectiveSettings(node: {
  */
 export declare function settingsProblem(schema: JsonSchema | undefined, defaults: Readonly<Record<string, unknown>> | undefined, settings: unknown): string | null;
 /**
- * **The one place `needs`' reference grammar is parsed** — `FD-V26`'s three forms,
+ * **The one place `needs`' reference grammar is parsed** — `FD-V26`'s five forms (`"."`, `"$payload"`, `"$item"`, `"n"`, `["n"]` — the two `$` forms since v0.44, `"$item"` composed since v0.45),
  * and `spec/flow-definition.md` section 3's table. `null` is *not a reference at
  * all*, which is what `FD-V26` reports; every other return is well formed and
  * `FD-V27`/`FD-V28` decide whether it is well AIMED.
  *
- * **`"."` and `"?"` are the only invented tokens in the grammar**, and both are safe
- * because they are outside `FD-V16`'s charset, so no node may ever be called `.` or
- * end in `?`.
+ * **The grammar's invented tokens are `"."`, `"?"` and — v0.44 — the whole `"$"` PREFIX**, and
+ * each is safe because it is outside `FD-V16`'s charset, so no node may ever be called `.`, end
+ * in `?` or begin with `$` (P38 fact 1). *(This read *"`"."` and `"?"` are the only invented
+ * tokens"* until W190.)* Two `$` tokens are references: **`"$payload"`** — the value the RUN
+ * entered with, from any node and any edge (v0.44,
+ * [ADR 0117](../../doc/decisions/0117-a-reference-may-name-what-reached-the-run.md)) — and
+ * **`"$item"`** — the item of the innermost map instance CONTAINING the reader, from any node or edge
+ * inside one (v0.45, P38 (c), [ADR 0118](../../doc/decisions/0118-a-map-instance-keeps-its-item-while-a-node-of-it-may-still-be-entered.md));
+ * parsed here since v0.44 so the union is one type for both (P38 (h)), and aimed by `FD-V49`. Every other `$`
+ * spelling — `["$payload"]`, `"$payload?"`, `"$other"` — is `null`, and `FD-V26` names the fix.
+ * **They are `form`s and not a flag**, and `node` is `null` on all three node-less forms, so a
+ * caller that reads `node === null` as *the `"."` form* reads `"$payload"` as `"."` in silence —
+ * **switch on `form`** (P38 fact 7, the reason the union is widened rather than `'self'` reused).
  * **On an EDGE the `"."` form is refused** — `FD-V26`s v0.12 clause — but that is the
  * CALLER`s rule: this function parses ONE grammar, and the two sites differ in what
- * they accept of it rather than in how it is read.
+ * they accept of it rather than in how it is read. *`"$payload"` and `"$item"` are NOT refused there*: a
+ * predicate has no `ctx.payload` and no `ctx.item`, so naming either is not redundant (P38 decision 3).
  *
  * **The `?` suffix is v0.13's, and it decides what happens when the target produced
  * NOTHING on this path rather than which outputs are named** —
@@ -289,6 +329,14 @@ export declare function referenceTarget(ref: unknown): {
     form: 'self';
     node: null;
     conditional: false;
+} | {
+    form: 'payload';
+    node: null;
+    conditional: false;
+} | {
+    form: 'item';
+    node: null;
+    conditional: false;
 } | {
     form: 'one' | 'all';
     node: string;

package/dist/types/src/definition/wiring.d.ts

@@ -60,6 +60,15 @@
  * `RT-R12` holds and this module loads no engine of its own. A witness is not a proof, and a
  * sample that passes is reported as *the sample passed*, never as *fits*.
  *
+ * **And a value the CALLER GIVES is not an arc at all** (v0.38,
+ * [P37](../../doc/plans/p37-a-runtime-is-its-registry.md) stop-and-ask (d),
+ * [W166](../../doc/work-items/w166-a-sample-the-caller-gives.md)): `givenVerdict` runs a task's transform
+ * ONCE on what the node RECEIVES — `$`, as given, no `needs` composed over it — and returns ONE verdict of
+ * shape `given`, with no producer and the source `'given'`, whatever arcs reach the node and on the ENTRY
+ * too. It reads no arrival, so a given value never reaches the record's or the composition's source
+ * aggregation (P37 fact 4) — and those are typed over the two sources a SCHEMA supplies, so it cannot.
+ * The evaluation is the arcs' own: `judgeTransform` below is the one both roads call.
+ *
  * **A GATE's arc carries what reached it REFINED by what its ROUTE guarantees, and a KEY PATH the
  * producer FORBIDS makes that arc `no`** — [ADR 0068](../../doc/decisions/0068-a-route-guarantees-what-its-type-declares-and-the-library-derives-it-from-the-key-path.md)
  * and its refusing half ([W99](../../doc/work-items/w99-what-a-route-guarantees.md),
@@ -70,19 +79,30 @@
  * states, one question over, **and with the same scope: a step the producer REQUIRES is not read as
  * never carried.** That scope is W100's, and it is what made `fits`'s `'is open there'` arm dead.
  *
+ * **An ASK is a PRODUCER and never a consumer** (v0.42, [W179](../../doc/work-items/w179-the-ask-node-in-the-definition.md),
+ * ADR 0108). What leaves it is the person's ANSWER, so the arc it sends carries its `answerSchema` exactly as a
+ * task's carries its worker's `outputSchema` — an edge, a branch's arrival at a join, a `needs` naming it — and an
+ * ask declaring none sends an `unchecked` arc naming the ask. What REACHES it is shown to a person and held to no
+ * schema (it runs no worker, so it has no `inputSchema`), so an arc into an ask gets no verdict, as an arc into a
+ * gate or a join gets none of its own.
+ *
  * Pure over data except the one `import()` of an adapter's worker half, which is async and is why
  * `checkWiring` returns a Promise; no `node:` import, no clock (`RT-R3`, `RT-R4`).
  */
 import { type JsonSchema } from './schema.js';
 import type { Edge, FlowDefinition, GateNode, Registry } from './types.js';
 import { type SampleSource } from './witness.js';
-/** The five shapes of *what a node receives* — `FD-C1`, `JP-R11`, `JP-R12`. */
-export type WiringShape = 'edge' | 'branch' | 'item' | 'record' | 'needs';
+/**
+ * The five shapes of *what a node receives* — `FD-C1`, `JP-R11`, `JP-R12` — **and `given`, which is
+ * not an arc** (v0.38, W166): the value a caller hands `tryTransform(…, { input })`. `checkWiring` never
+ * produces it. **BREAKING in 0.8.0**: a `switch` exhaustive over the five is not exhaustive over six.
+ */
+export type WiringShape = 'edge' | 'branch' | 'item' | 'record' | 'needs' | 'given';
 /** The five verdicts. */
 export type VerdictKind = 'fits' | 'no' | 'transform-passes' | 'transform-fails' | 'unchecked';
 /** The value a transformed arc was verified on, where it came from, and what came out. */
 export interface WiringSample {
-    /** Whether the producer side was a declared example or the generator's witness (Q301). */
+    /** Whether the producer side was a declared example or the generator's witness (Q301) — or, on a `given` verdict and only there, the value the caller gave (`'given'`, W166). */
     source: SampleSource;
     /** How many branches or items the sample had, where the producer is a region or a map (Q263). */
     arity?: number;
@@ -95,8 +115,12 @@ export interface WiringVerdict {
     /** The task node on the consuming side. */
     consumer: string;
     shape: WiringShape;
-    /** The task whose output arrives, the join whose record arrives, or the opener of the region the consumer sits in. */
-    producer: string;
+    /**
+     * The task — or, since v0.42, the ask — whose output arrives, the join whose record arrives, or the opener of the region the consumer sits in.
+     * **ABSENT on a `given` verdict, and present on every other** (v0.38, W166): a value the caller gave came from no
+     * node. **BREAKING in 0.8.0**: this was `string`.
+     */
+    producer?: string;
     /** For a `branch` or `item` arc: the fan-out or map the value passed through. */
     through?: string;
     kind: VerdictKind;
@@ -111,7 +135,7 @@ export interface WiringReport {
     /**
      * The tasks the run's PAYLOAD reaches with no worker in between — the entry task, or every branch
      * task of an entry region, recursively. No arc leads to them; `FD-R4` holds the payload to their
-     * input schemas at `start()`, once per run.
+     * input schemas at `start()`, once per run, except where a task declares a `transform` (ADR 0101, W170).
      */
     entry: string[];
 }
@@ -128,7 +152,7 @@ export interface WiringReport {
 export type WiringRegistry = Pick<Registry, 'workers' | 'nodeTypes' | 'languages' | 'gateTypes'>;
 /**
  * **Every value `P` admits is accepted by `C`** — P19 fact 3's relation, verbatim in shape, over
- * the twelve constraining keywords (`examples` is read by nothing, ADR 0056 rule 1). `'fits'` or
+ * the twelve constraining keywords (the five annotations are read by nothing — `examples`, ADR 0056 rule 1, and `title`, `description`, `readOnly` and `writeOnly`, ADR 0098). `'fits'` or
  * `'no'` with the reason, never a third answer. `path` is where in the two schemas the answer was
  * decided, as `findings` addresses a value.
  */
@@ -140,8 +164,10 @@ export declare function fits(P: JsonSchema, C: JsonSchema, path?: string): {
  * **The first task(s) a run's payload reaches with no worker in between** — the entry task, or the
  * branch tasks of an entry region, recursively; for a map, one per element of the array the
  * payload carries under `over`. `FD-R4`'s targets at `start()`; the driver composes each value
- * through the node's `needs` (a `"."` is the only reference an entry can carry) and holds it to the
- * task's worker `inputSchema`. ONE walk, two callers — the driver with the payload, and
+ * through the node's `needs` (an entry names no NODE, `FD-V27`: what it can carry is `"."` and, since v0.44,
+ * `"$payload"` — the payload this walk was handed, P38 (f) — and, since v0.45, `"$item"`: a target inside a map instance
+ * is that map's BRANCH ENTRY, so its value IS the instance's item and a `"$item"` key composes it, P38 (i)) and holds it to the
+ * task's worker `inputSchema` — the value the node RECEIVES — unless the task declares a `transform` (ADR 0101, W170). ONE walk, two callers — the driver with the payload, and
  * `checkWiring` with none for `WiringReport.entry` (W73's adequacy reader found a second walk
  * beside this one whose map arm nothing bound; there is one walk now, `entryWalk`).
  *
@@ -178,9 +204,31 @@ export interface WiringOptions {
     workerHalf?: Readonly<Record<string, WorkerCompile>>;
 }
 export declare function checkWiring(registry: WiringRegistry, flow: FlowDefinition, options?: WiringOptions): Promise<WiringReport>;
+/**
+ * **A value the CALLER GIVES, on one task node: its transform run ONCE on what the node RECEIVES, and ONE
+ * verdict** — v0.38, [P37](../../doc/plans/p37-a-runtime-is-its-registry.md) stop-and-ask (d)'s answer,
+ * [W166](../../doc/work-items/w166-a-sample-the-caller-gives.md). **PUBLIC SURFACE, new in 0.8.0**: `index.ts`
+ * re-exports every name of this module, so it is a root export, stated as one in `spec/flow-definition.md`
+ * v0.38 and `AGENTS.md` section 15. It is `tryTransform` on the node as the flow DECLARES it — `tryTransform`
+ * calls it on the copy that carries the candidate — and the two have ONE contract.
+ *
+ * `input` IS `$` — what the node receives, so no `needs` is composed over it and no arc is read: the verdict
+ * is the same whatever arcs reach the node, and the ENTRY node — which no arc reaches — gets one too. Its
+ * shape is `given`, it has NO `producer` and no `through`, and its sample's source is `'given'` and nothing
+ * else. The evaluation and the judgement are the arcs' own (`judgeTransform`): `transform-passes` where the
+ * result satisfies the consumer's `inputSchema`, `transform-fails` naming the finding where it does not or the
+ * error where the expression throws, `unchecked` for a language, type, worker or consumer schema the registry
+ * lacks — and for a node with NO transform, because there is nothing to run the value through: holding one
+ * value to a schema is `findings`'s question.
+ *
+ * **`undefined` is no input** (the spec's table, W166's conformity reader F1): with it the ARCS answer, exactly
+ * as `tryTransform` with no input — the node's verdicts from `checkWiring`, and `[]` on the entry. A node id
+ * that names no task returns `[]`.
+ */
+export declare function givenVerdict(registry: WiringRegistry, flow: FlowDefinition, nodeId: string, input: unknown, options?: WiringOptions): Promise<WiringVerdict[]>;
 /** One verdict as one line a person reads — the source of a sample always named (Q301). */
 export declare function describeVerdict(v: WiringVerdict): string;
 /** The verdict kinds, enumerated — what a report's `counts` is keyed by, bound to the spec's table by a test. */
 export declare const VERDICT_KINDS: readonly VerdictKind[];
-/** The arc shapes, enumerated. */
+/** The shapes, enumerated — the five arc shapes and `given` (W166), bound to the spec's arc table by a test. */
 export declare const WIRING_SHAPES: readonly WiringShape[];

package/dist/types/src/definition/witness.d.ts

@@ -26,14 +26,22 @@
 import type { JsonSchema } from './schema.js';
 /** The least value `schema` admits. */
 export declare function witness(schema: JsonSchema, path?: string): unknown;
-/** Where a sample came from — the word every verdict built on one carries (Q301). */
-export type SampleSource = 'example' | 'witness';
+/**
+ * Where a sample came from — the word every verdict built on one carries (Q301). **`'given'` since
+ * v0.38** ([P37](../../doc/plans/p37-a-runtime-is-its-registry.md) stop-and-ask (d),
+ * [W166](../../doc/work-items/w166-a-sample-the-caller-gives.md)): a value the CALLER handed
+ * `tryTransform(…, { input })` as what the node receives — never a schema's, so `sampleOf` below never
+ * returns it and an ARC's sample never carries it. **BREAKING in 0.8.0**: this was two values, and a
+ * `switch` exhaustive over two is not exhaustive over three.
+ */
+export type SampleSource = 'example' | 'witness' | 'given';
 /**
  * **The value a tool runs on for one schema, and which it was**: the FIRST declared example (ADR
  * 0056 rule 3), else the witness. A schema of `undefined` — a worker that declares none — has no
- * sample; the caller says UNCHECKED rather than inventing one.
+ * sample; the caller says UNCHECKED rather than inventing one. **Its source is one of the TWO a schema
+ * can supply, typed so** — `'given'` is the caller's and never a schema's (W166).
  */
 export declare function sampleOf(schema: JsonSchema | undefined): {
     value: unknown;
-    source: SampleSource;
+    source: Exclude<SampleSource, 'given'>;
 } | undefined;