@fluidgrids/workflows 2026.1027.0 → 2026.1028.1

package/dist/workflow-J-yYixny.d.cts

@@ -0,0 +1,444 @@
+import { a as Json, J as JsonObject, W as WorkflowInterface } from './types-BGoPzgcl.cjs';
+import { a6 as WorkflowInfoSnapshot, R as RetryPolicy, c as ActivityCancellationType, w as Headers, P as ParentClosePolicy, C as ChildCancellationType } from './types-CpBBjaGX.cjs';
+
+/**
+ * Node operation descriptors: what a builder call needs to know about the node
+ * it emits. Generated clients (`.fluidgrids/nodes.ts`) are lists of these;
+ * the built-in internal nodes and triggers ship here so `nodes.internal.*` and
+ * `triggers.*` work without a registry.
+ */
+
+/** A file reference in node inputs and outputs. */
+interface FileRef {
+    fileId: string;
+    name?: string;
+    mimeType?: string;
+    size?: number;
+}
+declare const OPERATION_TYPES: unique symbol;
+/** One node operation. `In` and `Out` type the arguments and the output. */
+interface Operation<In = Record<string, Json>, Out = Json> {
+    readonly kind: 'operation';
+    readonly nodeType: string;
+    /** Written as the node's `version` unless the call overrides it. */
+    readonly version?: string;
+    /** Written as the node's `operation_name` unless the call overrides it. */
+    readonly operation?: string;
+    readonly role?: 'trigger';
+    /** Type-level only; never present at run time. */
+    readonly [OPERATION_TYPES]?: {
+        input: In;
+        output: Out;
+    };
+}
+/** A trigger operation. */
+type TriggerOperation<In = Record<string, Json>, Out = Json> = Operation<In, Out> & {
+    readonly role: 'trigger';
+};
+/** Describe a node operation (generated clients call this). */
+declare function op<In = Record<string, Json>, Out = Json>(nodeType: string, version?: string, operation?: string): Operation<In, Out>;
+/** Describe a trigger operation (generated clients call this). */
+declare function trigger<In = Record<string, Json>, Out = Json>(nodeType: string, version?: string, operation?: string): TriggerOperation<In, Out>;
+/** True for a value made by {@link op} or {@link trigger}. */
+declare function isOperation(value: unknown): value is Operation<unknown, unknown>;
+/** Built-in trigger nodes (`wspace-workflow-svc` `triggers/manifests`). */
+declare const triggers: {
+    readonly api: TriggerOperation<Record<string, Json>, Json>;
+    readonly manual: TriggerOperation<Record<string, Json>, Json>;
+    readonly schedule: TriggerOperation<Record<string, Json>, Json>;
+    readonly webhook: TriggerOperation<Record<string, Json>, Json>;
+    readonly form: TriggerOperation<Record<string, Json>, Json>;
+    readonly errorTrigger: TriggerOperation<Record<string, Json>, Json>;
+    readonly workflowCall: TriggerOperation<Record<string, Json>, Json>;
+    readonly rssFeed: TriggerOperation<Record<string, Json>, Json>;
+    readonly httpPoll: TriggerOperation<Record<string, Json>, Json>;
+    readonly databasePoll: TriggerOperation<Record<string, Json>, Json>;
+    readonly emailImap: TriggerOperation<Record<string, Json>, Json>;
+    readonly fileUpload: TriggerOperation<Record<string, Json>, Json>;
+    readonly recordChange: TriggerOperation<Record<string, Json>, Json>;
+    readonly stateChange: TriggerOperation<Record<string, Json>, Json>;
+};
+/** Built-in internal nodes (`wspace-workflow-svc` `internalnodes/manifests`, plus the two IR v2 nodes). */
+declare const internalNodes: {
+    readonly merge: Operation<Record<string, Json>, Json>;
+    readonly if: Operation<Record<string, Json>, Json>;
+    readonly switch: Operation<Record<string, Json>, Json>;
+    readonly loop: Operation<Record<string, Json>, Json>;
+    readonly set: Operation<Record<string, Json>, Json>;
+    readonly filter: Operation<Record<string, Json>, Json>;
+    readonly aggregate: Operation<Record<string, Json>, Json>;
+    readonly wait: Operation<Record<string, Json>, Json>;
+    readonly noop: Operation<Record<string, Json>, Json>;
+    readonly code: Operation<Record<string, Json>, Json>;
+    readonly http: Operation<Record<string, Json>, Json>;
+    readonly transform: Operation<Record<string, Json>, Json>;
+    readonly validate: Operation<Record<string, Json>, Json>;
+    readonly log: Operation<Record<string, Json>, Json>;
+    readonly error: Operation<Record<string, Json>, Json>;
+    readonly subworkflow: Operation<Record<string, Json>, Json>;
+    readonly compareDatasets: Operation<Record<string, Json>, Json>;
+    readonly splitOut: Operation<Record<string, Json>, Json>;
+    readonly limit: Operation<Record<string, Json>, Json>;
+    readonly dedupe: Operation<Record<string, Json>, Json>;
+    readonly sort: Operation<Record<string, Json>, Json>;
+    readonly dataTable: Operation<Record<string, Json>, Json>;
+    readonly respondToWebhook: Operation<Record<string, Json>, Json>;
+    readonly sendAndWait: Operation<Record<string, Json>, Json>;
+    readonly codeWorkflow: Operation<Record<string, Json>, Json>;
+    readonly waitForSignal: Operation<Record<string, Json>, Json>;
+};
+/** Node clients that need no registry: the internal nodes and `custom()`. */
+declare const nodes: {
+    readonly internal: {
+        readonly merge: Operation<Record<string, Json>, Json>;
+        readonly if: Operation<Record<string, Json>, Json>;
+        readonly switch: Operation<Record<string, Json>, Json>;
+        readonly loop: Operation<Record<string, Json>, Json>;
+        readonly set: Operation<Record<string, Json>, Json>;
+        readonly filter: Operation<Record<string, Json>, Json>;
+        readonly aggregate: Operation<Record<string, Json>, Json>;
+        readonly wait: Operation<Record<string, Json>, Json>;
+        readonly noop: Operation<Record<string, Json>, Json>;
+        readonly code: Operation<Record<string, Json>, Json>;
+        readonly http: Operation<Record<string, Json>, Json>;
+        readonly transform: Operation<Record<string, Json>, Json>;
+        readonly validate: Operation<Record<string, Json>, Json>;
+        readonly log: Operation<Record<string, Json>, Json>;
+        readonly error: Operation<Record<string, Json>, Json>;
+        readonly subworkflow: Operation<Record<string, Json>, Json>;
+        readonly compareDatasets: Operation<Record<string, Json>, Json>;
+        readonly splitOut: Operation<Record<string, Json>, Json>;
+        readonly limit: Operation<Record<string, Json>, Json>;
+        readonly dedupe: Operation<Record<string, Json>, Json>;
+        readonly sort: Operation<Record<string, Json>, Json>;
+        readonly dataTable: Operation<Record<string, Json>, Json>;
+        readonly respondToWebhook: Operation<Record<string, Json>, Json>;
+        readonly sendAndWait: Operation<Record<string, Json>, Json>;
+        readonly codeWorkflow: Operation<Record<string, Json>, Json>;
+        readonly waitForSignal: Operation<Record<string, Json>, Json>;
+    };
+    /**
+     * Any node type, including ones the registry snapshot does not know. Typed
+     * as JSON in and out.
+     */
+    readonly custom: (nodeType: string, operation?: string, version?: string) => Operation<Record<string, Json>, Json>;
+};
+
+/**
+ * Signal, query and update definitions (spec 02 §4, 05). Signals work in Phase
+ * B; queries and updates can be declared (they appear in the interface) but
+ * custom handlers are Phase C.
+ */
+declare const PAYLOAD: unique symbol;
+interface SignalDefinition<Payload = unknown> {
+    readonly kind: 'signal';
+    readonly name: string;
+    readonly description?: string;
+    /** JSON Schema of the payload, written into the workflow interface. */
+    readonly schema?: Record<string, unknown>;
+    /** Type-level only. */
+    readonly [PAYLOAD]?: Payload;
+}
+interface QueryDefinition<Result = unknown, Args = unknown> {
+    readonly kind: 'query';
+    readonly name: string;
+    readonly description?: string;
+    readonly [PAYLOAD]?: {
+        result: Result;
+        args: Args;
+    };
+}
+interface UpdateDefinition<Args = unknown, Result = unknown> {
+    readonly kind: 'update';
+    readonly name: string;
+    readonly description?: string;
+    readonly [PAYLOAD]?: {
+        result: Result;
+        args: Args;
+    };
+}
+interface DefinitionOptions {
+    description?: string;
+    schema?: Record<string, unknown>;
+}
+/** Declare a signal. */
+declare function defineSignal<Payload = unknown>(name: string, options?: DefinitionOptions): SignalDefinition<Payload>;
+/** Declare a query. Handlers are Phase C; the declaration appears in the interface. */
+declare function defineQuery<Result = unknown, Args = unknown>(name: string, options?: {
+    description?: string;
+}): QueryDefinition<Result, Args>;
+/** Declare an update. Handlers are Phase C; the declaration appears in the interface. */
+declare function defineUpdate<Args = unknown, Result = unknown>(name: string, options?: {
+    description?: string;
+}): UpdateDefinition<Args, Result>;
+
+/** A duration: milliseconds, or a string such as `'30s'` or `'PT2H'`. */
+type Duration = number | string;
+/** Milliseconds of `value`; throws a `TypeError` naming `what` when it is not a duration. */
+declare function toMs(value: Duration, what?: string): number;
+
+/**
+ * The `WorkflowContext` a tier-2 workflow function receives (spec 02 §4). The
+ * runtime (`src/runtime/`) implements it; this module is types only.
+ */
+
+/** Options of `ctx.run`. */
+interface RunOptions<In> {
+    args: In;
+    /** Connection name, resolved by the service at `SCHEDULE_ACTIVITY`. */
+    connection?: string;
+    /** Default: 1 s, x2, at most 100 s, unlimited attempts (Temporal's policy). */
+    retry?: Partial<RetryPolicy>;
+    startToCloseTimeout?: Duration;
+    scheduleToCloseTimeout?: Duration;
+    scheduleToStartTimeout?: Duration;
+    heartbeatTimeout?: Duration;
+    cancellationType?: ActivityCancellationType;
+    /** 1 (highest) to 5; default 3. */
+    priority?: number;
+    /** Label in the History tab (at most 200 characters). */
+    summary?: string;
+    runOn?: string;
+    /** Overrides the operation name the descriptor carries. */
+    operation?: string;
+    /** Overrides the node version the descriptor carries. */
+    nodeVersion?: string;
+    headers?: Headers;
+}
+/** Options of `ctx.child` and `ctx.startChild` (11 §2.35). */
+interface ChildOptions {
+    input?: unknown;
+    /** `active` (default), `vN` or `@alias`. */
+    version?: string;
+    taskQueue?: string;
+    /** Default `TERMINATE` for `ctx.child`, `ABANDON` for `ctx.startChild` (DB13). */
+    parentClosePolicy?: ParentClosePolicy;
+    /**
+     * How the awaitable reacts when its scope is cancelled. Unset, it rejects at
+     * once and the child is left to the parent-close policy; set, the SDK sends
+     * a cancel request to the child (`REQUEST_CANCEL_EXTERNAL_RUN`, a parity
+     * command).
+     */
+    cancellationType?: ChildCancellationType;
+    workflowId?: string;
+    priority?: number;
+    summary?: string;
+    details?: string;
+    context?: JsonObject;
+    startDelay?: Duration;
+    executionTimeout?: Duration;
+    runTimeout?: Duration;
+    workflowTaskTimeout?: Duration;
+    headers?: Headers;
+}
+/** A started child run. */
+interface ChildHandle<Out = Json> {
+    readonly childId: string;
+    readonly runId: string;
+    result(): Promise<Out>;
+    signal<P>(signal: SignalDefinition<P> | string, payload?: P): Promise<void>;
+    /** Request cancellation of the child (parity command `REQUEST_CANCEL_EXTERNAL_RUN`). */
+    cancel(): Promise<void>;
+}
+/** A handle to another run of the workspace (11 §2.24). */
+interface ExternalRunHandle {
+    readonly runId: string;
+    signal<P>(signal: SignalDefinition<P> | string, payload?: P): Promise<void>;
+    /** Resolves when the cancel request was delivered, not when the run ends. */
+    cancel(): Promise<void>;
+}
+/** A cancellation scope (11 §2.24). */
+interface CancellationScope {
+    /** Rejects with `CancelledFailure` when the scope is cancelled. */
+    readonly cancelRequested: Promise<never>;
+    readonly consideredCancelled: boolean;
+    cancel(): void;
+}
+interface CancellationScopeOptions {
+    /** A durable timer that cancels the scope when it fires. */
+    timeout?: Duration;
+    nonCancellable?: boolean;
+}
+/** `ctx.cancellationScope(fn, options)` and `ctx.cancellationScope.current()`. */
+interface CancellationScopeFunction {
+    <T>(fn: (ctx: WorkflowContext) => Promise<T>, options?: CancellationScopeOptions): Promise<T>;
+    current(): CancellationScope;
+}
+/** What workflow code knows about its run. */
+interface WorkflowInfo extends WorkflowInfoSnapshot {
+    readonly workflowFn: string;
+    /** Events in the history when the current workflow task started. */
+    readonly historyLength: number;
+    /** UTF-8 bytes of their payloads. */
+    readonly historyBytes: number;
+    /** True from 80 % of the history cap; continue as new soon. */
+    readonly continueAsNewSuggested: boolean;
+    readonly isReplaying: boolean;
+}
+/** Logging from workflow code; lines are emitted once, never during replay. */
+interface WorkflowLogger {
+    debug(message: string, data?: Json): void;
+    info(message: string, data?: Json): void;
+    warn(message: string, data?: Json): void;
+    error(message: string, data?: Json): void;
+}
+/**
+ * Compensations run in reverse order, each in its own non-cancellable scope,
+ * so they still run after a cancel request. A compensation receives that
+ * scope's `ctx`; use it for every call after the compensation's first await.
+ */
+interface Saga {
+    add(compensation: (ctx: WorkflowContext) => unknown): void;
+    compensate(): Promise<void>;
+}
+interface ContinueAsNewOptions {
+    taskQueue?: string;
+    retry?: Partial<RetryPolicy>;
+    workflowTaskTimeout?: Duration;
+    context?: JsonObject;
+    versioningBehavior?: 'PINNED' | 'AUTO_UPGRADE';
+}
+/** A child target: a workflow key (graph or durable) or a tier-2 function of the same bundle. */
+type ChildTarget<Out> = string | DurableWorkflow<never, Out> | DurableWorkflow<Json, Out>;
+/** The context of a tier-2 workflow function. */
+interface WorkflowContext {
+    readonly info: WorkflowInfo;
+    readonly log: WorkflowLogger;
+    /** Run a canvas node operation as a durable activity (`SCHEDULE_ACTIVITY`, kind `node`). */
+    run<In, Out>(operation: Operation<In, Out>, options: RunOptions<In>): Promise<Out>;
+    /** A durable timer. */
+    sleep(duration: Duration, options?: {
+        summary?: string;
+    }): Promise<void>;
+    /** Resolves `true` once `predicate` holds after an event, or `false` when `timeout` passes first. */
+    condition(predicate: () => boolean, timeout?: Duration): Promise<boolean>;
+    /** The next signal of this name (buffered signals first). */
+    signalReceived<P>(signal: SignalDefinition<P> | string): Promise<P>;
+    /** Handle every signal of this name, buffered ones first. */
+    onSignal<P>(signal: SignalDefinition<P> | string, handler: (payload: P) => unknown): void;
+    /** Handle signals no other handler or waiter takes. */
+    setDefaultSignalHandler(handler: (name: string, payload: unknown) => unknown): void;
+    /** Start a child run and wait for its result. */
+    child<Out = Json>(target: ChildTarget<Out>, options?: ChildOptions): Promise<Out>;
+    /** Start a child run; resolves once it has started. */
+    startChild<Out = Json>(target: ChildTarget<Out>, options?: ChildOptions): Promise<ChildHandle<Out>>;
+    /** Signal another run of the workspace; resolves on delivery. */
+    signalRun<P>(runId: string, signal: SignalDefinition<P> | string, payload?: P): Promise<void>;
+    /** Signal the parent run. */
+    signalParent<P>(signal: SignalDefinition<P> | string, payload?: P): Promise<void>;
+    getRunHandle(runId: string): ExternalRunHandle;
+    /** Shorthand for `getRunHandle(runId).cancel()`. */
+    cancelRun(runId: string): Promise<void>;
+    /** The workflow clock (the task's start time), in epoch milliseconds. */
+    now(): number;
+    /** A deterministic random number in [0, 1), seeded per run. */
+    random(): number;
+    /** A deterministic version-4 UUID. */
+    uuid(): string;
+    /** Record a value once (`RECORD_SIDE_EFFECT`); replays return the recorded value. */
+    sideEffect<T extends Json>(fn: () => T): T;
+    /** In-place versioning (spec 06 §4). */
+    patched(patchId: string): boolean;
+    deprecatePatch(patchId: string): void;
+    /** Live Markdown status for the run page and `__metadata` (at most 20 KiB). */
+    setCurrentDetails(markdown: string): void;
+    /** Merge keys into the run's context (parity command `UPSERT_CONTEXT`). */
+    upsertContext(entries: JsonObject): void;
+    /** End this run and start a fresh history (parity command `CONTINUE_AS_NEW`). */
+    continueAsNew(input: unknown, options?: ContinueAsNewOptions): Promise<never>;
+    /**
+     * Run `fn` in a new cancellation scope. `fn` gets a `ctx` bound to the
+     * scope: use it inside `fn`. This outer `ctx` joins the scope only while
+     * `fn` runs synchronously; after an await it is back in its own scope, so
+     * concurrent branches never share a scope by accident.
+     */
+    readonly cancellationScope: CancellationScopeFunction;
+    /** `cancellationScope(fn, { nonCancellable: true })`; the same `ctx` rule applies. */
+    nonCancellable<T>(fn: (ctx: WorkflowContext) => Promise<T>): Promise<T>;
+    /**
+     * Run `fn` when the current scope is cancelled. An error thrown by `fn` is
+     * handled like an error thrown by the workflow; the other handlers still run.
+     */
+    onCancel(fn: () => void): void;
+    isCancellation(error: unknown): boolean;
+    saga(): Saga;
+    /** Resolves when no asynchronous signal handler is running; cancellation does not interrupt the wait. */
+    allHandlersFinished(): Promise<void>;
+    /** Phase C: user activities. Throws `PhaseCFeatureError`. */
+    activity(...args: unknown[]): Promise<never>;
+    /** Phase B parity: local activities. Throws `PhaseCFeatureError` in this release. */
+    localActivity(...args: unknown[]): Promise<never>;
+    /** Phase C: custom queries. Throws `PhaseCFeatureError`. */
+    handleQuery(...args: unknown[]): void;
+    /** Phase C: updates. Throws `PhaseCFeatureError`. */
+    handleUpdate(...args: unknown[]): void;
+    /** Phase C: search attributes. Throws `PhaseCFeatureError`. */
+    upsertSearchAttributes(...args: unknown[]): void;
+}
+
+/**
+ * `workflow()`: declare a tier-2 durable workflow function (spec 02 §4).
+ *
+ * The value is inert data plus the function: nothing runs at module load.
+ * `lower()` reads it to report `code.exports.workflows[exportName]`, and the
+ * runtime (`src/runtime/`) calls the function by export name inside a
+ * workflow task.
+ */
+
+declare const DURABLE_MARKER = "fluidgrids.durable-workflow";
+/**
+ * A payload schema: a JSON Schema object, or a schema library value with a
+ * `toJSONSchema()` method. Anything else (a zod schema without one, for
+ * example) types the code but leaves the interface without that schema.
+ */
+type SchemaLike = Record<string, unknown> | {
+    toJSONSchema(): unknown;
+};
+/** How a standalone tier-2 workflow starts (lowered to its trigger node). */
+type TriggerSpec = Operation<never, unknown> | Operation<Record<string, Json>, Json> | {
+    operation: Operation<never, unknown> | Operation<Record<string, Json>, Json>;
+    args?: JsonObject;
+    id?: string;
+};
+interface DurableWorkflowOptions {
+    /** Display name of the standalone workflow. */
+    title?: string;
+    description?: string;
+    input?: SchemaLike;
+    output?: SchemaLike;
+    signals?: ReadonlyArray<SignalDefinition<never> | SignalDefinition<unknown>>;
+    /** Declared only; handlers are Phase C. */
+    queries?: ReadonlyArray<QueryDefinition<unknown, unknown>>;
+    /** Declared only; handlers are Phase C. */
+    updates?: ReadonlyArray<UpdateDefinition<unknown, unknown>>;
+    /** Default `managed`. */
+    taskQueue?: string;
+    /** Lowers to the trigger node of the standalone workflow (default `internal:api`). */
+    trigger?: TriggerSpec;
+    /**
+     * Whether the function is a workflow of its own (07 §4): by default, when it
+     * declares a trigger or nothing in the project embeds it with `wf.codeWorkflow`.
+     */
+    standalone?: boolean;
+    /** Error classes that fail the run instead of the workflow task (11 §2.25). */
+    failureErrorTypes?: ReadonlyArray<abstract new (...args: never[]) => Error>;
+}
+/** A declared tier-2 workflow. */
+interface DurableWorkflow<In = Json, Out = Json> {
+    readonly __fluidgrids: typeof DURABLE_MARKER;
+    /** The workflow key it gets when it is standalone. */
+    readonly name: string;
+    readonly options: DurableWorkflowOptions;
+    readonly fn: (ctx: WorkflowContext, input: In) => Promise<Out>;
+}
+/** Declare a tier-2 workflow. `name` is its workflow key when it is standalone. */
+declare function workflow<In = Json, Out = Json>(name: string, options: DurableWorkflowOptions, fn: (ctx: WorkflowContext, input: In) => Promise<Out>): DurableWorkflow<In, Out>;
+declare function workflow<In = Json, Out = Json>(name: string, fn: (ctx: WorkflowContext, input: In) => Promise<Out>): DurableWorkflow<In, Out>;
+/** True for a value made by {@link workflow}. */
+declare function isDurableWorkflow(value: unknown): value is DurableWorkflow<never, unknown>;
+/** The JSON Schema of a {@link SchemaLike}, or undefined when it has none. */
+declare function jsonSchemaOf(schema: SchemaLike | undefined): JsonObject | undefined;
+/** The workflow `interface` (spec 01 §4) a tier-2 declaration describes. */
+declare function interfaceOf(definition: DurableWorkflow<never, unknown>): WorkflowInterface;
+
+export { trigger as A, triggers as B, type CancellationScope as C, DURABLE_MARKER as D, type ExternalRunHandle as E, type FileRef as F, workflow as G, type Operation as O, type QueryDefinition as Q, type RunOptions as R, type Saga as S, type TriggerOperation as T, type UpdateDefinition as U, type WorkflowContext as W, type CancellationScopeFunction as a, type CancellationScopeOptions as b, type ChildHandle as c, type ChildOptions as d, type ChildTarget as e, type ContinueAsNewOptions as f, type DefinitionOptions as g, type DurableWorkflow as h, type DurableWorkflowOptions as i, type Duration as j, type SchemaLike as k, type SignalDefinition as l, type TriggerSpec as m, type WorkflowInfo as n, type WorkflowLogger as o, defineQuery as p, defineSignal as q, defineUpdate as r, interfaceOf as s, internalNodes as t, isDurableWorkflow as u, isOperation as v, jsonSchemaOf as w, nodes as x, op as y, toMs as z };

package/fixtures/README.md

@@ -0,0 +1,128 @@
+# Shared round-trip fixtures
+
+These fixtures are the conformance suite for the tier-1 builders in
+`@fluidgrids/workflows` (TypeScript, this repo) and `fluidgrids-workflows`
+(Python, `fluidgrids-workflows-sdk-python`). Spec 03 §2 and spec 10 §2 require
+both SDKs to lower the same graph to byte-identical IR; this directory is where
+that is checked.
+
+Everything except `ir.json`, `index.json`, `registry.json` and
+`connections.json` is generated. Regenerate with `bun run check:fixtures --write`
+and check with `bun run check:fixtures --ruff` (CI does both checks).
+
+## Layout
+
+```
+fixtures/
+  index.json                 every fixture: name, source, what it covers
+  registry.json              node registry snapshot (9 store nodes from fluidgrids-nodes, contract fields only)
+  connections.json           connectionId -> { name, adapter }
+  .fluidgrids/nodes.ts       generated clients for registry.json (generateNodeClients(..., 'ts'))
+  .fluidgrids/nodes.py       generated clients for registry.json (generateNodeClients(..., 'py'))
+  <fixture>/
+    ir.json                  the input definition, as stored (not normalised)
+    expected.ir.json         normalizeDefinition(ir) with the workflow key and without authoring:
+                             what lowering the code must reproduce
+    fixture.json             { key, irHash, fidelity, items }
+    workflows/<key>.ts       lifted tier-1 TypeScript (Prettier, pinned options)
+    workflows/<key_snake>.py lifted tier-1 Python (Ruff-stable, line length 88)
+    workflows/<key>.layout.json  positions, sticky notes and meta.layout
+    .fluidgrids -> ../.fluidgrids   so each fixture directory is a complete project
+```
+
+## The conformance check
+
+For every fixture, lowering `workflows/<key_snake>.py` (with the layout sidecar
+and `connections.json` resolving connection names to `{ connectionId, adapter }`)
+must give a definition whose `irHash` equals `fixture.json` `irHash`. That is
+the same check the TypeScript suite runs on `workflows/<key>.ts`
+(`tests/fixtures.test.ts`, invariants 1 and 2 of spec 07 §5).
+
+`irHash` is `sha256:` + the SHA-256 of the RFC 8785 canonical JSON of the
+normalised definition without its `authoring` block. Provenance
+(`authoring.generator` is `sdk-ts` or `sdk-py`) is not content, so the two SDKs
+hash equally. Implement RFC 8785 exactly (keys sorted by UTF-16 code units,
+ECMAScript number formatting, no whitespace) and `normalizeDefinition` as
+`src/ir/normalize.ts` documents it.
+
+## The Python tier-1 surface the fixtures pin
+
+The Python files are printed from the same lift plan as the TypeScript files,
+so they define the Python builder's surface:
+
+- Imports: `from fluidgrids_workflows import and_, define_workflow, edge, expr, nodes, or_, triggers`
+  and `from fluidgrids_workflows.project import nodes as n`, which resolves to the
+  project's `.fluidgrids/nodes.py`.
+- `@define_workflow(key=..., name=..., description=..., config=..., interface=..., code=..., tags=..., meta=..., extra=...)`
+  on `def <key_snake>(wf):`.
+- Builder methods: `wf.trigger(op, ...)`, `wf.step(op, ...)` and the helpers
+  `if_`, `switch`, `loop`, `merge`, `wait`, `wait_for_signal`, `send_and_wait`,
+  `subworkflow`, `validate`, `compare_datasets`, `set`, `filter`, `aggregate`,
+  `split_out`, `limit`, `dedupe`, `sort`, `data_table`, `http`, `code`,
+  `transform`, `log`, `respond_to_webhook`, `stop_and_error`, `noop`; plus
+  `wf.ref(id)`, `wf.connect(source, target_id, **edge_options)`,
+  `wf.edge_order_is([...])`, `wf.json`, `wf.vars`, `wf.now`, `wf.execution`.
+- Keyword options are the TypeScript option names in snake_case: `id`, `label`,
+  `after`, `args`, `operation`, `version`, `connection`, `connections`,
+  `credentials`, `context`, `retry`, `timeout`, `on_error`, `error_config`,
+  `execution_settings`, `disabled`, `extra`, `condition`; edge options `id`,
+  `type`, `target_handle`, `label`, `data`, `mapping`, `extra`.
+- Option values are never converted: `args`, `retry`, `timeout`, `config`,
+  `extra` and every other dictionary keep the IR's own keys (`maxRetries`,
+  `channelId`, `link_names`), so they lower byte for byte. This is a deliberate
+  difference from the snake_case `retry` keys sketched in spec 03 §2.
+- `False` for `operation`, `version` and edge `id` / `type` means "write no
+  such field"; leaving the option out means "write the default" (the
+  descriptor's operation and version, the default edge id
+  `e-<source>-<target>[-<sourceHandle>][-<targetHandle>]`, edge type `deletable`).
+  Default ids are given after the callback returns: explicit ids are claimed
+  first, and a default id that is already taken gets `-2`, `-3`, … in
+  declaration order. Only a repeated explicit id is an error.
+- References: `node.output.a.b`, `["key"]` for keys that are not identifiers,
+  Python keywords, names starting with `_`, or reference method names, and
+  `[0]` for indices. They lower to `{{ $node["<id>"].item.<path> }}`;
+  `wf.json.x` lowers to `{{ $json.x }}`.
+- Conditions: `>=`, `>`, `<=`, `<`, `==`, `!=` on a reference, the methods
+  `contains`, `not_contains`, `starts_with`, `ends_with`, `matches` (operator
+  `regex`), `has_property`, `is_empty`, `is_not_empty`, `is_null`,
+  `is_not_null`, `is_true`, `is_false`, the generic `is_(operator[, value])`,
+  and `and_()` / `or_()`. A condition field is `WorkflowState.<id>.<path>` for a
+  node output and `output.<path>` for `wf.json`; one top-level rule is wrapped
+  in an `AND` group.
+- `expr("text ", ref, " more")` concatenates its parts; references render as
+  `{{ … }}`.
+- Typed handles: `if_` → `.true`, `.false`; `loop` → `.body`, `.done`;
+  `validate` → `.valid`, `.invalid`; `send_and_wait` → `.approved`,
+  `.declined`, `.timed_out`; `wait_for_signal` → `.received`, `.timed_out`;
+  `compare_datasets` → `.in_a_only`, `.in_b_only`, `.same`, `.different`;
+  `switch` → `.case("h")`, `.default`; any node → `.handle("h")`.
+- Generated clients: `op(node_type, version, operation, InputTypedDict, OutputTypedDict)`
+  and `trigger(...)` with the same arguments; `nodes.<group>.<operation>` and
+  `triggers.<group>.<operation>` use snake_case names (`n.slack.send_message`).
+  `fluidgrids_workflows` must export `op`, `trigger`, `Json` and `FileRef`.
+
+## Substitutions and corrections in the fixtures
+
+- **Real nodes only.** `store/clearbit` (example 02) is replaced by
+  `internal:http` calling the Clearbit API with a saved connection;
+  `store/warehouse-erp` (example 01) by `store/postgresql` `executeQuery`; the
+  `store/slack` `sendAndWait` operation (example 01), which does not exist, by
+  `internal:send-and-wait`. Store operations and argument names are the ones in
+  `registry.json` (for example Slack `channelId`, Stripe `createRefund`
+  `charge`).
+- **The expression form the workers evaluate.** The examples write
+  `{{ $node["x"].json.path }}`; the expression language exposes
+  `$node["x"].item` (there is no `.json`), so the fixtures use `.item`.
+- **The condition tree the IF node evaluates.** The examples write
+  `{ op, left, right }`; `internal:if` evaluates
+  `{ type: "group", combinator, children: [{ type: "rule", field, operator, value }] }`.
+- **Example 01** routed both `declined` and `timedOut` from `approve` to
+  `refund`. Two edges between the same pair of nodes are rejected by the
+  service validator, so the fixture keeps the `declined` edge only.
+- **Examples 03, 04 and 05** have no canvas JSON in the spec. Their `ir.json`
+  was produced by writing the example's tier-1 code against the real nodes and
+  lowering it once; the lifted `workflows/*.ts` is that code in canonical form.
+- **Doctor samples** (`fg-uc-*`, `doctor-*`) are the `definitionJson` of the
+  fluidgrids-doctor samples, with `key` added from the file name. They keep
+  their legacy `${…}` templates, `config` parameters and `store:<name>` types,
+  which is the point: they are what stored definitions look like.