@fluidgrids/workflows 2026.1027.0 → 2026.1028.1

package/README.md

@@ -1,18 +1,23 @@
 # @fluidgrids/workflows
 
-Author [FluidGrids](https://fluidgrids.ai) workflows as code. This package is
-Phase A of the code-first workflows spec set (BOFF-9902 / BOFF-9904,
-`fluidgrids-specs/product/specs/code-first/`):
+Author [FluidGrids](https://fluidgrids.ai) workflows as code. This package
+implements Phases A and B of the code-first workflows spec set (BOFF-9902,
+BOFF-9904, BOFF-9905; `fluidgrids-specs/product/specs/code-first/`):
 
 - the workflow IR, schema version 2: types, JSON Schema 2020-12, normalisation,
   validation, hashing, diff, interface derivation and the export envelope;
 - the tier-1 graph builder: TypeScript that constructs a canvas workflow;
+- tier-2 durable workflow functions (`workflow()`), executed by replay;
+- the durable-function contract shared with the service, the workers and the
+  Python SDK: the runtime ABI, the history, command and task JSON Schemas, the
+  command-to-event state machine, the retry policy and the activity allow-list;
+- the QuickJS workflow task runner, bundles with vendored pure-ESM
+  dependencies and the source archive;
+- a test environment, replay and the replay conformance fixtures;
 - lift (IR to TypeScript or Python) and lower (TypeScript to IR), with a
   fidelity report computed by actually lowering the code;
 - typed node clients generated from a node registry snapshot.
 
-Durable (tier-2) workflow functions are Phase B and are not in this package yet.
-
 ## Install
 
 ```bash
@@ -21,14 +26,18 @@ bun add @fluidgrids/workflows
 
 ## Entry points
 
-| Import                                           | Contents                                                                                                                                          | Runs in                                   |
-| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
-| `@fluidgrids/workflows`                          | `defineWorkflow`, `triggers`, `nodes`, `edge`, `expr`, `and`, `or`, `op`, `trigger`, `toIR`                                                       | anywhere; also bundled into workflow code |
-| `@fluidgrids/workflows/ir`                       | IR v2 types, `IR_V2_SCHEMA`, `normalizeDefinition`, `validate`, `irHash`, `canonicalJson`, `diffDefinitions`, `deriveInterface`, envelope helpers | anywhere, browser included                |
-| `@fluidgrids/workflows/roundtrip`                | `liftToTypeScript`, `liftToPython`, `lower`, `exportWorkflowCode`, `checkFidelity`                                                                | Node or Bun                               |
-| `@fluidgrids/workflows/codegen`                  | `generateNodeClients(manifests, 'ts' \| 'py')`                                                                                                    | anywhere                                  |
-| `@fluidgrids/workflows/quickjs`                  | `createQuickJSEvaluator()` for lowering untrusted code                                                                                            | Node or Bun                               |
-| `@fluidgrids/workflows/schema/ir-v2.schema.json` | the JSON Schema                                                                                                                                   | data                                      |
+| Import                                       | Contents                                                                                                                                                                                                                                         | Runs in                                   |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |
+| `@fluidgrids/workflows`                      | `defineWorkflow`, `triggers`, `nodes`, `edge`, `expr`, `and`, `or`, `op`, `trigger`, `toIR`; `workflow`, `defineSignal`, `defineQuery`, `defineUpdate`, the failure classes                                                                      | anywhere; also bundled into workflow code |
+| `@fluidgrids/workflows/history`              | `EVENT_TYPES`, `COMMAND_TYPES`, `TASK_FAILURE_CAUSES`, the JSON Schemas, `validateCommands`, `eventsForCommands`, `projectRunState`, `splitActivations`, `computeRetryDelay`, `ACTIVITY_NODE_ALLOWLIST`, `assertActivityNodeType`, history files | Node or Bun                               |
+| `@fluidgrids/workflows/runtime`              | the runtime ABI (`createWorkflowRuntime`, `installWorkflowRuntime`), the scheduler, the determinism shims                                                                                                                                        | anywhere; bundled into workflow code      |
+| `@fluidgrids/workflows/testing`              | `TestWorkflowEnvironment`, `replay`, `assertHistory`, `expectIR`, `simulate`, the `vm` task runner                                                                                                                                               | Node or Bun                               |
+| `@fluidgrids/workflows/ir`                   | IR v2 types, `IR_V2_SCHEMA`, `normalizeDefinition`, `validate`, `irHash`, `canonicalJson`, `diffDefinitions`, `deriveInterface`, envelope helpers                                                                                                | anywhere, browser included                |
+| `@fluidgrids/workflows/roundtrip`            | `liftToTypeScript`, `liftToPython`, `lower`, `exportWorkflowCode`, `checkFidelity`, `buildBundle`, `vendorDependencies`, `packSources`, `unpackSources`                                                                                          | Node or Bun                               |
+| `@fluidgrids/workflows/codegen`              | `generateNodeClients(manifests, 'ts' \| 'py')`                                                                                                                                                                                                   | anywhere                                  |
+| `@fluidgrids/workflows/quickjs`              | `createQuickJSEvaluator()` for lowering untrusted code, `createWorkflowTaskRunner()` for workflow tasks                                                                                                                                          | Node or Bun                               |
+| `@fluidgrids/workflows/schema/*.schema.json` | `ir-v2`, `run-event`, `workflow-command`, `workflow-task`, `history-file`                                                                                                                                                                        | data                                      |
+| `@fluidgrids/workflows/fixtures/histories/*` | the replay conformance histories                                                                                                                                                                                                                 | data                                      |
 
 ## Tier 1: the graph builder
 
@@ -79,8 +88,16 @@ calls, so the same source always gives the same IR.
   becomes `{{ $json.x }}`. Comparisons (`gte`, `eq`, `contains`, `isEmpty`, …,
   `and`, `or`) become the condition tree `internal:if` evaluates.
 - `connection: 'name'` resolves to a connection id when the workflow is pushed.
+- Lowering must not read the clock or a random source while the workflow is
+  defined: `Date.now()`, `new Date()` / `Date()` without arguments,
+  `Math.random()`, `crypto.getRandomValues()` / `crypto.randomUUID()` and an
+  argument-less `Intl.DateTimeFormat` `format()` throw a `DeterminismViolation`
+  error in both evaluators. Use `wf.now` and other references for run-time values.
 - Positions come from the layout sidecar `workflows/<key>.layout.json`, or the
   automatic layout the AI draft generator uses.
+- An edge without an explicit `id` gets `e-<source>-<target>[-<sourceHandle>][-<targetHandle>]`.
+  Ids may contain `-`, so two edges can share that default; the later ones get
+  `-2`, `-3`, … in declaration order. Only a repeated explicit id is an error.
 - `edge(source, { id, type, targetHandle, label, mapping, extra })`,
   `wf.connect`, `wf.edgeOrderIs` and the `extra` option on every node keep any
   stored definition expressible exactly.
@@ -116,14 +133,23 @@ const { buildId, workflows } = await lower(files, { connections });
   evaluates the bundle in an isolate. `buildId` is the SHA-256 of the bundle; it
   is identical with `esbuild` and `esbuild-wasm` of the same version, so the CLI
   and the service agree. Workflow code may import project files and
-  `@fluidgrids/workflows` only.
+  `@fluidgrids/workflows` only. The sources are limited to `maxSourceBytes`
+  (default 1 MiB) before esbuild runs and the bundle to `maxBundleBytes`
+  (default 1.5 MiB) before it is evaluated; a `LowerError` with
+  `reason: 'too-large'` reports either.
 - **Evaluators**: the default is a fresh Node `vm` context (for the CLI, which
   runs the developer's own code). Services use `createQuickJSEvaluator()` from
   `@fluidgrids/workflows/quickjs` (quickjs-emscripten 0.32.0, the engine the
-  workers use), which bounds memory and time.
+  workers use), which bounds memory exactly. Both evaluate in a worker thread
+  that is terminated at `timeoutMs`, so the budget covers parsing and compiling
+  the bundle, promise jobs and anything the code leaves behind, and the calling
+  process never runs or inspects a value from the isolate. Failures are
+  `LowerError`s with a `reason` (`timeout`, `determinism`, `out-of-memory`, …).
 - **Fidelity** is `lossless` when `irHash(lower(lift(ir))) == irHash(ir)`. Items
   report what is kept as plain strings or exact forms: `expression-verbatim`,
-  `legacy-syntax`, `unknown-node`, `connection-id-only`, `raw-node`, `key-added`;
+  `legacy-syntax`, `unknown-node`, `connection-id-only`, `connection-ambiguous`
+  (a connection name that more than one connection id has, so the id is kept),
+  `raw-node`, `key-added`;
   `layout-omitted`, `pinned-data-omitted`, `roundtrip-mismatch` and
   `lowering-failed` make an export lossy.
 
@@ -133,8 +159,12 @@ const { buildId, workflows } = await lower(files, { connections });
   `config` on internal nodes) into the canonical node fields following the
   executor's own reading order, so no executor-visible value changes
   (`executorView` computes what the executor reads, for checking). It is pure
-  and idempotent. The one mirror it keeps is `data.executionSettings.runOn`,
-  because today's executor reads `runOn` only there.
+  and idempotent. It keeps the mirrors some executor path reads from the data
+  bag only: `data.executionSettings.runOn`, `data.operation_name` (the agent tool
+  binding) and an external node's `data.version` (node-state rows). It does not
+  promote an external node's `data.state`, which the sub-node paths do not read;
+  `validate --strict` reports it. Keys named `__proto__` are ordinary keys
+  everywhere (copies, hashes, lift and lower).
 - `irHash` is `sha256:` + the SHA-256 of the RFC 8785 canonical JSON of the
   normalised definition without `authoring`.
 - `validate(definition, { strict, isTaskQueueKnown })` applies the service's
@@ -159,6 +189,127 @@ manifest's `input_fields` / `output_fields`; trigger operations also appear
 under `triggers`. Internal nodes ship in the package as `nodes.internal.*` and
 `triggers.*`.
 
+## Tier 2: durable workflow functions
+
+A tier-2 workflow is an `async` function that the engine runs by **replay**:
+from the top on every workflow task, with recorded results fed back, until it
+returns or awaits something not yet in its history. Everything that touches
+the world is a command (`ctx.run` for node activities, timers, child runs,
+signals to other runs); the function itself has no I/O.
+
+```ts
+import { workflow, defineSignal, ApplicationError } from '@fluidgrids/workflows';
+import { nodes as n } from './.fluidgrids/nodes';
+
+export const approve = defineSignal<{ by: string }>('approve');
+
+export const refundOrder = workflow(
+  'refund-order',
+  { signals: [approve] },
+  async (ctx, order: { id: string }) => {
+    const decision = await Promise.race([
+      ctx.signalReceived(approve),
+      ctx.sleep('2d').then(() => undefined),
+    ]);
+    if (!decision) throw new ApplicationError('Not approved in time', { type: 'PERMANENT' });
+    const refund = await ctx.run(n.stripe.refund, {
+      args: { chargeId: order.id },
+      retry: { maxRetries: 5, retryDelay: 1000 },
+    });
+    return { refunded: refund.id, approvedBy: decision.by };
+  }
+);
+```
+
+- `ctx.run`, `ctx.sleep`, `ctx.condition`, `ctx.signalReceived` / `ctx.onSignal`
+  / `ctx.setDefaultSignalHandler`, `ctx.child` / `ctx.startChild`,
+  `ctx.signalRun` / `ctx.signalParent` / `ctx.getRunHandle`, `ctx.sideEffect`,
+  `ctx.patched` / `ctx.deprecatePatch`, `ctx.now` / `ctx.random` / `ctx.uuid`,
+  `ctx.setCurrentDetails`, cancellation scopes, `ctx.saga()`, and the parity
+  commands `ctx.upsertContext` and `ctx.continueAsNew`. User activities, local
+  activities, custom queries, updates and search attributes are Phase C and fail
+  the workflow task with `UNSUPPORTED_COMMAND`.
+- Only store and registry nodes and `internal:http`, `internal:datatable`,
+  `internal:set` and `internal:code` may run as activities
+  (`ACTIVITY_NODE_ALLOWLIST`).
+- An `ApplicationError` (or any failure class, or a class listed in
+  `failureErrorTypes`) fails the run; any other throw, a determinism violation
+  or a Phase C call fails only the workflow task, which the engine retries.
+- A cancellation scope function receives a `ctx` bound to its scope; use it
+  inside the function. The outer `ctx` joins the scope only while the function
+  runs synchronously (`ctx.nonCancellable(() => ctx.run(...))` works), never
+  after an await, so concurrent branches never share a scope by accident.
+  `saga.compensate()` runs each compensation in its own non-cancellable scope
+  and passes it that scope's `ctx` (`saga.add((ctx) => ...)`).
+- `ctx.condition` in a scope that is already cancelled rejects with
+  `CancelledFailure`; `ctx.allHandlersFinished()` ignores cancellation.
+- A child whose options omit `cancellationType` uses
+  `WAIT_CANCELLATION_COMPLETED`: a cancelled scope sends
+  `REQUEST_CANCEL_EXTERNAL_RUN` with a `{ childId }` target (enabled with the
+  core commands) and the awaitable rejects once the child has ended.
+- `ctx.random()` and `ctx.uuid()` are seeded from `randomnessSeed` in the
+  `WORKFLOW_STARTED` payload (the service writes the run id), falling back to
+  `info.runId`, so a history replays on its own.
+- Inside the isolates, local time is UTC on every host, the `toLocale*` and
+  `localeCompare` methods are locale-independent, `Intl` is absent and
+  `WeakRef` / `FinalizationRegistry` throw, so QuickJS and `vm` run code the
+  same way. The in-process test environment runs on the host's built-ins.
+- In tier-1 code, `wf.codeWorkflow(fn, options)` embeds a function as an
+  `internal:code-workflow` node. A function that declares a trigger, or that no
+  tier-1 workflow embeds, lowers to a workflow of its own.
+
+### The runtime ABI and the task runner
+
+Every bundle installs `globalThis.__fluidgridsRuntime = { protocol: 1,
+sdkVersion, start(requestJson), step(), complete() }`. A host calls `start`,
+drains promise jobs while `step()` returns `"more"`, drains once more and reads
+the `WorkflowTaskResult` JSON from `complete()`. `createWorkflowTaskRunner()`
+(`@fluidgrids/workflows/quickjs`) does this in QuickJS on a pool of worker
+threads with a heap cap, a stack cap (default 256 KiB, about 1,300 frames,
+because QuickJS's C frames also use the host thread's stack) and a wall-clock
+budget, verifies bundles against their `buildId`, and replaces threads that
+time out or end a task with a fatal engine error before they get another task.
+
+### Testing
+
+```ts
+import { TestWorkflowEnvironment, replay } from '@fluidgrids/workflows/testing';
+
+const env = await TestWorkflowEnvironment.create();
+env.mock(n.stripe.refund, async () => ({ id: 're_1' }));
+const handle = await env.start(refundOrder, { input: { id: 'ch_1' } });
+await handle.signal(approve, { by: 'ana' });
+expect(await handle.result()).toEqual({ refunded: 're_1', approvedBy: 'ana' });
+await replay(refundOrder, handle.history()); // throws DeterminismViolation on a mismatch
+```
+
+The test environment appends exactly the events the service appends
+(`eventsForCommands`) and retries activities with `computeRetryDelay`. Its
+documented differences from the service: workflow tasks run in this process
+without the determinism shims (pass `taskExecutor` to run them in an isolate), a
+failed workflow task stops the run instead of being retried, activity
+start-to-close and heartbeat timeouts are not timed (a mock may throw a
+`TimeoutFailure`), and graph children are mocks (`mockChild`).
+
+`simulate(definition, { trigger, mocks, workflows })` walks a tier-1 graph in
+process. It is a reduced form: no expressions are evaluated, a node without a
+mock passes its input through, routing follows the handle a mock returns (or
+every edge), loops run their body once, and error policies, retries, waits and
+merges are not modelled.
+
+### Replay conformance fixtures
+
+`fixtures/histories/` holds the recorded histories of spec 10 §3 (timers,
+signals, cancellation, child runs, race, gather, continue-as-new, patched,
+side effects, activities, task failures, activation boundaries, and updates as
+parse-only fixtures), with their workflow sources in `fixtures/histories/src/`
+and the scenarios that recorded them in `fixtures/histories/scenarios.ts`.
+`bun run check:histories` re-records every history, replays it in QuickJS and in
+`vm`, requires both results to equal the recorded `expected`, and replays every
+completed workflow task to exactly the commands it recorded, then does all of
+it again under `TZ=Asia/Kolkata`; `tests/histories.test.ts` adds the in-process
+replay. `--write` re-records.
+
 ## Shared fixtures
 
 `fixtures/` holds the conformance fixtures shared with the Python SDK: every
@@ -175,6 +326,7 @@ bun run test:coverage        # with the 85% gate
 bun run lint
 bun run typecheck            # src, tests and the fixture projects
 bun run check:fixtures       # fixtures are current; add --ruff to run ruff format --check
+bun run check:histories      # replay conformance in QuickJS and vm; --write re-records
 bun run build                # tsup: ESM + CJS + .d.ts
 bun run sanity               # everything above
 ```

package/dist/activation-BBh1p82z.d.cts

@@ -0,0 +1,57 @@
+import { U as RunEventRecord } from './types-CpBBjaGX.cjs';
+
+/**
+ * Split a history into activations (C-HIST, spec 04 §2).
+ *
+ * An activation is what one workflow task saw and did: the input events it
+ * delivered to the code, the clock it ran with, and (for completed tasks) the
+ * command events it appended. Replaying a history means running the code
+ * through the same activations in order and checking that each completed one
+ * issues the commands it recorded; the last, open activation then produces the
+ * new commands.
+ *
+ * The rules:
+ * 1. A boundary is a `WORKFLOW_TASK_STARTED` followed (input events may
+ *    interleave) by `WORKFLOW_TASK_COMPLETED` of the same `taskId`. A Started
+ *    followed by Failed or TimedOut is not a boundary; its inputs carry over.
+ * 2. Activation k delivers the inputs appended before its Started, up to the
+ *    history length the task was leased with (`payload.historyLength`, written
+ *    on transient attempts, else the Started event's own seq).
+ * 3. Inputs appended after that (while the task ran) belong to activation k+1.
+ * 4. Command events after Completed(k) belong to activation k.
+ * 5. The clock of activation k is `payload.startedAt` of its Started event
+ *    when present, else the event time. The open activation uses `nowMs`.
+ * 6. The history length activation k reports is its cutoff (rule 2); the open
+ *    activation reports the leased length.
+ */
+
+interface Activation {
+    /** Input events to deliver, in history order. */
+    inputs: RunEventRecord[];
+    /** Command events the task appended; undefined for the open (new) activation. */
+    recorded: RunEventRecord[] | undefined;
+    /** The workflow clock during the activation. */
+    timeMs: number;
+    /** The completed task's id. */
+    taskId?: string;
+    /**
+     * The history length the task saw when it started (what `ctx.info.historyLength`
+     * and `continueAsNewSuggested` report during the activation, so replay sees
+     * the same values the original task did).
+     */
+    historyLength: number;
+}
+/**
+ * The activations of `history`. With `includeOpen`, the last entry is the
+ * open activation (the task being executed), even when it has no inputs.
+ */
+declare function splitActivations(history: readonly RunEventRecord[], nowMs: number, includeOpen: boolean): Activation[];
+/**
+ * Input events that no completed workflow task has delivered yet, in history
+ * order, including those that arrived while a task was running (rule 3). The
+ * service schedules a new workflow task when this is not empty after a task
+ * completes or an input is appended.
+ */
+declare function unseenInputs(history: readonly RunEventRecord[]): RunEventRecord[];
+
+export { type Activation as A, splitActivations as s, unseenInputs as u };

package/dist/activation-DnhG7SmF.d.ts

@@ -0,0 +1,57 @@
+import { U as RunEventRecord } from './types-DV-HX_Gt.js';
+
+/**
+ * Split a history into activations (C-HIST, spec 04 §2).
+ *
+ * An activation is what one workflow task saw and did: the input events it
+ * delivered to the code, the clock it ran with, and (for completed tasks) the
+ * command events it appended. Replaying a history means running the code
+ * through the same activations in order and checking that each completed one
+ * issues the commands it recorded; the last, open activation then produces the
+ * new commands.
+ *
+ * The rules:
+ * 1. A boundary is a `WORKFLOW_TASK_STARTED` followed (input events may
+ *    interleave) by `WORKFLOW_TASK_COMPLETED` of the same `taskId`. A Started
+ *    followed by Failed or TimedOut is not a boundary; its inputs carry over.
+ * 2. Activation k delivers the inputs appended before its Started, up to the
+ *    history length the task was leased with (`payload.historyLength`, written
+ *    on transient attempts, else the Started event's own seq).
+ * 3. Inputs appended after that (while the task ran) belong to activation k+1.
+ * 4. Command events after Completed(k) belong to activation k.
+ * 5. The clock of activation k is `payload.startedAt` of its Started event
+ *    when present, else the event time. The open activation uses `nowMs`.
+ * 6. The history length activation k reports is its cutoff (rule 2); the open
+ *    activation reports the leased length.
+ */
+
+interface Activation {
+    /** Input events to deliver, in history order. */
+    inputs: RunEventRecord[];
+    /** Command events the task appended; undefined for the open (new) activation. */
+    recorded: RunEventRecord[] | undefined;
+    /** The workflow clock during the activation. */
+    timeMs: number;
+    /** The completed task's id. */
+    taskId?: string;
+    /**
+     * The history length the task saw when it started (what `ctx.info.historyLength`
+     * and `continueAsNewSuggested` report during the activation, so replay sees
+     * the same values the original task did).
+     */
+    historyLength: number;
+}
+/**
+ * The activations of `history`. With `includeOpen`, the last entry is the
+ * open activation (the task being executed), even when it has no inputs.
+ */
+declare function splitActivations(history: readonly RunEventRecord[], nowMs: number, includeOpen: boolean): Activation[];
+/**
+ * Input events that no completed workflow task has delivered yet, in history
+ * order, including those that arrived while a task was running (rule 3). The
+ * service schedules a new workflow task when this is not empty after a task
+ * completes or an input is appended.
+ */
+declare function unseenInputs(history: readonly RunEventRecord[]): RunEventRecord[];
+
+export { type Activation as A, splitActivations as s, unseenInputs as u };

package/dist/assemble-BLqQ8lSu.d.cts

@@ -0,0 +1,39 @@
+import { P as Position, J as JsonObject, d as ConnectionRef, i as WorkflowAuthoring, b as WorkflowDefinition } from './types-BGoPzgcl.cjs';
+import { T as Tier1Recording, x as Tier1Workflow } from './workflow-FXUkpIBc.cjs';
+
+declare const LAYOUT_FORMAT = "fluidgrids.layout";
+declare const LAYOUT_FORMAT_VERSION = 1;
+/**
+ * The layout sidecar (`workflows/<key>.layout.json`): canvas positions, sticky
+ * notes and `meta.layout`, kept out of the code so it stays readable.
+ */
+interface LayoutSidecar {
+    format: typeof LAYOUT_FORMAT;
+    formatVersion: typeof LAYOUT_FORMAT_VERSION;
+    positions: Record<string, Position>;
+    stickyNotes?: JsonObject[];
+    metaLayout?: JsonObject;
+}
+/** How connection names in code resolve to connection references. */
+type ConnectionResolver = Readonly<Record<string, ConnectionRef>> | ((name: string) => ConnectionRef | undefined);
+interface AssembleOptions {
+    layout?: LayoutSidecar;
+    connections?: ConnectionResolver;
+    /** TEST-only pinned data (`workflows/<key>.pinned.json`). */
+    pinnedData?: JsonObject;
+    /** Provenance; defaults to `{ mode: 'canvas', generator: 'sdk-ts', generatorVersion }`. */
+    authoring?: WorkflowAuthoring;
+}
+/** Connection names used in code that the target workspace does not have. */
+declare class UnresolvedConnectionsError extends Error {
+    readonly names: string[];
+    constructor(names: string[]);
+}
+/** Validate a parsed layout sidecar. */
+declare function parseLayoutSidecar(value: unknown): LayoutSidecar;
+/** Assemble IR v2 from a recording. */
+declare function assembleRecording(recording: Tier1Recording, options?: AssembleOptions): WorkflowDefinition;
+/** Lower a tier-1 workflow to IR v2 (spec 10 §1 `toIR`). */
+declare function toIR(workflow: Tier1Workflow, options?: AssembleOptions): WorkflowDefinition;
+
+export { type AssembleOptions as A, type ConnectionResolver as C, LAYOUT_FORMAT as L, UnresolvedConnectionsError as U, LAYOUT_FORMAT_VERSION as a, type LayoutSidecar as b, assembleRecording as c, parseLayoutSidecar as p, toIR as t };

package/dist/assemble-DWgaXHd-.d.ts

@@ -0,0 +1,39 @@
+import { P as Position, J as JsonObject, d as ConnectionRef, i as WorkflowAuthoring, b as WorkflowDefinition } from './types-BGoPzgcl.js';
+import { T as Tier1Recording, x as Tier1Workflow } from './workflow-Bpr3vnA_.js';
+
+declare const LAYOUT_FORMAT = "fluidgrids.layout";
+declare const LAYOUT_FORMAT_VERSION = 1;
+/**
+ * The layout sidecar (`workflows/<key>.layout.json`): canvas positions, sticky
+ * notes and `meta.layout`, kept out of the code so it stays readable.
+ */
+interface LayoutSidecar {
+    format: typeof LAYOUT_FORMAT;
+    formatVersion: typeof LAYOUT_FORMAT_VERSION;
+    positions: Record<string, Position>;
+    stickyNotes?: JsonObject[];
+    metaLayout?: JsonObject;
+}
+/** How connection names in code resolve to connection references. */
+type ConnectionResolver = Readonly<Record<string, ConnectionRef>> | ((name: string) => ConnectionRef | undefined);
+interface AssembleOptions {
+    layout?: LayoutSidecar;
+    connections?: ConnectionResolver;
+    /** TEST-only pinned data (`workflows/<key>.pinned.json`). */
+    pinnedData?: JsonObject;
+    /** Provenance; defaults to `{ mode: 'canvas', generator: 'sdk-ts', generatorVersion }`. */
+    authoring?: WorkflowAuthoring;
+}
+/** Connection names used in code that the target workspace does not have. */
+declare class UnresolvedConnectionsError extends Error {
+    readonly names: string[];
+    constructor(names: string[]);
+}
+/** Validate a parsed layout sidecar. */
+declare function parseLayoutSidecar(value: unknown): LayoutSidecar;
+/** Assemble IR v2 from a recording. */
+declare function assembleRecording(recording: Tier1Recording, options?: AssembleOptions): WorkflowDefinition;
+/** Lower a tier-1 workflow to IR v2 (spec 10 §1 `toIR`). */
+declare function toIR(workflow: Tier1Workflow, options?: AssembleOptions): WorkflowDefinition;
+
+export { type AssembleOptions as A, type ConnectionResolver as C, LAYOUT_FORMAT as L, UnresolvedConnectionsError as U, LAYOUT_FORMAT_VERSION as a, type LayoutSidecar as b, assembleRecording as c, parseLayoutSidecar as p, toIR as t };