@particle-academy/fancy-flow 0.55.0 → 0.56.0

package/dist/index.js

@@ -7,8 +7,8 @@ export { evaluateConfig, evaluateExpression, resolvePath, text, truthy } from '.
 import { buildNodeTypes } from './chunk-E3AGYTHP.js';
 export { ANY_PORT_TYPE, RegistryNode, buildNodeTypes, createConnectionValidator, defaultPortCompatibility } from './chunk-E3AGYTHP.js';
 export { LEGACY_PAUSE_PREFIXES, PAUSE_PREFIX, decodePause, encodePause, isPause, pauseForHuman } from './chunk-UEOE6B52.js';
-import { workflowToBlob, importWorkflow, exportWorkflow } from './chunk-YVLOLS25.js';
-export { WORKFLOW_SCHEMA_URL, WORKFLOW_SCHEMA_VERSION, exportWorkflow, importWorkflow, migrateSchema, workflowToBlob } from './chunk-YVLOLS25.js';
+import { workflowToBlob, importWorkflow, exportWorkflow } from './chunk-GB4A7DFM.js';
+export { WORKFLOW_SCHEMA_URL, WORKFLOW_SCHEMA_VERSION, exportWorkflow, importWorkflow, migrateSchema, workflowToBlob } from './chunk-GB4A7DFM.js';
 import { ReactFlowProvider, useReactFlow, humanInputFields, onNodeKindsChanged, listNodeKinds, getNodeKind, defaultConfigFor, FlowEditorProvider, addEdge, applyEdgeChanges, applyNodeChanges, Position, ensureBuiltinKinds, validateConfig, categoryAccent, Handle } from './chunk-22OJOD4X.js';
 export { BUILTIN_KINDS, LaneNode, NoteNode, categoryAccent, clearNodeKindOverrides, defaultConfigFor, ensureBuiltinKinds, getNodeKind, listNodeKinds, onNodeKindsChanged, overrideNodeKind, registerBuiltinKinds, registerNodeKind, resolveNodePorts, resolvePortSpec, runFlow, useFlowEditor, useFlowEditorOptional, validateConfig } from './chunk-22OJOD4X.js';
 import { getRichInputAdapter } from './chunk-F5RPRB7A.js';

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

@@ -10737,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 = [];