@fluidgrids/workflows 0.0.0-stage → 2026.1027.0

package/dist/roundtrip/index.d.cts

@@ -0,0 +1,287 @@
+import { W as WorkflowDefinition, a as JsonObject } from '../types-Dr2Fn1Ax.cjs';
+import { m as LayoutSidecar } from '../assemble-BJo9TECS.cjs';
+import { N as NodeManifest } from '../manifest-Duf-gHdO.cjs';
+import { P as PathSegment } from '../expressions-DhHaqyar.cjs';
+import { E as Evaluator, a as EsbuildApi } from '../lower-DcOY8ux0.cjs';
+export { b as ESBUILD_VERSION, c as EVALUATION_GLOBAL, L as LowerError, d as LowerOptions, e as LowerResult, f as LoweredWorkflow, g as bundleProject, h as defaultEntries, l as lower } from '../lower-DcOY8ux0.cjs';
+import 'esbuild';
+import '../hash-CZkTXPCX.cjs';
+
+/**
+ * The language-neutral lift plan: a definition expressed as tier-1 builder
+ * calls. The TypeScript and Python renderers print the same plan, and
+ * {@link interpretPlan} runs it through the real builder so the lifter can
+ * prove, node by node, that the code it is about to print lowers back to the
+ * same IR.
+ */
+
+/** What a reference points at. */
+type PlanRefTarget = {
+    kind: 'node';
+    nodeId: string;
+} | {
+    kind: 'json' | 'vars' | 'now' | 'execution';
+};
+interface PlanRef {
+    target: PlanRefTarget;
+    path: PathSegment[];
+}
+/** A comparison method on a reference (`gte`, `isEmpty`, …) or the generic `is`. */
+interface PlanRule {
+    k: 'rule';
+    ref: PlanRef;
+    /** Builder method name; `is` takes the operator explicitly. */
+    method: string;
+    operator: string;
+    value?: string | number | boolean | null;
+    hasValue: boolean;
+}
+interface PlanGroup {
+    k: 'group';
+    combinator: 'and' | 'or';
+    children: Array<PlanRule | PlanGroup>;
+}
+/** The typed handle accessors of builder refs. */
+type HandleAccessor = {
+    kind: 'property';
+    name: string;
+} | {
+    kind: 'case';
+} | {
+    kind: 'generic';
+};
+type PlanExpr = {
+    k: 'literal';
+    value: string | number | boolean | null;
+} | {
+    k: 'object';
+    entries: Array<[string, PlanExpr]>;
+} | {
+    k: 'array';
+    items: PlanExpr[];
+} | {
+    k: 'ref';
+    ref: PlanRef;
+} | {
+    k: 'template';
+    parts: Array<{
+        text: string;
+    } | {
+        ref: PlanRef;
+    }>;
+} | PlanRule | PlanGroup | {
+    k: 'node';
+    nodeId: string;
+} | {
+    k: 'handle';
+    nodeId: string;
+    handle: string;
+    accessor: HandleAccessor;
+} | {
+    k: 'edge';
+    from: PlanExpr;
+    options: Array<[string, PlanExpr]>;
+};
+/** How a node's operation descriptor is written. */
+type PlanOperation = {
+    kind: 'trigger';
+    name: string;
+    nodeType: string;
+} | {
+    kind: 'internal';
+    name: string;
+    nodeType: string;
+} | {
+    kind: 'client';
+    group: string;
+    operationKey: string;
+    nodeType: string;
+    operation: string;
+    version?: string;
+    role?: 'trigger';
+} | {
+    kind: 'custom';
+    nodeType: string;
+    operation?: string;
+    version?: string;
+};
+interface PlanNodeStatement {
+    kind: 'node';
+    nodeId: string;
+    /** Builder method (`trigger`, `step`, `if`, `loop`, …). */
+    method: string;
+    /** Present for `trigger` and `step`. */
+    operation?: PlanOperation;
+    options: Array<[string, PlanExpr]>;
+}
+interface PlanConnectStatement {
+    kind: 'connect';
+    from: PlanExpr;
+    to: string;
+    options: Array<[string, PlanExpr]>;
+}
+interface PlanEdgeOrderStatement {
+    kind: 'edgeOrder';
+    /** Edge ids, or declaration positions for edges without an id. */
+    ids: Array<string | number>;
+}
+type PlanStatement = PlanNodeStatement | PlanConnectStatement | PlanEdgeOrderStatement;
+interface LiftPlan {
+    key: string;
+    workflowOptions: Array<[string, PlanExpr]>;
+    statements: PlanStatement[];
+}
+
+/** Fidelity report types (spec 07 §2). */
+/**
+ * The documented item kinds:
+ * - `expression-verbatim`: a `{{ … }}` expression kept as a string, not typed;
+ * - `legacy-syntax`: a `${…}` template, an edge mapping or legacy credentials kept verbatim;
+ * - `unknown-node`: a node type or operation the registry snapshot does not know, written as `nodes.custom()`;
+ * - `connection-id-only`: a connection with no name, kept as its id;
+ * - `raw-node`: a node written in its exact form (`nodes.custom()` plus `extra`);
+ * - `layout-omitted`, `pinned-data-omitted`: left out by the export options (lossy);
+ * - `key-added`: the definition had no `key`; the workflow key was written;
+ * - `roundtrip-mismatch` / `lowering-failed`: lowering the code did not reproduce the IR (lossy).
+ */
+type FidelityItemKind = 'expression-verbatim' | 'legacy-syntax' | 'unknown-node' | 'connection-id-only' | 'raw-node' | 'layout-omitted' | 'pinned-data-omitted' | 'key-added' | 'roundtrip-mismatch' | 'lowering-failed';
+interface FidelityItem {
+    nodeId?: string;
+    path?: string;
+    kind: FidelityItemKind;
+    detail: string;
+}
+interface FidelityReport {
+    level: 'lossless' | 'lossy';
+    items: FidelityItem[];
+}
+
+declare class LiftError extends Error {
+    constructor(message: string);
+}
+interface PlanOptions {
+    /** Workflow key when the definition has none. */
+    workflowKey?: string;
+    /** Registry snapshot for typed node clients. */
+    registry?: readonly NodeManifest[];
+    /** connectionId → connection name. */
+    connectionNames?: Readonly<Record<string, string>>;
+}
+
+/** One file of an export. */
+interface ExportedFile {
+    path: string;
+    contentType: string;
+    content: string;
+}
+interface LiftHeader {
+    workflowKey?: string;
+    version?: string;
+    irHash?: string;
+    exportedAt?: string;
+    registrySnapshot?: string;
+}
+interface LiftOptions extends PlanOptions {
+    /** Write the layout sidecar. Default true; without it positions are lost (lossy). */
+    includeLayout?: boolean;
+    /** Write pinned data to `workflows/<key>.pinned.json` (TEST only). Default false. */
+    includePinnedData?: boolean;
+    /** Header comment fields. */
+    header?: LiftHeader;
+}
+/** A definition prepared for printing. */
+interface PreparedLift {
+    /** What lowering the code must reproduce: the normalised definition (with its key). */
+    reference: WorkflowDefinition;
+    plan: LiftPlan;
+    items: FidelityItem[];
+    layout?: LayoutSidecar;
+    pinnedData?: JsonObject;
+    registry: readonly NodeManifest[];
+    clientPy: (nodeType: string, operation: string) => string;
+    usesClients: boolean;
+}
+interface LiftResult {
+    files: ExportedFile[];
+    items: FidelityItem[];
+    /** The definition the code lowers to when fidelity is lossless. */
+    reference: WorkflowDefinition;
+}
+/** Normalise, plan and verify a definition for lifting. */
+declare function prepareLift(definition: unknown, options?: LiftOptions): PreparedLift;
+/** Lift to a tier-1 TypeScript project fragment. */
+declare function liftToTypeScript(definition: unknown, options?: LiftOptions): Promise<LiftResult>;
+/** Lift to a tier-1 Python project fragment. */
+declare function liftToPython(definition: unknown, options?: LiftOptions): Promise<LiftResult>;
+
+interface NodeVmEvaluatorOptions {
+    /** Wall-clock budget for evaluating the bundle. Default 5000 ms. */
+    timeoutMs?: number;
+}
+declare function createNodeVmEvaluator(options?: NodeVmEvaluatorOptions): Evaluator;
+
+interface ExportCodeOptions extends LiftOptions {
+    format: 'TYPESCRIPT' | 'PYTHON';
+    esbuild?: EsbuildApi;
+    evaluator?: Evaluator;
+}
+interface ExportCodeResult {
+    format: 'TYPESCRIPT' | 'PYTHON';
+    files: ExportedFile[];
+    fidelity: FidelityReport;
+    /** `irHash` of the exported definition. */
+    irHash: string;
+}
+/** Lower lifted TypeScript files and compare with the reference IR. */
+declare function checkFidelity(files: readonly ExportedFile[], reference: unknown, items: readonly FidelityItem[], options?: {
+    esbuild?: EsbuildApi;
+    evaluator?: Evaluator;
+    connectionNames?: Readonly<Record<string, string>>;
+}): Promise<FidelityReport>;
+/** Export a definition as TypeScript or Python files with a computed fidelity report. */
+declare function exportWorkflowCode(definition: unknown, options: ExportCodeOptions): Promise<ExportCodeResult>;
+
+/** Prettier options for lifted TypeScript. Part of the output contract: changing them changes every export. */
+declare const TS_FORMAT_OPTIONS: {
+    readonly parser: "typescript";
+    readonly printWidth: 100;
+    readonly singleQuote: true;
+    readonly trailingComma: "all";
+    readonly semi: true;
+    readonly tabWidth: 2;
+    readonly useTabs: false;
+    readonly bracketSpacing: true;
+    readonly arrowParens: "always";
+};
+/** Import path of the generated clients, relative to `workflows/<key>.ts`. */
+declare const TS_NODES_IMPORT = "../.fluidgrids/nodes";
+
+declare const PY_SDK_MODULE = "fluidgrids_workflows";
+declare const PY_PROJECT_MODULE = "fluidgrids_workflows.project";
+
+/**
+ * A small Python printer whose output `ruff format` (Black style, line length
+ * 88) leaves unchanged, so the service can emit Python without running Ruff
+ * (decision D1).
+ *
+ * The rules are Black's for the expression shapes the lifter produces (calls,
+ * keyword arguments, dicts, lists, subscripts, comparisons, attribute chains,
+ * string and number literals):
+ *
+ * 1. A line that fits in 88 columns stays on one line, without a trailing comma.
+ * 2. Otherwise the last bracket pair on the line is split. If the bracket's
+ *    contents fit on one line at the next indent, they go there with no
+ *    trailing comma ("hugging" the brackets).
+ * 3. Otherwise, with two or more elements, every element goes on its own line
+ *    with a trailing comma, and each element line is formatted recursively.
+ *    A single element is formatted recursively on its own line, without a
+ *    trailing comma.
+ * 4. Import lists always split one name per line with a trailing comma.
+ * 5. A too-long `name = <atom>` gets its right-hand side wrapped in
+ *    parentheses when the atom then fits.
+ *
+ * The fixture suite runs `ruff format --check` over every generated file.
+ */
+declare const PY_LINE_LENGTH = 88;
+
+export { EsbuildApi, Evaluator, type ExportCodeOptions, type ExportCodeResult, type ExportedFile, type FidelityItem, type FidelityItemKind, type FidelityReport, LiftError, type LiftHeader, type LiftOptions, type LiftResult, type NodeVmEvaluatorOptions, PY_LINE_LENGTH, PY_PROJECT_MODULE, PY_SDK_MODULE, type PlanOptions, type PreparedLift, TS_FORMAT_OPTIONS, TS_NODES_IMPORT, checkFidelity, createNodeVmEvaluator, exportWorkflowCode, liftToPython, liftToTypeScript, prepareLift };

package/dist/roundtrip/index.d.ts

@@ -0,0 +1,287 @@
+import { W as WorkflowDefinition, a as JsonObject } from '../types-Dr2Fn1Ax.js';
+import { m as LayoutSidecar } from '../assemble-DMOuaxRI.js';
+import { N as NodeManifest } from '../manifest-Bp9ZJlav.js';
+import { P as PathSegment } from '../expressions-DhHaqyar.js';
+import { E as Evaluator, a as EsbuildApi } from '../lower-Dw5grNrI.js';
+export { b as ESBUILD_VERSION, c as EVALUATION_GLOBAL, L as LowerError, d as LowerOptions, e as LowerResult, f as LoweredWorkflow, g as bundleProject, h as defaultEntries, l as lower } from '../lower-Dw5grNrI.js';
+import 'esbuild';
+import '../hash-CZkTXPCX.js';
+
+/**
+ * The language-neutral lift plan: a definition expressed as tier-1 builder
+ * calls. The TypeScript and Python renderers print the same plan, and
+ * {@link interpretPlan} runs it through the real builder so the lifter can
+ * prove, node by node, that the code it is about to print lowers back to the
+ * same IR.
+ */
+
+/** What a reference points at. */
+type PlanRefTarget = {
+    kind: 'node';
+    nodeId: string;
+} | {
+    kind: 'json' | 'vars' | 'now' | 'execution';
+};
+interface PlanRef {
+    target: PlanRefTarget;
+    path: PathSegment[];
+}
+/** A comparison method on a reference (`gte`, `isEmpty`, …) or the generic `is`. */
+interface PlanRule {
+    k: 'rule';
+    ref: PlanRef;
+    /** Builder method name; `is` takes the operator explicitly. */
+    method: string;
+    operator: string;
+    value?: string | number | boolean | null;
+    hasValue: boolean;
+}
+interface PlanGroup {
+    k: 'group';
+    combinator: 'and' | 'or';
+    children: Array<PlanRule | PlanGroup>;
+}
+/** The typed handle accessors of builder refs. */
+type HandleAccessor = {
+    kind: 'property';
+    name: string;
+} | {
+    kind: 'case';
+} | {
+    kind: 'generic';
+};
+type PlanExpr = {
+    k: 'literal';
+    value: string | number | boolean | null;
+} | {
+    k: 'object';
+    entries: Array<[string, PlanExpr]>;
+} | {
+    k: 'array';
+    items: PlanExpr[];
+} | {
+    k: 'ref';
+    ref: PlanRef;
+} | {
+    k: 'template';
+    parts: Array<{
+        text: string;
+    } | {
+        ref: PlanRef;
+    }>;
+} | PlanRule | PlanGroup | {
+    k: 'node';
+    nodeId: string;
+} | {
+    k: 'handle';
+    nodeId: string;
+    handle: string;
+    accessor: HandleAccessor;
+} | {
+    k: 'edge';
+    from: PlanExpr;
+    options: Array<[string, PlanExpr]>;
+};
+/** How a node's operation descriptor is written. */
+type PlanOperation = {
+    kind: 'trigger';
+    name: string;
+    nodeType: string;
+} | {
+    kind: 'internal';
+    name: string;
+    nodeType: string;
+} | {
+    kind: 'client';
+    group: string;
+    operationKey: string;
+    nodeType: string;
+    operation: string;
+    version?: string;
+    role?: 'trigger';
+} | {
+    kind: 'custom';
+    nodeType: string;
+    operation?: string;
+    version?: string;
+};
+interface PlanNodeStatement {
+    kind: 'node';
+    nodeId: string;
+    /** Builder method (`trigger`, `step`, `if`, `loop`, …). */
+    method: string;
+    /** Present for `trigger` and `step`. */
+    operation?: PlanOperation;
+    options: Array<[string, PlanExpr]>;
+}
+interface PlanConnectStatement {
+    kind: 'connect';
+    from: PlanExpr;
+    to: string;
+    options: Array<[string, PlanExpr]>;
+}
+interface PlanEdgeOrderStatement {
+    kind: 'edgeOrder';
+    /** Edge ids, or declaration positions for edges without an id. */
+    ids: Array<string | number>;
+}
+type PlanStatement = PlanNodeStatement | PlanConnectStatement | PlanEdgeOrderStatement;
+interface LiftPlan {
+    key: string;
+    workflowOptions: Array<[string, PlanExpr]>;
+    statements: PlanStatement[];
+}
+
+/** Fidelity report types (spec 07 §2). */
+/**
+ * The documented item kinds:
+ * - `expression-verbatim`: a `{{ … }}` expression kept as a string, not typed;
+ * - `legacy-syntax`: a `${…}` template, an edge mapping or legacy credentials kept verbatim;
+ * - `unknown-node`: a node type or operation the registry snapshot does not know, written as `nodes.custom()`;
+ * - `connection-id-only`: a connection with no name, kept as its id;
+ * - `raw-node`: a node written in its exact form (`nodes.custom()` plus `extra`);
+ * - `layout-omitted`, `pinned-data-omitted`: left out by the export options (lossy);
+ * - `key-added`: the definition had no `key`; the workflow key was written;
+ * - `roundtrip-mismatch` / `lowering-failed`: lowering the code did not reproduce the IR (lossy).
+ */
+type FidelityItemKind = 'expression-verbatim' | 'legacy-syntax' | 'unknown-node' | 'connection-id-only' | 'raw-node' | 'layout-omitted' | 'pinned-data-omitted' | 'key-added' | 'roundtrip-mismatch' | 'lowering-failed';
+interface FidelityItem {
+    nodeId?: string;
+    path?: string;
+    kind: FidelityItemKind;
+    detail: string;
+}
+interface FidelityReport {
+    level: 'lossless' | 'lossy';
+    items: FidelityItem[];
+}
+
+declare class LiftError extends Error {
+    constructor(message: string);
+}
+interface PlanOptions {
+    /** Workflow key when the definition has none. */
+    workflowKey?: string;
+    /** Registry snapshot for typed node clients. */
+    registry?: readonly NodeManifest[];
+    /** connectionId → connection name. */
+    connectionNames?: Readonly<Record<string, string>>;
+}
+
+/** One file of an export. */
+interface ExportedFile {
+    path: string;
+    contentType: string;
+    content: string;
+}
+interface LiftHeader {
+    workflowKey?: string;
+    version?: string;
+    irHash?: string;
+    exportedAt?: string;
+    registrySnapshot?: string;
+}
+interface LiftOptions extends PlanOptions {
+    /** Write the layout sidecar. Default true; without it positions are lost (lossy). */
+    includeLayout?: boolean;
+    /** Write pinned data to `workflows/<key>.pinned.json` (TEST only). Default false. */
+    includePinnedData?: boolean;
+    /** Header comment fields. */
+    header?: LiftHeader;
+}
+/** A definition prepared for printing. */
+interface PreparedLift {
+    /** What lowering the code must reproduce: the normalised definition (with its key). */
+    reference: WorkflowDefinition;
+    plan: LiftPlan;
+    items: FidelityItem[];
+    layout?: LayoutSidecar;
+    pinnedData?: JsonObject;
+    registry: readonly NodeManifest[];
+    clientPy: (nodeType: string, operation: string) => string;
+    usesClients: boolean;
+}
+interface LiftResult {
+    files: ExportedFile[];
+    items: FidelityItem[];
+    /** The definition the code lowers to when fidelity is lossless. */
+    reference: WorkflowDefinition;
+}
+/** Normalise, plan and verify a definition for lifting. */
+declare function prepareLift(definition: unknown, options?: LiftOptions): PreparedLift;
+/** Lift to a tier-1 TypeScript project fragment. */
+declare function liftToTypeScript(definition: unknown, options?: LiftOptions): Promise<LiftResult>;
+/** Lift to a tier-1 Python project fragment. */
+declare function liftToPython(definition: unknown, options?: LiftOptions): Promise<LiftResult>;
+
+interface NodeVmEvaluatorOptions {
+    /** Wall-clock budget for evaluating the bundle. Default 5000 ms. */
+    timeoutMs?: number;
+}
+declare function createNodeVmEvaluator(options?: NodeVmEvaluatorOptions): Evaluator;
+
+interface ExportCodeOptions extends LiftOptions {
+    format: 'TYPESCRIPT' | 'PYTHON';
+    esbuild?: EsbuildApi;
+    evaluator?: Evaluator;
+}
+interface ExportCodeResult {
+    format: 'TYPESCRIPT' | 'PYTHON';
+    files: ExportedFile[];
+    fidelity: FidelityReport;
+    /** `irHash` of the exported definition. */
+    irHash: string;
+}
+/** Lower lifted TypeScript files and compare with the reference IR. */
+declare function checkFidelity(files: readonly ExportedFile[], reference: unknown, items: readonly FidelityItem[], options?: {
+    esbuild?: EsbuildApi;
+    evaluator?: Evaluator;
+    connectionNames?: Readonly<Record<string, string>>;
+}): Promise<FidelityReport>;
+/** Export a definition as TypeScript or Python files with a computed fidelity report. */
+declare function exportWorkflowCode(definition: unknown, options: ExportCodeOptions): Promise<ExportCodeResult>;
+
+/** Prettier options for lifted TypeScript. Part of the output contract: changing them changes every export. */
+declare const TS_FORMAT_OPTIONS: {
+    readonly parser: "typescript";
+    readonly printWidth: 100;
+    readonly singleQuote: true;
+    readonly trailingComma: "all";
+    readonly semi: true;
+    readonly tabWidth: 2;
+    readonly useTabs: false;
+    readonly bracketSpacing: true;
+    readonly arrowParens: "always";
+};
+/** Import path of the generated clients, relative to `workflows/<key>.ts`. */
+declare const TS_NODES_IMPORT = "../.fluidgrids/nodes";
+
+declare const PY_SDK_MODULE = "fluidgrids_workflows";
+declare const PY_PROJECT_MODULE = "fluidgrids_workflows.project";
+
+/**
+ * A small Python printer whose output `ruff format` (Black style, line length
+ * 88) leaves unchanged, so the service can emit Python without running Ruff
+ * (decision D1).
+ *
+ * The rules are Black's for the expression shapes the lifter produces (calls,
+ * keyword arguments, dicts, lists, subscripts, comparisons, attribute chains,
+ * string and number literals):
+ *
+ * 1. A line that fits in 88 columns stays on one line, without a trailing comma.
+ * 2. Otherwise the last bracket pair on the line is split. If the bracket's
+ *    contents fit on one line at the next indent, they go there with no
+ *    trailing comma ("hugging" the brackets).
+ * 3. Otherwise, with two or more elements, every element goes on its own line
+ *    with a trailing comma, and each element line is formatted recursively.
+ *    A single element is formatted recursively on its own line, without a
+ *    trailing comma.
+ * 4. Import lists always split one name per line with a trailing comma.
+ * 5. A too-long `name = <atom>` gets its right-hand side wrapped in
+ *    parentheses when the atom then fits.
+ *
+ * The fixture suite runs `ruff format --check` over every generated file.
+ */
+declare const PY_LINE_LENGTH = 88;
+
+export { EsbuildApi, Evaluator, type ExportCodeOptions, type ExportCodeResult, type ExportedFile, type FidelityItem, type FidelityItemKind, type FidelityReport, LiftError, type LiftHeader, type LiftOptions, type LiftResult, type NodeVmEvaluatorOptions, PY_LINE_LENGTH, PY_PROJECT_MODULE, PY_SDK_MODULE, type PlanOptions, type PreparedLift, TS_FORMAT_OPTIONS, TS_NODES_IMPORT, checkFidelity, createNodeVmEvaluator, exportWorkflowCode, liftToPython, liftToTypeScript, prepareLift };