@fluidgrids/workflows 2026.1027.1 → 2026.1028.1

package/fixtures/histories/timer-sleep-once.history.json

@@ -0,0 +1,118 @@
+{
+  "format": "fluidgrids.history",
+  "formatVersion": 1,
+  "name": "timer-sleep-once",
+  "description": "One durable one-hour timer; the clock after it is the TIMER_FIRED task time.",
+  "source": "src/timers.ts",
+  "info": {
+    "workspaceId": "test-workspace",
+    "taskQueue": "managed",
+    "attempt": 1,
+    "startedAt": "2026-01-01T00:00:00.000Z",
+    "runStartedAt": "2026-01-01T00:00:00.000Z",
+    "runId": "run-1"
+  },
+  "nowMs": 1767229200000,
+  "workflowFn": "sleepOnce",
+  "events": [
+    {
+      "seq": 1,
+      "type": "WORKFLOW_STARTED",
+      "payload": {
+        "workflowFn": "sleepOnce",
+        "input": null,
+        "taskQueue": "managed",
+        "randomnessSeed": "run-1"
+      },
+      "createdAt": "2026-01-01T00:00:00.000Z"
+    },
+    {
+      "seq": 2,
+      "type": "WORKFLOW_TASK_SCHEDULED",
+      "payload": {
+        "taskId": "run-1-task-1"
+      },
+      "createdAt": "2026-01-01T00:00:00.000Z"
+    },
+    {
+      "seq": 3,
+      "type": "WORKFLOW_TASK_STARTED",
+      "payload": {
+        "taskId": "run-1-task-1",
+        "attempt": 1
+      },
+      "createdAt": "2026-01-01T00:00:00.000Z"
+    },
+    {
+      "seq": 4,
+      "type": "WORKFLOW_TASK_COMPLETED",
+      "payload": {
+        "taskId": "run-1-task-1"
+      },
+      "createdAt": "2026-01-01T00:00:00.000Z",
+      "taskId": "run-1-task-1"
+    },
+    {
+      "seq": 5,
+      "type": "TIMER_STARTED",
+      "payload": {
+        "timerId": "t1",
+        "durationMs": 3600000,
+        "fireAt": "2026-01-01T01:00:00.000Z"
+      },
+      "createdAt": "2026-01-01T00:00:00.000Z",
+      "taskId": "run-1-task-1"
+    },
+    {
+      "seq": 6,
+      "type": "TIMER_FIRED",
+      "payload": {
+        "timerId": "t1"
+      },
+      "createdAt": "2026-01-01T01:00:00.000Z"
+    },
+    {
+      "seq": 7,
+      "type": "WORKFLOW_TASK_SCHEDULED",
+      "payload": {
+        "taskId": "run-1-task-2"
+      },
+      "createdAt": "2026-01-01T01:00:00.000Z"
+    },
+    {
+      "seq": 8,
+      "type": "WORKFLOW_TASK_STARTED",
+      "payload": {
+        "taskId": "run-1-task-2",
+        "attempt": 1
+      },
+      "createdAt": "2026-01-01T01:00:00.000Z"
+    },
+    {
+      "seq": 9,
+      "type": "WORKFLOW_TASK_COMPLETED",
+      "payload": {
+        "taskId": "run-1-task-2"
+      },
+      "createdAt": "2026-01-01T01:00:00.000Z",
+      "taskId": "run-1-task-2"
+    },
+    {
+      "seq": 10,
+      "type": "WORKFLOW_COMPLETED",
+      "payload": {
+        "output": {
+          "wokeAt": 1767229200000
+        }
+      },
+      "createdAt": "2026-01-01T01:00:00.000Z",
+      "taskId": "run-1-task-2"
+    }
+  ],
+  "expected": {
+    "protocol": 1,
+    "outcome": "commands",
+    "commands": [],
+    "logs": []
+  }
+}

package/fixtures/histories/timer-sleep-sequence.history.json

@@ -0,0 +1,210 @@
+{
+  "format": "fluidgrids.history",
+  "formatVersion": 1,
+  "name": "timer-sleep-sequence",
+  "description": "sleep(0) issues no timer; then 1s, 2s (with a summary) and PT2H timers in sequence.",
+  "source": "src/timers.ts",
+  "info": {
+    "workspaceId": "test-workspace",
+    "taskQueue": "managed",
+    "attempt": 1,
+    "startedAt": "2026-01-01T00:00:00.000Z",
+    "runStartedAt": "2026-01-01T00:00:00.000Z",
+    "runId": "run-1"
+  },
+  "nowMs": 1767232803000,
+  "workflowFn": "sleepSequence",
+  "events": [
+    {
+      "seq": 1,
+      "type": "WORKFLOW_STARTED",
+      "payload": {
+        "workflowFn": "sleepSequence",
+        "input": null,
+        "taskQueue": "managed",
+        "randomnessSeed": "run-1"
+      },
+      "createdAt": "2026-01-01T00:00:00.000Z"
+    },
+    {
+      "seq": 2,
+      "type": "WORKFLOW_TASK_SCHEDULED",
+      "payload": {
+        "taskId": "run-1-task-1"
+      },
+      "createdAt": "2026-01-01T00:00:00.000Z"
+    },
+    {
+      "seq": 3,
+      "type": "WORKFLOW_TASK_STARTED",
+      "payload": {
+        "taskId": "run-1-task-1",
+        "attempt": 1
+      },
+      "createdAt": "2026-01-01T00:00:00.000Z"
+    },
+    {
+      "seq": 4,
+      "type": "WORKFLOW_TASK_COMPLETED",
+      "payload": {
+        "taskId": "run-1-task-1"
+      },
+      "createdAt": "2026-01-01T00:00:00.000Z",
+      "taskId": "run-1-task-1"
+    },
+    {
+      "seq": 5,
+      "type": "TIMER_STARTED",
+      "payload": {
+        "timerId": "t1",
+        "durationMs": 1000,
+        "fireAt": "2026-01-01T00:00:01.000Z"
+      },
+      "createdAt": "2026-01-01T00:00:00.000Z",
+      "taskId": "run-1-task-1"
+    },
+    {
+      "seq": 6,
+      "type": "TIMER_FIRED",
+      "payload": {
+        "timerId": "t1"
+      },
+      "createdAt": "2026-01-01T00:00:01.000Z"
+    },
+    {
+      "seq": 7,
+      "type": "WORKFLOW_TASK_SCHEDULED",
+      "payload": {
+        "taskId": "run-1-task-2"
+      },
+      "createdAt": "2026-01-01T00:00:01.000Z"
+    },
+    {
+      "seq": 8,
+      "type": "WORKFLOW_TASK_STARTED",
+      "payload": {
+        "taskId": "run-1-task-2",
+        "attempt": 1
+      },
+      "createdAt": "2026-01-01T00:00:01.000Z"
+    },
+    {
+      "seq": 9,
+      "type": "WORKFLOW_TASK_COMPLETED",
+      "payload": {
+        "taskId": "run-1-task-2"
+      },
+      "createdAt": "2026-01-01T00:00:01.000Z",
+      "taskId": "run-1-task-2"
+    },
+    {
+      "seq": 10,
+      "type": "TIMER_STARTED",
+      "payload": {
+        "timerId": "t2",
+        "durationMs": 2000,
+        "summary": "two seconds",
+        "fireAt": "2026-01-01T00:00:03.000Z"
+      },
+      "createdAt": "2026-01-01T00:00:01.000Z",
+      "taskId": "run-1-task-2"
+    },
+    {
+      "seq": 11,
+      "type": "TIMER_FIRED",
+      "payload": {
+        "timerId": "t2"
+      },
+      "createdAt": "2026-01-01T00:00:03.000Z"
+    },
+    {
+      "seq": 12,
+      "type": "WORKFLOW_TASK_SCHEDULED",
+      "payload": {
+        "taskId": "run-1-task-3"
+      },
+      "createdAt": "2026-01-01T00:00:03.000Z"
+    },
+    {
+      "seq": 13,
+      "type": "WORKFLOW_TASK_STARTED",
+      "payload": {
+        "taskId": "run-1-task-3",
+        "attempt": 1
+      },
+      "createdAt": "2026-01-01T00:00:03.000Z"
+    },
+    {
+      "seq": 14,
+      "type": "WORKFLOW_TASK_COMPLETED",
+      "payload": {
+        "taskId": "run-1-task-3"
+      },
+      "createdAt": "2026-01-01T00:00:03.000Z",
+      "taskId": "run-1-task-3"
+    },
+    {
+      "seq": 15,
+      "type": "TIMER_STARTED",
+      "payload": {
+        "timerId": "t3",
+        "durationMs": 7200000,
+        "fireAt": "2026-01-01T02:00:03.000Z"
+      },
+      "createdAt": "2026-01-01T00:00:03.000Z",
+      "taskId": "run-1-task-3"
+    },
+    {
+      "seq": 16,
+      "type": "TIMER_FIRED",
+      "payload": {
+        "timerId": "t3"
+      },
+      "createdAt": "2026-01-01T02:00:03.000Z"
+    },
+    {
+      "seq": 17,
+      "type": "WORKFLOW_TASK_SCHEDULED",
+      "payload": {
+        "taskId": "run-1-task-4"
+      },
+      "createdAt": "2026-01-01T02:00:03.000Z"
+    },
+    {
+      "seq": 18,
+      "type": "WORKFLOW_TASK_STARTED",
+      "payload": {
+        "taskId": "run-1-task-4",
+        "attempt": 1
+      },
+      "createdAt": "2026-01-01T02:00:03.000Z"
+    },
+    {
+      "seq": 19,
+      "type": "WORKFLOW_TASK_COMPLETED",
+      "payload": {
+        "taskId": "run-1-task-4"
+      },
+      "createdAt": "2026-01-01T02:00:03.000Z",
+      "taskId": "run-1-task-4"
+    },
+    {
+      "seq": 20,
+      "type": "WORKFLOW_COMPLETED",
+      "payload": {
+        "output": {
+          "done": true,
+          "at": 1767232803000
+        }
+      },
+      "createdAt": "2026-01-01T02:00:03.000Z",
+      "taskId": "run-1-task-4"
+    }
+  ],
+  "expected": {
+    "protocol": 1,
+    "outcome": "commands",
+    "commands": [],
+    "logs": []
+  }
+}

package/fixtures/histories/update-accepted-completed.history.json

@@ -0,0 +1,149 @@
+{
+  "format": "fluidgrids.history",
+  "formatVersion": 1,
+  "name": "update-accepted-completed",
+  "description": "Phase C: an update accepted and completed by a handler (UPDATE_ACCEPTED, UPDATE_COMPLETED). Parsed and projected, not replayed.",
+  "source": "src/signals.ts",
+  "replay": false,
+  "info": {
+    "runId": "run-1",
+    "workspaceId": "test-workspace",
+    "taskQueue": "managed"
+  },
+  "nowMs": 1767225900000,
+  "workflowFn": "waitForApproval",
+  "events": [
+    {
+      "seq": 1,
+      "type": "WORKFLOW_STARTED",
+      "payload": {
+        "workflowFn": "waitForApproval",
+        "input": null,
+        "taskQueue": "managed"
+      },
+      "createdAt": "2026-01-01T00:00:00.000Z"
+    },
+    {
+      "seq": 2,
+      "type": "WORKFLOW_TASK_SCHEDULED",
+      "payload": {
+        "taskId": "t1"
+      },
+      "createdAt": "2026-01-01T00:00:00.000Z"
+    },
+    {
+      "seq": 3,
+      "type": "WORKFLOW_TASK_STARTED",
+      "payload": {
+        "taskId": "t1",
+        "attempt": 1
+      },
+      "createdAt": "2026-01-01T00:00:00.000Z"
+    },
+    {
+      "seq": 4,
+      "type": "WORKFLOW_TASK_COMPLETED",
+      "payload": {
+        "taskId": "t1"
+      },
+      "createdAt": "2026-01-01T00:00:00.000Z"
+    },
+    {
+      "seq": 5,
+      "type": "WORKFLOW_TASK_SCHEDULED",
+      "payload": {
+        "taskId": "t2"
+      },
+      "createdAt": "2026-01-01T00:05:00.000Z"
+    },
+    {
+      "seq": 6,
+      "type": "WORKFLOW_TASK_STARTED",
+      "payload": {
+        "taskId": "t2",
+        "attempt": 1
+      },
+      "createdAt": "2026-01-01T00:05:00.000Z"
+    },
+    {
+      "seq": 7,
+      "type": "WORKFLOW_TASK_COMPLETED",
+      "payload": {
+        "taskId": "t2"
+      },
+      "createdAt": "2026-01-01T00:05:00.000Z"
+    },
+    {
+      "seq": 8,
+      "type": "UPDATE_ACCEPTED",
+      "taskId": "t2",
+      "payload": {
+        "updateId": "u1",
+        "name": "changeAddress",
+        "args": {
+          "address": "1 Main St"
+        }
+      },
+      "createdAt": "2026-01-01T00:05:00.000Z"
+    },
+    {
+      "seq": 9,
+      "type": "UPDATE_COMPLETED",
+      "taskId": "t2",
+      "payload": {
+        "updateId": "u1",
+        "result": {
+          "accepted": true
+        }
+      },
+      "createdAt": "2026-01-01T00:05:00.000Z"
+    },
+    {
+      "seq": 10,
+      "type": "SIGNAL_RECEIVED",
+      "payload": {
+        "name": "approve",
+        "payload": {
+          "by": "dee"
+        }
+      },
+      "createdAt": "2026-01-01T00:05:00.000Z"
+    },
+    {
+      "seq": 11,
+      "type": "WORKFLOW_TASK_SCHEDULED",
+      "payload": {
+        "taskId": "t3"
+      },
+      "createdAt": "2026-01-01T00:05:00.000Z"
+    },
+    {
+      "seq": 12,
+      "type": "WORKFLOW_TASK_STARTED",
+      "payload": {
+        "taskId": "t3",
+        "attempt": 1
+      },
+      "createdAt": "2026-01-01T00:05:00.000Z"
+    },
+    {
+      "seq": 13,
+      "type": "WORKFLOW_TASK_COMPLETED",
+      "payload": {
+        "taskId": "t3"
+      },
+      "createdAt": "2026-01-01T00:05:00.000Z"
+    },
+    {
+      "seq": 14,
+      "type": "WORKFLOW_COMPLETED",
+      "taskId": "t3",
+      "payload": {
+        "output": {
+          "approvedBy": "dee"
+        }
+      },
+      "createdAt": "2026-01-01T00:05:00.000Z"
+    }
+  ]
+}

package/fixtures/histories/update-with-start-rejected-validation.history.json

@@ -0,0 +1,91 @@
+{
+  "format": "fluidgrids.history",
+  "formatVersion": 1,
+  "name": "update-with-start-rejected-validation",
+  "description": "Phase C: update-with-start admits an update (UPDATE_ADMITTED); a later update rejected by its validator leaves no event (11 §2.39). Parsed and projected, not replayed.",
+  "source": "src/signals.ts",
+  "replay": false,
+  "info": {
+    "runId": "run-1",
+    "workspaceId": "test-workspace",
+    "taskQueue": "managed"
+  },
+  "nowMs": 1767225600000,
+  "workflowFn": "waitForApproval",
+  "events": [
+    {
+      "seq": 1,
+      "type": "WORKFLOW_STARTED",
+      "payload": {
+        "workflowFn": "waitForApproval",
+        "input": null,
+        "taskQueue": "managed"
+      },
+      "createdAt": "2026-01-01T00:00:00.000Z"
+    },
+    {
+      "seq": 2,
+      "type": "UPDATE_ADMITTED",
+      "payload": {
+        "updateId": "u1",
+        "name": "changeAddress",
+        "args": {
+          "address": ""
+        }
+      },
+      "createdAt": "2026-01-01T00:00:00.000Z"
+    },
+    {
+      "seq": 3,
+      "type": "WORKFLOW_TASK_SCHEDULED",
+      "payload": {
+        "taskId": "t1"
+      },
+      "createdAt": "2026-01-01T00:00:00.000Z"
+    },
+    {
+      "seq": 4,
+      "type": "WORKFLOW_TASK_STARTED",
+      "payload": {
+        "taskId": "t1",
+        "attempt": 1
+      },
+      "createdAt": "2026-01-01T00:00:00.000Z"
+    },
+    {
+      "seq": 5,
+      "type": "WORKFLOW_TASK_COMPLETED",
+      "payload": {
+        "taskId": "t1"
+      },
+      "createdAt": "2026-01-01T00:00:00.000Z"
+    },
+    {
+      "seq": 6,
+      "type": "UPDATE_ACCEPTED",
+      "taskId": "t1",
+      "payload": {
+        "updateId": "u1",
+        "name": "changeAddress",
+        "args": {
+          "address": ""
+        }
+      },
+      "createdAt": "2026-01-01T00:00:00.000Z"
+    },
+    {
+      "seq": 7,
+      "type": "UPDATE_COMPLETED",
+      "taskId": "t1",
+      "payload": {
+        "updateId": "u1",
+        "failure": {
+          "errorType": "VALIDATION",
+          "message": "address is empty",
+          "type": "ApplicationError"
+        }
+      },
+      "createdAt": "2026-01-01T00:00:00.000Z"
+    }
+  ]
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fluidgrids/workflows",
-  "version": "2026.1027.1",
-  "description": "Author FluidGrids workflows as code: the IR v2 schema and tools, the tier-1 graph builder, lift and lower between canvas JSON, TypeScript and Python, and typed node client generation.",
+  "version": "2026.1028.1",
+  "description": "Author FluidGrids workflows as code: the IR v2 schema and tools, the tier-1 graph builder, tier-2 durable workflow functions with their runtime, history contract, QuickJS replay runner and test environment, lift and lower between canvas JSON, TypeScript and Python, and typed node client generation.",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -57,12 +57,48 @@
         "default": "./dist/quickjs/index.cjs"
       }
     },
+    "./history": {
+      "import": {
+        "types": "./dist/history/index.d.ts",
+        "default": "./dist/history/index.js"
+      },
+      "require": {
+        "types": "./dist/history/index.d.cts",
+        "default": "./dist/history/index.cjs"
+      }
+    },
+    "./runtime": {
+      "import": {
+        "types": "./dist/runtime/index.d.ts",
+        "default": "./dist/runtime/index.js"
+      },
+      "require": {
+        "types": "./dist/runtime/index.d.cts",
+        "default": "./dist/runtime/index.cjs"
+      }
+    },
+    "./testing": {
+      "import": {
+        "types": "./dist/testing/index.d.ts",
+        "default": "./dist/testing/index.js"
+      },
+      "require": {
+        "types": "./dist/testing/index.d.cts",
+        "default": "./dist/testing/index.cjs"
+      }
+    },
     "./schema/ir-v2.schema.json": "./schema/ir-v2.schema.json",
+    "./schema/run-event.schema.json": "./schema/run-event.schema.json",
+    "./schema/workflow-command.schema.json": "./schema/workflow-command.schema.json",
+    "./schema/workflow-task.schema.json": "./schema/workflow-task.schema.json",
+    "./schema/history-file.schema.json": "./schema/history-file.schema.json",
+    "./fixtures/histories/*": "./fixtures/histories/*",
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
     "schema",
+    "fixtures/histories/*.history.json",
     "README.md",
     "LICENSE"
   ],
@@ -81,10 +117,11 @@
     "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\" \"scripts/**/*.ts\" \"*.{json,md}\"",
     "typecheck": "bun run generate && bash scripts/build-limits.sh tsc --noEmit -p tsconfig.json && bash scripts/build-limits.sh tsc -p tsconfig.test.json && bash scripts/build-limits.sh tsc -p tsconfig.fixtures.json",
     "check:fixtures": "bun scripts/check-fixtures.ts",
-    "sanity": "bash scripts/build-limits.sh --gate bash -c 'bun run format:check && bun run lint:check && bun run typecheck && bun run test:coverage && bun run build && bun run check:exports && bun run check:fixtures'",
+    "sanity": "bash scripts/build-limits.sh --gate bash -c 'bun run format:check && bun run lint:check && bun run typecheck && bun run test:coverage && bun run build && bun run check:exports && bun run check:fixtures && bun run check:histories'",
     "prepublishOnly": "bun run build",
     "clean": "rm -rf dist coverage src/generated",
-    "check:exports": "bash scripts/build-limits.sh tsc -p scripts/exports-check/tsconfig.json"
+    "check:exports": "bash scripts/build-limits.sh tsc -p scripts/exports-check/tsconfig.json",
+    "check:histories": "bun run generate && bun scripts/check-histories.ts && TZ=Asia/Kolkata bun scripts/check-histories.ts"
   },
   "keywords": [
     "fluidgrids",
@@ -92,7 +129,9 @@
     "workflow-as-code",
     "automation",
     "sdk",
-    "typescript"
+    "typescript",
+    "durable-execution",
+    "replay"
   ],
   "author": {
     "name": "FluidGrids",