@particle-academy/fancy-flow 0.54.0 → 0.56.0

package/dist/runtime.js

@@ -1,6 +1,6 @@
-export { applyOutputsToNodes, applyStatusesToNodes, createHistory, useFlowHistory, useFlowRun, useFlowState } from './chunk-FG3C7LIG.js';
-export { runCohort } from './chunk-WCFRKXH5.js';
-export { RunIdentity, escapeSegment, runFlow } from './chunk-CIBW5ATA.js';
+export { applyOutputsToNodes, applyStatusesToNodes, createHistory, useFlowHistory, useFlowRun, useFlowState } from './chunk-L4QAAGLV.js';
+export { runCohort } from './chunk-KP4TBF3A.js';
+export { RunIdentity, escapeSegment, runFlow } from './chunk-22OJOD4X.js';
 import './chunk-F5RPRB7A.js';
 import './chunk-USL4FMFU.js';
 //# sourceMappingURL=runtime.js.map

package/dist/schema/index.d.cts

@@ -116,13 +116,37 @@ type ImportOptions = {
      *  instead of errors. Default false. */
     lenient?: boolean;
 };
+/** A migration step: takes a version-N document to version N+1. */
+type MigrationStep = (schema: Record<string, unknown>) => Record<string, unknown>;
 /**
- * Migrate a raw schema object up to the current version. Additive changes need
- * no migration (an older document simply lacks the newer optional fields); this
- * is the seam for a future BREAKING bump — add `case N → N+1` steps here and
- * `importWorkflow` runs them before validating the version.
+ * Migrate a raw schema object up to the current version, as far as it can go.
+ *
+ * Additive changes need no migration — an older document simply lacks the newer
+ * optional fields. This is the seam for a future BREAKING bump, and
+ * `importWorkflow` runs it before validating the version.
+ *
+ * ## The three rules, each with a reason
+ *
+ *  - **A PAST version migrates forward**, step by step, to the current one.
+ *  - **A FUTURE version is left ALONE.** We cannot know what a later schema
+ *    means, and migrating downward would be guessing. Untouched hands it to the
+ *    version check, which reports it honestly.
+ *  - **A GAP in the table is left alone too.** A missing step is not a licence
+ *    to guess.
+ *
+ * ## Why `steps` is a parameter
+ *
+ * With only v1 in existence there is no old document to migrate, so a seam
+ * tested against the built-in (empty) table is a check that CANNOT fail — it
+ * would pass identically against a function that returned its input untouched,
+ * which is what this was until the twins needed the same seam.
+ *
+ * The PHP and Python runtimes carry the identical shape. That mattered more
+ * than it sounds: they had no migration at all and errored on any version
+ * mismatch, so a v2 bump would have made every stored Op unreadable on exactly
+ * the runtimes where durable runs resume.
  */
-declare function migrateSchema(schema: unknown): unknown;
+declare function migrateSchema(schema: unknown, steps?: Record<number, MigrationStep>): unknown;
 /**
  * Hydrate a schema into runtime FlowGraph + validate kinds/configs against
  * the registry. Reports issues for unknown kinds, missing required config,

package/dist/schema/index.d.ts

@@ -116,13 +116,37 @@ type ImportOptions = {
      *  instead of errors. Default false. */
     lenient?: boolean;
 };
+/** A migration step: takes a version-N document to version N+1. */
+type MigrationStep = (schema: Record<string, unknown>) => Record<string, unknown>;
 /**
- * Migrate a raw schema object up to the current version. Additive changes need
- * no migration (an older document simply lacks the newer optional fields); this
- * is the seam for a future BREAKING bump — add `case N → N+1` steps here and
- * `importWorkflow` runs them before validating the version.
+ * Migrate a raw schema object up to the current version, as far as it can go.
+ *
+ * Additive changes need no migration — an older document simply lacks the newer
+ * optional fields. This is the seam for a future BREAKING bump, and
+ * `importWorkflow` runs it before validating the version.
+ *
+ * ## The three rules, each with a reason
+ *
+ *  - **A PAST version migrates forward**, step by step, to the current one.
+ *  - **A FUTURE version is left ALONE.** We cannot know what a later schema
+ *    means, and migrating downward would be guessing. Untouched hands it to the
+ *    version check, which reports it honestly.
+ *  - **A GAP in the table is left alone too.** A missing step is not a licence
+ *    to guess.
+ *
+ * ## Why `steps` is a parameter
+ *
+ * With only v1 in existence there is no old document to migrate, so a seam
+ * tested against the built-in (empty) table is a check that CANNOT fail — it
+ * would pass identically against a function that returned its input untouched,
+ * which is what this was until the twins needed the same seam.
+ *
+ * The PHP and Python runtimes carry the identical shape. That mattered more
+ * than it sounds: they had no migration at all and errored on any version
+ * mismatch, so a v2 bump would have made every stored Op unreadable on exactly
+ * the runtimes where durable runs resume.
  */
-declare function migrateSchema(schema: unknown): unknown;
+declare function migrateSchema(schema: unknown, steps?: Record<number, MigrationStep>): unknown;
 /**
  * Hydrate a schema into runtime FlowGraph + validate kinds/configs against
  * the registry. Reports issues for unknown kinds, missing required config,

package/dist/schema.cjs

@@ -9337,7 +9337,7 @@ function resolveWorkflowProps(declared, passed) {
 // src/runtime/run-flow.ts
 async function runFlow(graph, executors, onEvent = () => {
 }, options = {}) {
-  const { signal, initialInputs = {}, timeoutMs, depth = 0, resumeOutputs = {} } = options;
+  const { signal, initialInputs = {}, timeoutMs, depth = 0, resumeOutputs = {}, entryNodes } = options;
   const run = options.run === void 0 ? void 0 : RunIdentity.from(options.run);
   const outputs = {};
   const portValues = /* @__PURE__ */ new Map();
@@ -9376,6 +9376,10 @@ async function runFlow(graph, executors, onEvent = () => {
         continue;
       }
       const incoming = incomingByNode.get(node.id) ?? [];
+      if (incoming.length === 0 && entryNodes !== void 0 && !entryNodes.includes(node.id)) {
+        onEvent({ type: "node-status", nodeId: node.id, status: "idle", text: "skipped" });
+        continue;
+      }
       if (incoming.length > 0) {
         const anyActive = incoming.some((e) => portValues.has(`${e.source}:${e.sourceHandle ?? "out"}`));
         if (!anyActive) {
@@ -10733,8 +10737,23 @@ function toSchemaEdge(e) {
     label: typeof e.label === "string" ? e.label : void 0
   };
 }
-function migrateSchema(schema) {
-  return schema;
+var MIGRATIONS = {};
+function migrateSchema(schema, steps = MIGRATIONS) {
+  if (!schema || typeof schema !== "object") return schema;
+  const doc = schema;
+  let version = doc.version;
+  if (typeof version !== "number" || !Number.isInteger(version) || version >= WORKFLOW_SCHEMA_VERSION) {
+    return schema;
+  }
+  let out = doc;
+  while (version < WORKFLOW_SCHEMA_VERSION) {
+    const step = steps[version];
+    if (!step) return out;
+    out = step(out);
+    version += 1;
+    out.version = version;
+  }
+  return out;
 }
 function importWorkflow(schema, options = {}) {
   const issues = [];