@chidchanun/bcp 0.2.9 → 0.2.10

package/README.md

@@ -2,13 +2,13 @@
 
 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.
 
-> **Development target:** `0.2.9 — Job Scheduling Platform`
+> **Development target:** `0.2.10 — Durable Jobs Platform`
 >
-> `0.2.9` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
+> `0.2.10` 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, and `0.2.10` adds durable worker leases, DLQ maintenance and Redis-compatible queue/scheduler adapters.
 
 Machine-readable platform contracts:
 
@@ -35,8 +35,9 @@ 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 |
 | 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 +132,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 +147,6 @@ postgresql
 sqlite
 ```
 
-Lifecycle control:
-
-```ts
-await db.connect();
-
-// application work
-
-await db.disconnect();
-```
-
 Migration CLI:
 
 ```bash
@@ -180,23 +169,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 +182,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 +202,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 +236,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 +245,7 @@ export const jobs =
     createJobQueue();
 ```
 
-Register a handler:
+Register work:
 
 ```ts
 jobs.register<{
@@ -329,7 +260,7 @@ jobs.register<{
 );
 ```
 
-Enqueue immediately or with a delay:
+Enqueue work:
 
 ```ts
 await jobs.enqueue(
@@ -344,24 +275,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 +315,113 @@ 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 now 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,
+    });
+```
+
+Retry-exhausted jobs can be inspected and requeued:
+
+```ts
+const failed =
+    await jobs.deadLetters();
+
+await jobs.requeueDeadLetter(
+    failed[0].id,
+    {
+        delayMs: 5_000,
+        resetAttempts: true,
+    }
+);
+```
+
+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>;
+}
 ```
 
-The scheduler runner polls due schedules and enqueues normal BCP jobs:
+Then create the adapters:
 
 ```ts
-const scheduleRunner =
-    scheduler.start({
-        pollIntervalMs: 1_000,
-        leaseMs: 30_000,
+import {
+    createJobQueue,
+    createJobScheduler,
+    createRedisJobQueueAdapter,
+    createRedisJobScheduleStore,
+} from "bcp/jobs";
+
+const queueAdapter =
+    createRedisJobQueueAdapter({
+        client: redisCommandClient,
+        namespace: "my-app:{jobs}",
+    });
+
+export const jobs =
+    createJobQueue({
+        adapter: queueAdapter,
     });
 
-// graceful shutdown
-await scheduleRunner.stop();
-await scheduler.close();
+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.
+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.
 
-Read more: [Job Scheduling Platform](docs/job-scheduling.md)
+A typical application may configure its Redis client with:
+
+```dotenv
+REDIS_URL=redis://localhost:6379
+```
+
+BCP does not read `REDIS_URL` automatically; connection creation, TLS/Cluster settings and credentials remain application-owned.
+
+Read more: [Durable Jobs Platform](docs/durable-jobs.md)
 
 ## Public entrypoints
 
@@ -485,27 +486,21 @@ 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
+shared jobs + scheduler + structured logs + metrics + health/readiness
 ```
 
-## Production build
-
 Raw standalone build:
 
 ```bash
@@ -519,8 +514,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 +540,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.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.
 
 Do not tag or publish until the final release commit passes the complete RC sequence.
 
@@ -571,12 +564,13 @@ 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 |
 
 ## 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.10 — Durable Jobs Platform` establishes shared production queue/scheduler adapters and worker recovery semantics while keeping the provider-neutral `bcp/jobs` contract.
 
-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.
+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.
 
 ## 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.10 — Durable Jobs Platform`
 >
 > **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
 
@@ -37,51 +37,57 @@ 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.9 — Job Scheduling Platform
+## 0.2.10 — Durable Jobs Platform
 
-`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.10` makes the queue/scheduler contracts production-oriented without changing the `bcp/jobs` public entrypoint.
 
 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 |
+| `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` | Scheduling navigation and `0.2.9` release route |
-| `releases/0.2.9.md` | Job Scheduling Platform release notes |
+| `docs-web-manifest.json` | Durable Jobs navigation and `0.2.10` release route |
+| `releases/0.2.10.md` | Durable Jobs Platform release notes |
 
-Primary scheduling APIs:
+Primary durable APIs:
 
 ```ts
 import {
-    createJobScheduler,
-    createMemoryJobScheduleStore,
-    nextCronTime,
-    nextScheduleTime,
+    createJobQueue,
+    createRedisJobQueueAdapter,
+    createRedisJobScheduleStore,
 } from "bcp/jobs";
 ```
 
 Runtime model:
 
 ```text
-recurring schedule
-    |
-    v
-JobScheduleStore.acquireDue()
-    |
-    | lease + deterministic run id
-    v
-JobQueueAdapter.enqueue()
-    |
-    v
-queue worker(s)
+web / API / action
+        |
+        v
+shared JobQueueAdapter
+        |
+        +--> visibility lease + heartbeat
+        +--> retry / stale recovery
+        +--> DLQ / requeue
+        |
+        v
+worker processes
+
+scheduler processes
+        |
+        v
+shared JobScheduleStore lease
 ```
 
-The built-in schedule store and queue are process-local. Multi-process/container production deployments should implement shared durable `JobScheduleStore` and `JobQueueAdapter` contracts.
+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.
 
 ## Update rule
 
@@ -98,8 +104,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 +113,11 @@ 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/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.10` | `releases/0.2.10.md` |
 
 Every route/source pair is validated by unit tests.
 
@@ -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.10`:
 
 ```bash
 npm run typecheck
@@ -151,17 +156,16 @@ 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,
+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,
 - 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.10",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [
@@ -99,10 +99,11 @@
       "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"
       ]
     },