@chidchanun/bcp 0.2.9 → 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.9 — Job Scheduling Platform`
+> **Development target:** `0.2.11 — Workflow Orchestration`
 >
-> `0.2.9` 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, and `0.2.9` adds recurring interval/UTC-cron scheduling with lease-aware shared-store contracts.
+`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:
 
@@ -35,8 +35,10 @@ docs/api-manifest.json
 | Authorization | Auth/guest/role/permission route guards, flat permissions and resource-aware policies |
 | Request security | Same-origin validation and signed CSRF tokens for unsafe mutations |
 | Middleware | Middleware System v2 with onion execution |
-| Background jobs | Adapter contract, in-memory queue, delayed jobs, retries/backoff, cancellation and concurrent workers |
+| 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 |
@@ -131,8 +133,6 @@ Read more:
 
 ## Database Platform v2 — 0.2.3
 
-Application code uses one server-only database entrypoint across supported SQL providers:
-
 ```ts
 import {
     db,
@@ -148,16 +148,6 @@ postgresql
 sqlite
 ```
 
-Lifecycle control:
-
-```ts
-await db.connect();
-
-// application work
-
-await db.disconnect();
-```
-
 Migration CLI:
 
 ```bash
@@ -180,23 +170,10 @@ Create a fresh production build and deployment package:
 bcp package
 ```
 
-Output:
+Output is written under:
 
 ```text
 .bcp-framework/package/
-├─ client/
-├─ server/
-│  └─ server.mjs
-├─ public/                 # when present
-├─ manifest.json
-├─ package.json
-├─ package-lock.json       # when a safe npm v3 production lock can be derived
-├─ bcp.package.json
-├─ bcp.deployment.json
-├─ bcp.env.json
-├─ Dockerfile
-├─ .dockerignore
-└─ README.md
 ```
 
 Read more:
@@ -206,35 +183,17 @@ Read more:
 
 ## Authentication Platform v2 — 0.2.5
 
-Stateless signed JWT-cookie authentication remains supported:
-
 ```ts
 import {
     auth,
-    login,
-    logout,
-} from "bcp/auth";
-```
-
-Applications that need centralized revocation can add a server-side session store:
-
-```ts
-import {
     createAuth,
     createMemoryAuthSessionStore,
+    login,
+    logout,
 } from "bcp/auth";
-
-const sessionStore =
-    createMemoryAuthSessionStore();
-
-export const appAuth =
-    createAuth({
-        store: sessionStore,
-        idleTimeout: 60 * 30,
-    });
 ```
 
-With a store configured, authentication requires both a valid signed JWT cookie and an active `sid` record. The built-in memory store is intended for development/tests; production multi-instance deployments should implement `AuthSessionStore` with shared storage.
+Stateless signed JWT-cookie authentication remains supported. Applications that need centralized revocation can configure an `AuthSessionStore`.
 
 Read more:
 
@@ -244,37 +203,12 @@ Read more:
 
 ## Authorization & Security v2 — 0.2.6
 
-Use flat permissions directly from `bcp/auth`:
-
 ```ts
 import {
+    authorize,
     hasPermission,
     requirePermission,
 } from "bcp/auth";
-
-hasPermission(
-    user,
-    "users.read"
-);
-
-await requirePermission(
-    [
-        "users.read",
-        "users.write",
-    ],
-    {
-        match: "all",
-    }
-);
-```
-
-Resource-aware policies:
-
-```ts
-import {
-    authorize,
-    defineAuthorizationPolicy,
-} from "bcp/auth";
 ```
 
 Request-security helpers are exposed from `bcp/server`:
@@ -303,8 +237,6 @@ Read more: [Observability Platform v2](docs/observability.md)
 
 ## Background Jobs Platform — 0.2.8
 
-Create a server-side queue:
-
 ```ts
 import {
     createJobQueue,
@@ -314,7 +246,7 @@ export const jobs =
     createJobQueue();
 ```
 
-Register a handler:
+Register work:
 
 ```ts
 jobs.register<{
@@ -329,7 +261,7 @@ jobs.register<{
 );
 ```
 
-Enqueue immediately or with a delay:
+Enqueue work:
 
 ```ts
 await jobs.enqueue(
@@ -344,24 +276,10 @@ await jobs.enqueue(
 );
 ```
 
-Start concurrent workers:
-
-```ts
-const worker =
-    jobs.startWorker({
-        concurrency: 4,
-        pollIntervalMs: 250,
-    });
-```
-
-The default memory adapter is process-local. Durable multi-process deployments should implement `JobQueueAdapter` against shared infrastructure.
-
 Read more: [Background Jobs Platform](docs/background-jobs.md)
 
 ## Job Scheduling Platform — 0.2.9
 
-Create a scheduler on top of the same queue:
-
 ```ts
 import {
     createJobScheduler,
@@ -398,29 +316,179 @@ await scheduler.schedule(
 );
 ```
 
-Supported cron shape:
+Read more: [Job Scheduling Platform](docs/job-scheduling.md)
 
-```text
-minute hour day-of-month month day-of-week
+## Durable Jobs Platform — 0.2.10
+
+Workers support visibility leases, heartbeat renewal and stale-running recovery when the configured adapter implements those capabilities:
+
+```ts
+const worker =
+    jobs.startWorker({
+        workerId: "email-worker",
+        concurrency: 4,
+        visibilityTimeoutMs: 30_000,
+        heartbeatIntervalMs: 10_000,
+        pollIntervalMs: 250,
+    });
 ```
 
-The scheduler runner polls due schedules and enqueues normal BCP jobs:
+Retry-exhausted jobs can be inspected and requeued:
 
 ```ts
-const scheduleRunner =
-    scheduler.start({
-        pollIntervalMs: 1_000,
-        leaseMs: 30_000,
+const failed =
+    await jobs.deadLetters();
+
+await jobs.requeueDeadLetter(
+    failed[0].id,
+    {
+        delayMs: 5_000,
+        resetAttempts: true,
+    }
+);
+```
+
+Redis-compatible durable adapters:
+
+```ts
+import {
+    createJobQueue,
+    createJobScheduler,
+    createRedisJobQueueAdapter,
+    createRedisJobScheduleStore,
+} from "bcp/jobs";
+
+const queueAdapter =
+    createRedisJobQueueAdapter({
+        client: redisCommandClient,
+        namespace: "my-app:{jobs}",
     });
 
-// graceful shutdown
-await scheduleRunner.stop();
-await scheduler.close();
+export const jobs =
+    createJobQueue({
+        adapter: queueAdapter,
+    });
+
+const scheduleStore =
+    createRedisJobScheduleStore({
+        client: redisCommandClient,
+        namespace: "my-app:{jobs}",
+    });
+
+export const scheduler =
+    createJobScheduler({
+        queue: jobs,
+        store: scheduleStore,
+        ownerId: "scheduler-a",
+    });
 ```
 
-The built-in `createMemoryJobScheduleStore()` is process-local. Multi-instance production deployments should implement a shared `JobScheduleStore` whose `acquireDue()` operation atomically claims schedules with lease ownership/expiry. Scheduled occurrences also use deterministic queue ids for duplicate protection.
+BCP does not read `REDIS_URL` or own the Redis client connection lifecycle automatically.
 
-Read more: [Job Scheduling Platform](docs/job-scheduling.md)
+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 failed run can be compensated in reverse completion order:
+
+```ts
+await onboarding.compensate(
+    runId
+);
+```
+
+For durable execution, supply an existing BCP job queue and a shared workflow store:
+
+```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
 
@@ -436,6 +504,7 @@ bcp/error
 bcp/database
 bcp/auth
 bcp/jobs
+bcp/workflow
 bcp/observability
 bcp/server
 bcp/server-only
@@ -485,27 +554,25 @@ bcp generate middleware
 bcp generate migration create_users
 ```
 
-## Application model
+## Production model
 
 ```text
-Browser
-  ↓
-Origin / CSRF / middleware / cache
-  ↓
-Authentication + authorization guard
-  ↓
-Loader / action / API route
-  ↓
-React SSR
-  ↓
-Hydration / SPA navigation
+Browser / API clients
+        ↓
+security + middleware + auth
+        ↓
+loaders / actions / API routes
+        ↓
+SSR / application responses
 
 Operational side channels:
-background jobs + scheduler + structured logs + metrics + health/readiness
+workflow orchestration
+        ↓
+shared jobs + scheduler
+        ↓
+workers + structured logs + metrics + health/readiness
 ```
 
-## Production build
-
 Raw standalone build:
 
 ```bash
@@ -519,8 +586,6 @@ Deployment package:
 bcp package
 ```
 
-Both current targets remain Node.js `standalone-node` applications.
-
 ## Documentation Platform
 
 The framework repository is the documentation source of truth.
@@ -547,7 +612,7 @@ npm run test:e2e
 npm run rc:check
 ```
 
-`0.2.9` adds Job Scheduling Platform unit and prepared-package smoke checks covering interval schedules, UTC cron parsing, standard day matching, schedule-store leases, deterministic scheduled run ids, retry propagation and lifecycle validation.
+`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.
 
@@ -571,12 +636,14 @@ Do not tag or publish until the final release commit passes the complete RC sequ
 | `0.2.7` | Observability Platform v2 |
 | `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.9 — Job Scheduling Platform` establishes recurring scheduling and the durable schedule-store contract on top of the provider-neutral queue introduced in `0.2.8`.
+`0.2.11 — Workflow Orchestration` establishes persistent multi-step backend workflows on top of the provider-neutral jobs foundation.
 
-Future work can add first-party durable queue/schedule adapters, dead-letter queues or workflow orchestration without changing the base queue and scheduler contracts. 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.9 — Job Scheduling Platform`
+> **Documentation target:** BCP Framework `0.2.11 — Workflow Orchestration`
 >
 > **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
 
@@ -37,51 +37,55 @@ Framework source and tests remain authoritative for runtime behavior.
 | `0.2.7` | Observability Platform v2 |
 | `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.9 — Job Scheduling Platform
+## 0.2.11 — Workflow Orchestration
 
-`0.2.9` extends `bcp/jobs` with recurring interval jobs, dependency-free UTC cron schedules, scheduler runners, deterministic scheduled occurrence IDs and a lease-aware `JobScheduleStore` contract.
+`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 from `0.2.8` |
-| `job-scheduling.md` | Interval/cron schedules, leases and durable schedule-store guidance |
-| `api-reference.md` | Public queue + scheduler APIs under `bcp/jobs` |
-| `platform-manifest.json` | Job Scheduling capability flags |
-| `api-manifest.json` | `bcp/jobs` guide ownership |
-| `docs-web-manifest.json` | Scheduling navigation and `0.2.9` release route |
-| `releases/0.2.9.md` | Job Scheduling 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 scheduling APIs:
+Primary APIs:
 
 ```ts
 import {
-    createJobScheduler,
-    createMemoryJobScheduleStore,
-    nextCronTime,
-    nextScheduleTime,
-} from "bcp/jobs";
+    createMemoryWorkflowStore,
+    createWorkflow,
+} from "bcp/workflow";
 ```
 
 Runtime model:
 
 ```text
-recurring schedule
-    |
-    v
-JobScheduleStore.acquireDue()
-    |
-    | lease + deterministic run id
-    v
-JobQueueAdapter.enqueue()
-    |
-    v
-queue worker(s)
+application / API
+       |
+       v
+WorkflowStore
+       |
+       v
+BCP Workflow
+       |
+       +--> sequential steps
+       +--> parallel groups
+       +--> retry / delay
+       +--> compensation
+       |
+       v
+optional durable bcp/jobs queue
 ```
 
-The built-in schedule store and queue are process-local. Multi-process/container production deployments should implement shared durable `JobScheduleStore` and `JobQueueAdapter` contracts.
+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
 
@@ -98,8 +102,6 @@ When framework behavior or public surface changes:
 
 ## Docs-web navigation
 
-`docs/docs-web-manifest.json` is the authoritative ordered navigation contract.
-
 Important current routes:
 
 | Website route | Markdown source |
@@ -109,10 +111,12 @@ Important current routes:
 | `/docs/observability` | `observability.md` |
 | `/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.9` | `releases/0.2.9.md` |
+| `/releases/0.2.11` | `releases/0.2.11.md` |
 
 Every route/source pair is validated by unit tests.
 
@@ -130,6 +134,7 @@ bcp/error
 bcp/database
 bcp/auth
 bcp/jobs
+bcp/workflow
 bcp/observability
 bcp/server
 bcp/server-only
@@ -140,7 +145,7 @@ The API-manifest entrypoint set must match the platform public-entrypoint set ex
 
 ## Release validation
 
-Before publishing `0.2.9`:
+Before publishing `0.2.11`:
 
 ```bash
 npm run typecheck
@@ -151,17 +156,18 @@ npm run test:e2e
 npm run rc:check
 ```
 
-Job Scheduling Platform validation covers:
-
-- interval scheduling,
-- five-field UTC cron parsing,
-- standard day-of-month/day-of-week behavior,
-- schedule-store leasing,
-- deterministic scheduled run IDs,
-- retry-limit propagation into queue jobs,
-- schedule inspection/removal,
-- scheduler configuration validation,
-- prepared npm package contents,
+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.9",
+  "version": "0.2.11",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [
@@ -99,10 +99,23 @@
       "source": "packages/client/src/jobs.ts",
       "environment": "server",
       "route": "/docs/api-reference#bcp-jobs",
-      "summary": "Background job queues plus recurring interval/cron scheduling, schedule-store leases and worker lifecycle APIs.",
+      "summary": "Background queues and schedules with visibility leases, heartbeats, stale recovery, DLQ maintenance and Redis-compatible durable adapters.",
       "guides": [
         "/docs/background-jobs",
         "/docs/job-scheduling",
+        "/docs/durable-jobs",
+        "/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"
       ]
     },