@chidchanun/bcp 0.2.7 → 0.2.9

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, 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, observability, validation, uploads, storage and standalone Node.js production deployment.
 
-> **Development target:** `0.2.7 — Observability Platform v2`
+> **Development target:** `0.2.9 — Job Scheduling Platform`
 >
-> `0.2.7` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
+> `0.2.9` 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, and `0.2.7` adds dependency-free metrics, Prometheus exposition, request metrics and health/readiness checks without intentionally changing the existing application model.
+`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.
 
 Machine-readable platform contracts:
 
@@ -35,6 +35,8 @@ 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 |
+| Scheduling | Recurring interval jobs, UTC cron, schedule-store leases and deterministic scheduled run IDs |
 | 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 |
@@ -273,24 +275,6 @@ import {
     authorize,
     defineAuthorizationPolicy,
 } from "bcp/auth";
-
-const updateProject =
-    defineAuthorizationPolicy(
-        ({
-            user,
-            resource,
-        }) =>
-            resource.ownerId ===
-            user.id
-    );
-
-await authorize(
-    updateProject,
-    {
-        user,
-        resource: project,
-    }
-);
 ```
 
 Request-security helpers are exposed from `bcp/server`:
@@ -307,89 +291,136 @@ Read more: [Authorization & Security v2](docs/authorization-security.md)
 
 ## Observability Platform v2 — 0.2.7
 
-Create one application metrics registry:
-
 ```ts
 import {
+    createHealthRegistry,
     createMetricsRegistry,
+    createMetricsResponse,
 } from "bcp/observability";
-
-export const metrics =
-    createMetricsRegistry();
 ```
 
-Supported metric types:
+Read more: [Observability Platform v2](docs/observability.md)
 
-```text
-counter
-gauge
-histogram
-```
+## Background Jobs Platform — 0.2.8
 
-Expose Prometheus-compatible text:
+Create a server-side queue:
 
 ```ts
 import {
-    createMetricsResponse,
-} from "bcp/observability";
+    createJobQueue,
+} from "bcp/jobs";
 
-export function GET() {
-    return createMetricsResponse(
-        metrics
-    );
-}
+export const jobs =
+    createJobQueue();
 ```
 
-Instrument HTTP requests through Middleware System v2:
+Register a handler:
 
 ```ts
-import {
-    createRequestMetricsMiddleware,
-} from "bcp/observability";
+jobs.register<{
+    userId: number;
+}>(
+    "email.welcome",
+    async ({ payload }) => {
+        await sendWelcomeEmail(
+            payload.userId
+        );
+    }
+);
+```
+
+Enqueue immediately or with a delay:
 
-export const requestMetrics =
-    createRequestMetricsMiddleware(
-        metrics
-    );
+```ts
+await jobs.enqueue(
+    "email.welcome",
+    {
+        userId: 42,
+    },
+    {
+        delayMs: 5_000,
+        maxAttempts: 5,
+    }
+);
 ```
 
-Default request metrics use only bounded labels:
+Start concurrent workers:
 
-```text
-bcp_http_requests_total{method,status}
-bcp_http_request_duration_seconds{method,status}
+```ts
+const worker =
+    jobs.startWorker({
+        concurrency: 4,
+        pollIntervalMs: 250,
+    });
 ```
 
-Raw paths are not attached by default.
+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
 
-Health/readiness registry:
+Create a scheduler on top of the same queue:
 
 ```ts
 import {
-    createHealthRegistry,
-} from "bcp/observability";
+    createJobScheduler,
+} from "bcp/jobs";
 
-export const health =
-    createHealthRegistry();
+export const scheduler =
+    createJobScheduler({
+        queue: jobs,
+    });
+```
+
+Interval schedule:
 
-health.register(
-    "database",
-    async () => {
-        await db.query("SELECT 1");
-        return true;
+```ts
+await scheduler.schedule(
+    "cache.cleanup",
+    {},
+    {
+        id: "cache-cleanup",
+        everyMs: 5 * 60 * 1000,
     }
 );
 ```
 
-Use:
+UTC cron schedule:
 
 ```ts
-return health.response();
+await scheduler.schedule(
+    "report.weekday",
+    {},
+    {
+        cron: "30 9 * * 1-5",
+    }
+);
 ```
 
-Health responses return `200` when every check passes and `503` when any registered dependency is unhealthy or times out.
+Supported cron shape:
 
-Read more: [Observability Platform v2](docs/observability.md)
+```text
+minute hour day-of-month month day-of-week
+```
+
+The scheduler runner polls due schedules and enqueues normal BCP jobs:
+
+```ts
+const scheduleRunner =
+    scheduler.start({
+        pollIntervalMs: 1_000,
+        leaseMs: 30_000,
+    });
+
+// graceful shutdown
+await scheduleRunner.stop();
+await scheduler.close();
+```
+
+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.
+
+Read more: [Job Scheduling Platform](docs/job-scheduling.md)
 
 ## Public entrypoints
 
@@ -404,6 +435,7 @@ bcp/validation
 bcp/error
 bcp/database
 bcp/auth
+bcp/jobs
 bcp/observability
 bcp/server
 bcp/server-only
@@ -469,7 +501,7 @@ React SSR
 Hydration / SPA navigation
 
 Operational side channels:
-structured logs + metrics + health/readiness
+background jobs + scheduler + structured logs + metrics + health/readiness
 ```
 
 ## Production build
@@ -515,7 +547,7 @@ npm run test:e2e
 npm run rc:check
 ```
 
-`0.2.7` adds Observability Platform v2 unit and prepared-package smoke checks covering metrics, Prometheus exposition, request timing, cardinality-safe default labels, health/readiness responses and timeout handling.
+`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.
 
 Do not tag or publish until the final release commit passes the complete RC sequence.
 
@@ -537,12 +569,14 @@ Do not tag or publish until the final release commit passes the complete RC sequ
 | `0.2.5` | Authentication Platform v2 |
 | `0.2.6` | Authorization & Security v2 |
 | `0.2.7` | Observability Platform v2 |
+| `0.2.8` | Background Jobs Platform |
+| `0.2.9` | Job Scheduling Platform |
 
 ## Roadmap
 
-`0.2.7 — Observability Platform v2` establishes process-level metrics and health/readiness contracts on top of the existing structured logging and Middleware System v2 runtime.
+`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`.
 
-Future `0.2.x` work can add distributed tracing or exporter integrations without changing the application metrics/health contract introduced here. Native `.exe`, desktop and mobile compilation remain later roadmap work.
+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.
 
 ## 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.7 — Observability Platform v2`
+> **Documentation target:** BCP Framework `0.2.9 — Job Scheduling Platform`
 >
 > **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
 
@@ -21,24 +21,6 @@ docs/api-manifest.json
   -> public package entrypoints, source ownership and guide mapping
 ```
 
-Markdown files under `docs/` remain the authored documentation content.
-
-Recommended flow:
-
-```text
-framework source/tests
-        ↓
-      docs/
-        ├─ Markdown content
-        ├─ docs-web-manifest.json
-        ├─ platform-manifest.json
-        └─ api-manifest.json
-        ↓
-manifest-driven sync
-        ↓
-    bcp-docs-web
-```
-
 Framework source and tests remain authoritative for runtime behavior.
 
 ## Current 0.2.x milestones
@@ -53,48 +35,53 @@ Framework source and tests remain authoritative for runtime behavior.
 | `0.2.5` | Authentication Platform v2 |
 | `0.2.6` | Authorization & Security v2 |
 | `0.2.7` | Observability Platform v2 |
+| `0.2.8` | Background Jobs Platform |
+| `0.2.9` | Job Scheduling Platform |
 
-## 0.2.7 — Observability Platform v2
+## 0.2.9 — Job Scheduling Platform
 
-`0.2.7` adds a server-only observability layer without adding third-party runtime dependencies.
+`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.
 
 New/updated documentation sources:
 
 | Source | Purpose |
 | --- | --- |
-| `observability.md` | Metrics registry, Prometheus output, request metrics and health/readiness checks |
-| `api-reference.md` | Public `bcp/observability` exports |
-| `platform-manifest.json` | Observability capability flags and new public entrypoint |
-| `api-manifest.json` | `bcp/observability` guide ownership |
-| `docs-web-manifest.json` | Observability navigation and `0.2.7` release route |
-| `releases/0.2.7.md` | Observability Platform v2 release notes |
+| `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 |
 
-Primary APIs:
+Primary scheduling APIs:
 
 ```ts
 import {
-    createHealthRegistry,
-    createMetricsRegistry,
-    createMetricsResponse,
-    createRequestMetricsMiddleware,
-} from "bcp/observability";
+    createJobScheduler,
+    createMemoryJobScheduleStore,
+    nextCronTime,
+    nextScheduleTime,
+} from "bcp/jobs";
 ```
 
 Runtime model:
 
 ```text
-structured logs
-    +
-process-local metrics
-    +
-Prometheus exposition
-    +
-health/readiness checks
+recurring schedule
+    |
+    v
+JobScheduleStore.acquireDue()
+    |
+    | lease + deterministic run id
+    v
+JobQueueAdapter.enqueue()
+    |
+    v
+queue worker(s)
 ```
 
-The request metrics middleware intentionally uses bounded `method` and `status` labels by default rather than raw paths.
-
-The built-in metrics registry is process-local; distributed aggregation remains deployment infrastructure or future exporter work.
+The built-in schedule store and queue are process-local. Multi-process/container production deployments should implement shared durable `JobScheduleStore` and `JobQueueAdapter` contracts.
 
 ## Update rule
 
@@ -113,21 +100,6 @@ When framework behavior or public surface changes:
 
 `docs/docs-web-manifest.json` is the authoritative ordered navigation contract.
 
-Current sections:
-
-```text
-Getting Started
-Routing & Data
-Authentication & Authorization
-Database
-Runtime & Infrastructure
-Storage & Uploads
-Developer Experience
-Platform & Compatibility
-API Reference
-Releases
-```
-
 Important current routes:
 
 | Website route | Markdown source |
@@ -135,40 +107,18 @@ Important current routes:
 | `/docs/authentication` | `authentication.md` |
 | `/docs/authorization-security` | `authorization-security.md` |
 | `/docs/observability` | `observability.md` |
-| `/docs/development-logging` | `development-logging.md` |
+| `/docs/background-jobs` | `background-jobs.md` |
+| `/docs/job-scheduling` | `job-scheduling.md` |
 | `/docs/application-packaging` | `application-packaging.md` |
 | `/docs/database` | `database.md` |
 | `/docs/api-reference` | `api-reference.md` |
-| `/releases/0.2.7` | `releases/0.2.7.md` |
+| `/releases/0.2.9` | `releases/0.2.9.md` |
 
 Every route/source pair is validated by unit tests.
 
-## Platform manifest
-
-`docs/platform-manifest.json` describes:
-
-```text
-framework version/release state
-Node/React/runtime baseline
-production build/package target
-public package entrypoints
-CLI command families
-capability flags
-previous-baseline compatibility intent
-documentation contract files
-```
+## Public entrypoints
 
-The supported production target remains:
-
-```text
-standalone-node
-```
-
-## API manifest
-
-`docs/api-manifest.json` describes public package entrypoints documentation tooling may present as supported APIs.
-
-Current entrypoints:
+Current documented entrypoints:
 
 ```text
 bcp
@@ -179,6 +129,7 @@ bcp/validation
 bcp/error
 bcp/database
 bcp/auth
+bcp/jobs
 bcp/observability
 bcp/server
 bcp/server-only
@@ -187,39 +138,9 @@ bcp/middleware
 
 The API-manifest entrypoint set must match the platform public-entrypoint set exactly.
 
-## bcp-docs-web synchronization
-
-The docs website sync loads the manifests before Markdown content:
-
-```text
-selected framework ref
-        ↓
-docs-web-manifest.json
-platform-manifest.json
-api-manifest.json
-        ↓
-validate version/release/API parity
-        ↓
-load referenced Markdown
-        ↓
-synchronize CMS/search/navigation
-```
-
-## Source conventions
-
-- one H1 per Markdown page,
-- stable heading hierarchy,
-- fenced code blocks with language tags,
-- relative links between docs,
-- exact public API names,
-- clear stable/RC/roadmap labels,
-- security limitations next to affected APIs,
-- no framework-internal module presented as public API,
-- no secrets/runtime `.env` values in public documentation metadata.
-
 ## Release validation
 
-Before publishing `0.2.7`:
+Before publishing `0.2.9`:
 
 ```bash
 npm run typecheck
@@ -230,16 +151,16 @@ npm run test:e2e
 npm run rc:check
 ```
 
-Observability Platform v2 validation covers:
+Job Scheduling Platform validation covers:
 
-- counter/gauge/histogram behavior,
-- Prometheus exposition,
-- metric definition validation,
-- request count and duration middleware,
-- cardinality-safe default request labels,
-- health/readiness response semantics,
-- health check timeout handling,
-- public `bcp/observability` exports,
+- 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,
 - docs/platform/API version parity.
 
@@ -247,17 +168,4 @@ The final release tag must point to the exact commit that passed the complete RC
 
 ## Repository authority
 
-The framework repository remains authoritative for:
-
-```text
-source
-public exports
-tests
-Markdown docs
-docs-web manifest
-platform manifest
-API manifest
-release notes
-```
-
-`bcp-docs-web` remains the presentation/search/navigation layer for this content.
+The framework repository remains authoritative for source, public exports, tests, Markdown docs, manifests and release notes. `bcp-docs-web` remains the presentation/search/navigation layer.

package/docs/api-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [
@@ -94,6 +94,18 @@
         "/docs/session-auth"
       ]
     },
+    {
+      "package": "bcp/jobs",
+      "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.",
+      "guides": [
+        "/docs/background-jobs",
+        "/docs/job-scheduling",
+        "/docs/observability"
+      ]
+    },
     {
       "package": "bcp/observability",
       "source": "packages/client/src/observability.ts",