@chidchanun/bcp 0.2.10 → 0.2.11

package/README.md

@@ -1,14 +1,14 @@
 # BCP Framework
 
-BCP Framework is a React full-stack framework for file-based routing, SSR, SPA navigation, server data loading, guarded application flows, API routes, authentication, authorization, database access, background jobs, recurring scheduling, observability, validation, uploads, storage and standalone Node.js production deployment.
+BCP Framework is a React full-stack framework for file-based routing, SSR, SPA navigation, server data loading, guarded application flows, API routes, authentication, authorization, database access, background jobs, recurring scheduling, workflow orchestration, observability, validation, uploads, storage and standalone Node.js production deployment.
 
-> **Development target:** `0.2.10 — Durable Jobs Platform`
+> **Development target:** `0.2.11 — Workflow Orchestration`
 >
-> `0.2.10` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
+> `0.2.11` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
 
 ## 0.2 platform
 
-`0.2.0` established the Framework Platform baseline, `0.2.1` added the Documentation Platform, `0.2.2` added Configuration & Environment v2, `0.2.3` added Database Platform v2, `0.2.4` added Application Packaging, `0.2.5` added Authentication Platform v2, `0.2.6` added Authorization & Security v2, `0.2.7` added Observability Platform v2, `0.2.8` added Background Jobs Platform, `0.2.9` added recurring scheduling, and `0.2.10` adds durable worker leases, DLQ maintenance and Redis-compatible queue/scheduler adapters.
+`0.2.0` established the Framework Platform baseline, `0.2.1` added the Documentation Platform, `0.2.2` added Configuration & Environment v2, `0.2.3` added Database Platform v2, `0.2.4` added Application Packaging, `0.2.5` added Authentication Platform v2, `0.2.6` added Authorization & Security v2, `0.2.7` added Observability Platform v2, `0.2.8` added Background Jobs Platform, `0.2.9` added recurring scheduling, `0.2.10` added durable worker leases/DLQ/Redis adapters, and `0.2.11` adds persistent multi-step workflow orchestration.
 
 Machine-readable platform contracts:
 
@@ -38,6 +38,7 @@ docs/api-manifest.json
 | Background jobs | Delayed jobs, retries/backoff, cancellation, concurrent workers, visibility leases, heartbeat, stale recovery and DLQ |
 | Scheduling | Recurring interval jobs, UTC cron, schedule-store leases and deterministic scheduled run IDs |
 | Durable jobs | Redis-compatible queue/schedule adapters, retention cleanup, requeue and queue statistics |
+| Workflows | Sequential/parallel steps, retries, persisted delays, compensation, run leases and optional queue-backed execution |
 | Observability | Structured logs, counters/gauges/histograms, Prometheus output, request metrics and health/readiness checks |
 | Validation | Typed validators and structured validation errors |
 | Error handling | HTTP error helpers and consistent error responses |
@@ -319,7 +320,7 @@ Read more: [Job Scheduling Platform](docs/job-scheduling.md)
 
 ## Durable Jobs Platform — 0.2.10
 
-Workers now support visibility leases, heartbeat renewal and stale-running recovery when the configured adapter implements those capabilities:
+Workers support visibility leases, heartbeat renewal and stale-running recovery when the configured adapter implements those capabilities:
 
 ```ts
 const worker =
@@ -347,36 +348,7 @@ await jobs.requeueDeadLetter(
 );
 ```
 
-Operational helpers:
-
-```ts
-await jobs.recoverStale({
-    limit: 100,
-});
-
-const stats =
-    await jobs.stats();
-
-await jobs.cleanup({
-    before:
-        Date.now() -
-        7 * 24 * 60 * 60 * 1000,
-});
-```
-
-### Redis-compatible durable queue
-
-BCP does not install a Redis client library. Supply an application-owned client that implements:
-
-```ts
-interface RedisCommandClient {
-    sendCommand(
-        command: string[]
-    ): Promise<unknown>;
-}
-```
-
-Then create the adapters:
+Redis-compatible durable adapters:
 
 ```ts
 import {
@@ -411,17 +383,112 @@ export const scheduler =
     });
 ```
 
-The Redis reference adapters use atomic Lua operations for reservations, visibility leases, heartbeat, stale recovery, DLQ requeue and scheduler leasing. The default namespace is `bcp:{jobs}` so keys share one Redis Cluster hash slot.
+BCP does not read `REDIS_URL` or own the Redis client connection lifecycle automatically.
+
+Read more: [Durable Jobs Platform](docs/durable-jobs.md)
+
+## Workflow Orchestration — 0.2.11
+
+Create a server-only workflow with typed input:
+
+```ts
+import {
+    createWorkflow,
+} from "bcp/workflow";
+
+export const onboarding =
+    createWorkflow<{
+        userId: number;
+    }>(
+        "user.onboarding",
+        workflow => {
+            workflow.step(
+                "profile",
+                async ({ input }) => {
+                    await createProfile(
+                        input.userId
+                    );
+                }
+            );
+
+            workflow.parallel(
+                "initialize",
+                parallel => {
+                    parallel.step(
+                        "preferences",
+                        createPreferences
+                    );
+                    parallel.step(
+                        "workspace",
+                        createWorkspace
+                    );
+                }
+            );
+
+            workflow.delay(
+                "cooldown",
+                1_000
+            );
+        }
+    );
+```
+
+Per-step retries:
+
+```ts
+workflow.step(
+    "charge-card",
+    chargeCard,
+    {
+        maxAttempts: 3,
+        retryDelayMs:
+            attempt =>
+                attempt * 1_000,
+    }
+);
+```
+
+Saga-style compensation:
+
+```ts
+workflow.step(
+    "reserve-stock",
+    reserveStock,
+    {
+        compensate:
+            releaseStock,
+    }
+);
+```
 
-A typical application may configure its Redis client with:
+A failed run can be compensated in reverse completion order:
 
-```dotenv
-REDIS_URL=redis://localhost:6379
+```ts
+await onboarding.compensate(
+    runId
+);
 ```
 
-BCP does not read `REDIS_URL` automatically; connection creation, TLS/Cluster settings and credentials remain application-owned.
+For durable execution, supply an existing BCP job queue and a shared workflow store:
 
-Read more: [Durable Jobs Platform](docs/durable-jobs.md)
+```ts
+export const fulfillment =
+    createWorkflow(
+        "order.fulfillment",
+        defineWorkflow,
+        {
+            queue: jobs,
+            store:
+                workflowStore,
+        }
+    );
+```
+
+With a queue configured, `start()`, `retry()`, `resume()` and delay continuations execute through `bcp/jobs`. `WorkflowStore.claim()` is the atomic run-level concurrency boundary for multi-instance deployments.
+
+The built-in `createMemoryWorkflowStore()` is intended for local development and tests. External side effects should remain idempotent because durable job delivery is at-least-once.
+
+Read more: [Workflow Orchestration](docs/workflow-orchestration.md)
 
 ## Public entrypoints
 
@@ -437,6 +504,7 @@ bcp/error
 bcp/database
 bcp/auth
 bcp/jobs
+bcp/workflow
 bcp/observability
 bcp/server
 bcp/server-only
@@ -498,7 +566,11 @@ loaders / actions / API routes
 SSR / application responses
 
 Operational side channels:
-shared jobs + scheduler + structured logs + metrics + health/readiness
+workflow orchestration
+        ↓
+shared jobs + scheduler
+        ↓
+workers + structured logs + metrics + health/readiness
 ```
 
 Raw standalone build:
@@ -540,7 +612,7 @@ npm run test:e2e
 npm run rc:check
 ```
 
-`0.2.10` adds Durable Jobs Platform unit and prepared-package smoke checks covering visibility leases, heartbeat renewal, stale recovery, DLQ/requeue, retention/statistics, Redis queue/scheduler command contracts and the compiled `bcp/jobs` runtime.
+`0.2.11` adds Workflow Orchestration unit and prepared-package smoke checks covering sequential/parallel execution, retries, persisted delay/resume behavior, compensation, queue-backed continuation, run leases, browser boundary enforcement and the compiled `bcp/workflow` runtime.
 
 Do not tag or publish until the final release commit passes the complete RC sequence.
 
@@ -565,12 +637,13 @@ Do not tag or publish until the final release commit passes the complete RC sequ
 | `0.2.8` | Background Jobs Platform |
 | `0.2.9` | Job Scheduling Platform |
 | `0.2.10` | Durable Jobs Platform |
+| `0.2.11` | Workflow Orchestration |
 
 ## Roadmap
 
-`0.2.10 — Durable Jobs Platform` establishes shared production queue/scheduler adapters and worker recovery semantics while keeping the provider-neutral `bcp/jobs` contract.
+`0.2.11 — Workflow Orchestration` establishes persistent multi-step backend workflows on top of the provider-neutral jobs foundation.
 
-Later `0.2.x` work can add workflow orchestration, transactional outbox helpers or additional durable providers without changing the base queue/scheduler model. Native `.exe`, desktop and mobile compilation remain later roadmap work.
+The next logical `0.2.x` milestone is transactional outbox/event delivery so a database change and later asynchronous workflow/job publication can be coordinated without pretending a Redis publish is part of the database transaction. Realtime, testing, plugin/module and broader deployment work remain later roadmap items. Native `.exe`, desktop and mobile compilation remain later roadmap work.
 
 ## License
 

package/docs/README.md

@@ -2,7 +2,7 @@
 
 The `docs/` directory is the documentation source of truth for BCP Framework and is organized for **`bcp-docs-web`**.
 
-> **Documentation target:** BCP Framework `0.2.10 — Durable Jobs Platform`
+> **Documentation target:** BCP Framework `0.2.11 — Workflow Orchestration`
 >
 > **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
 
@@ -38,56 +38,54 @@ Framework source and tests remain authoritative for runtime behavior.
 | `0.2.8` | Background Jobs Platform |
 | `0.2.9` | Job Scheduling Platform |
 | `0.2.10` | Durable Jobs Platform |
+| `0.2.11` | Workflow Orchestration |
 
-## 0.2.10 — Durable Jobs Platform
+## 0.2.11 — Workflow Orchestration
 
-`0.2.10` makes the queue/scheduler contracts production-oriented without changing the `bcp/jobs` public entrypoint.
+`0.2.11` adds a new server-only `bcp/workflow` public entrypoint for persistent multi-step backend orchestration.
 
 New/updated documentation sources:
 
 | Source | Purpose |
 | --- | --- |
-| `background-jobs.md` | Base queue/worker contract |
-| `job-scheduling.md` | Interval/cron schedules and scheduler leases |
-| `durable-jobs.md` | Visibility leases, heartbeat recovery, DLQ, retention, statistics and Redis adapters |
-| `api-reference.md` | Current `bcp/jobs` public APIs |
-| `platform-manifest.json` | Durable Jobs capability flags |
-| `api-manifest.json` | `bcp/jobs` guide ownership |
-| `docs-web-manifest.json` | Durable Jobs navigation and `0.2.10` release route |
-| `releases/0.2.10.md` | Durable Jobs Platform release notes |
+| `workflow-orchestration.md` | Workflow definition, persistence, delays, retries, queue execution and compensation |
+| `durable-jobs.md` | Durable execution layer used by queue-backed workflows |
+| `api-reference.md` | Public `bcp/workflow` APIs |
+| `platform-manifest.json` | Workflow capability flags and public entrypoint |
+| `api-manifest.json` | `bcp/workflow` source/guide ownership |
+| `docs-web-manifest.json` | Workflow docs navigation and `0.2.11` release route |
+| `releases/0.2.11.md` | Workflow Orchestration release notes |
 
-Primary durable APIs:
+Primary APIs:
 
 ```ts
 import {
-    createJobQueue,
-    createRedisJobQueueAdapter,
-    createRedisJobScheduleStore,
-} from "bcp/jobs";
+    createMemoryWorkflowStore,
+    createWorkflow,
+} from "bcp/workflow";
 ```
 
 Runtime model:
 
 ```text
-web / API / action
-        |
-        v
-shared JobQueueAdapter
-        |
-        +--> visibility lease + heartbeat
-        +--> retry / stale recovery
-        +--> DLQ / requeue
-        |
-        v
-worker processes
-
-scheduler processes
-        |
-        v
-shared JobScheduleStore lease
+application / API
+       |
+       v
+WorkflowStore
+       |
+       v
+BCP Workflow
+       |
+       +--> sequential steps
+       +--> parallel groups
+       +--> retry / delay
+       +--> compensation
+       |
+       v
+optional durable bcp/jobs queue
 ```
 
-BCP does not bundle a Redis client library. Redis connection creation and shutdown remain application-owned through the minimal `RedisCommandClient` contract and optional close hook.
+The memory workflow store is local-only. Multi-instance deployments should implement a shared durable `WorkflowStore` whose `claim()` method atomically leases one run to one executor.
 
 ## Update rule
 
@@ -114,10 +112,11 @@ Important current routes:
 | `/docs/background-jobs` | `background-jobs.md` |
 | `/docs/job-scheduling` | `job-scheduling.md` |
 | `/docs/durable-jobs` | `durable-jobs.md` |
+| `/docs/workflow-orchestration` | `workflow-orchestration.md` |
 | `/docs/application-packaging` | `application-packaging.md` |
 | `/docs/database` | `database.md` |
 | `/docs/api-reference` | `api-reference.md` |
-| `/releases/0.2.10` | `releases/0.2.10.md` |
+| `/releases/0.2.11` | `releases/0.2.11.md` |
 
 Every route/source pair is validated by unit tests.
 
@@ -135,6 +134,7 @@ bcp/error
 bcp/database
 bcp/auth
 bcp/jobs
+bcp/workflow
 bcp/observability
 bcp/server
 bcp/server-only
@@ -145,7 +145,7 @@ The API-manifest entrypoint set must match the platform public-entrypoint set ex
 
 ## Release validation
 
-Before publishing `0.2.10`:
+Before publishing `0.2.11`:
 
 ```bash
 npm run typecheck
@@ -156,16 +156,18 @@ npm run test:e2e
 npm run rc:check
 ```
 
-Durable Jobs Platform validation covers:
-
-- worker visibility leases and heartbeat renewal,
-- stale-running recovery,
-- retry exhaustion and DLQ indexing,
-- dead-letter requeue,
-- queue statistics,
-- terminal retention cleanup,
-- Redis queue and schedule adapter command contracts,
-- compiled `bcp/jobs` runtime imports,
+Workflow Orchestration validation covers:
+
+- sequential step execution,
+- step retries,
+- parallel child execution/state,
+- persisted delay/resume behavior,
+- manual retry,
+- reverse-order compensation,
+- queue-backed execution and delayed continuation,
+- workflow store run leases,
+- server-only client boundary enforcement,
+- compiled `workflow.mjs` package execution,
 - docs/platform/API version parity.
 
 The final release tag must point to the exact commit that passed the complete RC sequence.

package/docs/api-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [
@@ -107,6 +107,18 @@
         "/docs/observability"
       ]
     },
+    {
+      "package": "bcp/workflow",
+      "source": "packages/client/src/workflow.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-workflow",
+      "summary": "Persistent workflow orchestration with sequential and parallel steps, retries, delays, compensation, run leases and optional durable queue execution.",
+      "guides": [
+        "/docs/workflow-orchestration",
+        "/docs/durable-jobs",
+        "/docs/observability"
+      ]
+    },
     {
       "package": "bcp/observability",
       "source": "packages/client/src/observability.ts",

package/docs/api-reference.md

@@ -133,21 +133,7 @@ import {
 
 ### Queue lifecycle
 
-`createJobQueue()` supports:
-
-```text
-immediate/delayed enqueue
-retry/backoff
-cancellation
-manual processNext()
-worker concurrency
-visibility timeout
-heartbeat lease renewal
-stale-running recovery
-DLQ inspection/requeue
-terminal retention cleanup
-queue statistics
-```
+`createJobQueue()` supports immediate/delayed enqueue, retry/backoff, cancellation, manual `processNext()`, worker concurrency, visibility timeout, heartbeat lease renewal, stale-running recovery, DLQ inspection/requeue, terminal retention cleanup and queue statistics.
 
 Durable adapter methods such as `heartbeat()`, `recoverStale()`, `listDeadLetters()`, `requeueDeadLetter()`, `cleanup()` and `stats()` are optional so earlier `JobQueueAdapter` implementations remain compatible.
 
@@ -181,6 +167,64 @@ The processing model is at-least-once. Handlers that perform non-idempotent exte
 
 Related guides: [Background Jobs Platform](background-jobs.md), [Job Scheduling Platform](job-scheduling.md), [Durable Jobs Platform](durable-jobs.md), [Observability Platform v2](observability.md).
 
+## `bcp/workflow`
+
+Server-only Workflow Orchestration APIs added in `0.2.11`.
+
+```ts
+import {
+    createMemoryWorkflowStore,
+    createWorkflow,
+    type CancelWorkflowOptions,
+    type MemoryWorkflowStore,
+    type ResumeWorkflowOptions,
+    type StartWorkflowOptions,
+    type Workflow,
+    type WorkflowBuilder,
+    type WorkflowCompensationHandler,
+    type WorkflowOptions,
+    type WorkflowParallelBuilder,
+    type WorkflowRetryDelay,
+    type WorkflowRunRecord,
+    type WorkflowRunState,
+    type WorkflowStepContext,
+    type WorkflowStepHandler,
+    type WorkflowStepKind,
+    type WorkflowStepOptions,
+    type WorkflowStepRecord,
+    type WorkflowStepState,
+    type WorkflowStore,
+} from "bcp/workflow";
+```
+
+`createWorkflow()` defines a persistent server-side workflow with sequential steps, parallel groups, per-step retry policies, persisted delays and compensation handlers.
+
+Workflow controls include:
+
+```text
+start()
+run()
+get()
+list()
+resume()
+retry()
+cancel()
+compensate()
+close()
+```
+
+Without a queue, workflow execution runs in the current process until it succeeds, fails, is cancelled or reaches a persisted delay.
+
+When an existing `BackgroundJobQueue` is passed through `WorkflowOptions.queue`, workflow execution is submitted through `bcp/jobs`. Delay steps enqueue delayed continuation jobs instead of holding a long-running timer.
+
+`WorkflowStore` is the workflow persistence boundary. Its `claim()` / `release()` methods form the run-level lease contract for shared multi-instance stores.
+
+`createMemoryWorkflowStore()` is intended for development and deterministic tests. Production multi-instance applications should implement a shared durable store with atomic `claim()` behavior.
+
+Compensation is saga-style and executes successful compensatable steps in reverse completion order. It does not turn external services into one distributed database transaction.
+
+Related guides: [Workflow Orchestration](workflow-orchestration.md), [Durable Jobs Platform](durable-jobs.md), [Observability Platform v2](observability.md).
+
 ## `bcp/observability`
 
 Server-only Observability Platform v2 APIs for process-local counters, gauges, histograms, Prometheus exposition, request metrics middleware and health/readiness checks.

package/docs/docs-web-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.2.10",
+  "versionTarget": "0.2.11",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -57,7 +57,7 @@
     {
       "id": "runtime",
       "title": "Runtime & Infrastructure",
-      "description": "Middleware, durable background jobs, scheduling, observability, logging, caching, security and production hardening.",
+      "description": "Middleware, durable background jobs, scheduling, workflow orchestration, observability, logging, caching, security and production hardening.",
       "pages": [
         { "route": "/docs/middleware", "source": "middleware.md", "title": "Middleware" },
         { "route": "/docs/hydration", "source": "hydration.md", "title": "Hydration" },
@@ -66,6 +66,7 @@
         { "route": "/docs/background-jobs", "source": "background-jobs.md", "title": "Background Jobs Platform" },
         { "route": "/docs/job-scheduling", "source": "job-scheduling.md", "title": "Job Scheduling Platform" },
         { "route": "/docs/durable-jobs", "source": "durable-jobs.md", "title": "Durable Jobs Platform" },
+        { "route": "/docs/workflow-orchestration", "source": "workflow-orchestration.md", "title": "Workflow Orchestration" },
         { "route": "/docs/caching", "source": "caching.md", "title": "Caching" },
         { "route": "/docs/security", "source": "security.md", "title": "Security" },
         { "route": "/docs/production-hardening", "source": "production-hardening.md", "title": "Production Hardening" }
@@ -111,7 +112,8 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.10", "source": "releases/0.2.10.md", "version": "0.2.10", "state": "unreleased" },
+    { "route": "/releases/0.2.11", "source": "releases/0.2.11.md", "version": "0.2.11", "state": "unreleased" },
+    { "route": "/releases/0.2.10", "source": "releases/0.2.10.md", "version": "0.2.10" },
     { "route": "/releases/0.2.9", "source": "releases/0.2.9.md", "version": "0.2.9" },
     { "route": "/releases/0.2.8", "source": "releases/0.2.8.md", "version": "0.2.8" },
     { "route": "/releases/0.2.7", "source": "releases/0.2.7.md", "version": "0.2.7" },

package/docs/platform-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "releaseState": "unreleased",
-  "baseline": "durable-jobs-platform",
+  "baseline": "workflow-orchestration",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -20,6 +20,7 @@
     "bcp/database",
     "bcp/auth",
     "bcp/jobs",
+    "bcp/workflow",
     "bcp/observability",
     "bcp/server",
     "bcp/server-only",
@@ -90,6 +91,15 @@
     "deadLetterRequeue": true,
     "jobRetentionCleanup": true,
     "jobQueueStatistics": true,
+    "workflowOrchestration": true,
+    "workflowStoreContract": true,
+    "workflowRunLeases": true,
+    "workflowSequentialSteps": true,
+    "workflowParallelSteps": true,
+    "workflowStepRetries": true,
+    "workflowDelays": true,
+    "workflowCompensation": true,
+    "workflowQueueExecution": true,
     "databaseMigrations": true,
     "databaseAdapterContract": true,
     "databasePostgresql": true,
@@ -129,7 +139,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.9",
+    "previousBaseline": "0.2.10",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -149,7 +159,8 @@
     "backgroundJobs": "background-jobs.md",
     "jobScheduling": "job-scheduling.md",
     "durableJobs": "durable-jobs.md",
+    "workflowOrchestration": "workflow-orchestration.md",
     "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.10.md"
+    "releaseNotes": "releases/0.2.11.md"
   }
 }