@particle-academy/fancy-flow 0.55.0 → 0.57.0

package/dist/runtime.js

@@ -1,6 +1,6 @@
-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';
+export { applyOutputsToNodes, applyStatusesToNodes, createHistory, useFlowHistory, useFlowRun, useFlowState } from './chunk-4X3DPRVD.js';
+export { runCohort } from './chunk-45SSUYW7.js';
+export { RunIdentity, escapeSegment, runFlow } from './chunk-LTUOAFQA.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

@@ -10036,6 +10036,11 @@ var KINDS = [
   },
   {
     name: "@particle-academy/wait",
+    outputShape: [
+      { path: "waited", type: "string", description: "Which wait mode ran." },
+      { path: "duration", type: "number", description: "How long it waited." },
+      { path: "input", type: "unknown", description: "The value that arrived, carried forward." }
+    ],
     aliases: ["wait", "@fancy/wait"],
     category: "logic",
     label: "Wait",
@@ -10233,6 +10238,11 @@ var KINDS = [
   },
   {
     name: "@particle-academy/llm_router",
+    outputShape: [
+      { path: "route", type: "string", description: "The port the model chose." },
+      { path: "reason", type: "string", description: "Why the model chose it." },
+      { path: "input", type: "unknown", description: "The value that arrived, carried forward." }
+    ],
     // Every id this node has ever shipped under keeps resolving — MOIC's saved
     // flows carry the bare `llm_branch`.
     aliases: ["llm_router", "llm_branch", "@fancy/llm_branch", "@fancy/llm_router"],
@@ -10371,6 +10381,11 @@ var KINDS = [
   },
   {
     name: "@particle-academy/webhook_out",
+    outputShape: [
+      { path: "sent", type: "boolean", description: "True once the request was made." },
+      { path: "status", type: "number", description: "HTTP status, when the transport reported one." },
+      { path: "response", type: "unknown", description: "The response body, when there was one." }
+    ],
     aliases: ["webhook_out", "@fancy/webhook_out"],
     category: "io",
     label: "Send Webhook",
@@ -10408,6 +10423,12 @@ var KINDS = [
   },
   {
     name: "@particle-academy/notify",
+    outputShape: [
+      { path: "sent", type: "boolean", description: "True once the message was handed to the channel." },
+      { path: "channel", type: "string", description: "The channel it went to." },
+      { path: "to", type: "string", description: "The recipient." },
+      { path: "message", type: "string", description: "The rendered message." }
+    ],
     aliases: ["notify", "@fancy/notify"],
     category: "human",
     label: "Notify",
@@ -10443,6 +10464,10 @@ var KINDS = [
   },
   {
     name: "@particle-academy/log",
+    outputShape: [
+      { path: "logged", type: "string", description: "The message that was written." },
+      { path: "level", type: "string", description: "The level it was written at." }
+    ],
     aliases: ["log", "@fancy/log"],
     category: "output",
     label: "Log",
@@ -10737,8 +10762,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 = [];