@chidchanun/bcp 0.2.11 → 0.2.12

package/README.md

@@ -1,55 +1,37 @@
 # 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, workflow orchestration, 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, API routes, authentication, authorization, SQL databases, background jobs, scheduling, workflow orchestration, transactional events, observability, uploads, storage and standalone Node.js deployment.
 
-> **Development target:** `0.2.11 — Workflow Orchestration`
+> **Development target:** `0.2.12 — Transactional Outbox & Events`
 >
-> `0.2.11` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
+> `0.2.12` remains unreleased until local validation, RC checks, tagging and npm publication complete.
 
-## 0.2 platform
+## Current 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, `0.2.10` added durable worker leases/DLQ/Redis adapters, and `0.2.11` adds persistent multi-step workflow orchestration.
-
-Machine-readable platform contracts:
-
-```text
-docs/platform-manifest.json
-  -> runtime target, capabilities and compatibility
-
-docs/docs-web-manifest.json
-  -> documentation navigation, routes and releases
-
-docs/api-manifest.json
-  -> public package entrypoints and guide ownership
-```
-
-## Current capabilities
+BCP `0.2.x` currently includes:
 
 | Area | Capability |
 | --- | --- |
 | Application | React SSR, hydration, layouts, metadata and SPA navigation |
 | Routing | Static, dynamic, catch-all, optional catch-all and route groups |
-| Server data | Route `loader.ts`, request-scoped server APIs |
-| Mutations | Route-owned `actions.ts` and `<Form>` |
-| Authentication | JWT cookie sessions, optional server-side session stores, revocation, logout-all, idle timeout and rotation |
-| 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 |
+| Server data | Route loaders and request-scoped server APIs |
+| Mutations | Route-owned actions and `<Form>` |
+| Authentication | JWT cookie sessions, optional server-side stores, revocation, logout-all and idle timeout |
+| Authorization | Auth/guest/role/permission guards and resource-aware policies |
+| Security | Same-origin validation and signed CSRF tokens |
 | Middleware | Middleware System v2 with onion execution |
-| 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 |
-| Database | Provider-neutral MySQL, PostgreSQL and SQLite adapters, transactions, lifecycle and migrations |
-| Uploads | Buffered multipart helpers and production multipart streaming |
-| Storage | Local + S3-compatible storage, streaming, list/copy/move, metadata, bulk delete and signed URLs |
+| Database | MySQL, PostgreSQL and SQLite adapters, transactions, lifecycle and migrations |
+| Background jobs | Delay, retry/backoff, cancellation and concurrent workers |
+| Scheduling | Interval/UTC cron schedules and scheduler leases |
+| Durable jobs | Redis-compatible queue/schedule adapters, visibility timeout, heartbeat, stale recovery and DLQ |
+| Workflows | Sequential/parallel steps, retries, persisted delays, compensation and run leases |
+| Events | Transactional outbox, SQL persistence, dispatcher leases, retries, event bus and durable queue handoff |
+| Observability | Structured logs, metrics, Prometheus output and health/readiness checks |
+| Uploads & storage | Multipart streaming, Local/S3-compatible storage and signed URLs |
 | Caching | Response cache and revalidation primitives |
-| Configuration | Typed `bcp.config.*`, optional `bcp.environment.*`, startup diagnostics and `bcp config check` |
-| Developer tools | Generators, Doctor/Inspect v2, updater, route inspection and project metadata |
-| Production | Standalone Node.js build, application packaging, production dependency pruning, deployment manifests, Docker starter, hardening and graceful shutdown |
-| Documentation | Manifest-driven docs navigation, platform metadata and public API reference |
+| Configuration | Typed config/environment validation and diagnostics |
+| Production | Standalone Node.js build, packaging, dependency pruning, Docker starter and graceful shutdown |
+| Documentation | Manifest-driven docs, platform metadata and API reference |
 
 ## Requirements
 
@@ -57,7 +39,7 @@ docs/api-manifest.json
 - React `19`
 - npm
 
-Database drivers are optional and provider-specific:
+Optional SQL drivers:
 
 ```text
 MySQL       mysql2
@@ -73,7 +55,7 @@ cd my-app
 npm run dev
 ```
 
-Generated projects normally keep one framework dependency key:
+Generated projects normally use one framework dependency:
 
 ```json
 {
@@ -83,55 +65,7 @@ Generated projects normally keep one framework dependency key:
 }
 ```
 
-Do not install both `bcp` and a second direct `@chidchanun/bcp` dependency in the same application.
-
-## Configuration & environment
-
-Framework configuration stays in one of:
-
-```text
-bcp.config.ts
-bcp.config.mts
-bcp.config.js
-bcp.config.mjs
-```
-
-Application environment validation can be declared in:
-
-```text
-bcp.environment.ts
-bcp.environment.mts
-bcp.environment.js
-bcp.environment.mjs
-```
-
-Configuration precedence is:
-
-```text
-CLI override
-    ↓
-BCP_* environment
-    ↓
-bcp.config.*
-    ↓
-framework defaults
-```
-
-Validate configuration and declared environment values with:
-
-```bash
-bcp config check
-bcp config check --json
-```
-
-Variables beginning with `BCP_PUBLIC_` may be embedded in browser output. Never expose application secrets through public-prefixed variables.
-
-Read more:
-
-- [Configuration](docs/configuration.md)
-- [Environment Validation](docs/environment-validation.md)
-
-## Database Platform v2 — 0.2.3
+## Database Platform
 
 ```ts
 import {
@@ -140,14 +74,6 @@ import {
 } from "bcp/database";
 ```
 
-Built-in SQL providers:
-
-```text
-mysql
-postgresql
-sqlite
-```
-
 Migration CLI:
 
 ```bash
@@ -157,61 +83,17 @@ bcp db status
 bcp db rollback
 ```
 
-Read more:
-
-- [Database](docs/database.md)
-- [Database Migrations](docs/database-migrations.md)
-
-## Application Packaging — 0.2.4
-
-Create a fresh production build and deployment package:
-
-```bash
-bcp package
-```
-
-Output is written under:
-
-```text
-.bcp-framework/package/
-```
-
-Read more:
-
-- [Application Packaging](docs/application-packaging.md)
-- [Deployment](docs/deployment.md)
-
-## Authentication Platform v2 — 0.2.5
+## Authentication & authorization
 
 ```ts
 import {
-    auth,
     createAuth,
     createMemoryAuthSessionStore,
-    login,
-    logout,
-} from "bcp/auth";
-```
-
-Stateless signed JWT-cookie authentication remains supported. Applications that need centralized revocation can configure an `AuthSessionStore`.
-
-Read more:
-
-- [Authentication](docs/authentication.md)
-- [Auth Session Stores](docs/auth-session-store.md)
-- [Auth Route Guards](docs/auth-route-guards.md)
-
-## Authorization & Security v2 — 0.2.6
-
-```ts
-import {
-    authorize,
-    hasPermission,
     requirePermission,
 } from "bcp/auth";
 ```
 
-Request-security helpers are exposed from `bcp/server`:
+Request security is available from `bcp/server`:
 
 ```ts
 import {
@@ -221,9 +103,7 @@ import {
 } from "bcp/server";
 ```
 
-Read more: [Authorization & Security v2](docs/authorization-security.md)
-
-## Observability Platform v2 — 0.2.7
+## Observability
 
 ```ts
 import {
@@ -233,9 +113,7 @@ import {
 } from "bcp/observability";
 ```
 
-Read more: [Observability Platform v2](docs/observability.md)
-
-## Background Jobs Platform — 0.2.8
+## Background jobs
 
 ```ts
 import {
@@ -246,7 +124,7 @@ export const jobs =
     createJobQueue();
 ```
 
-Register work:
+Register typed work:
 
 ```ts
 jobs.register<{
@@ -261,24 +139,7 @@ jobs.register<{
 );
 ```
 
-Enqueue work:
-
-```ts
-await jobs.enqueue(
-    "email.welcome",
-    {
-        userId: 42,
-    },
-    {
-        delayMs: 5_000,
-        maxAttempts: 5,
-    }
-);
-```
-
-Read more: [Background Jobs Platform](docs/background-jobs.md)
-
-## Job Scheduling Platform — 0.2.9
+## Job scheduling
 
 ```ts
 import {
@@ -291,20 +152,7 @@ export const scheduler =
     });
 ```
 
-Interval schedule:
-
-```ts
-await scheduler.schedule(
-    "cache.cleanup",
-    {},
-    {
-        id: "cache-cleanup",
-        everyMs: 5 * 60 * 1000,
-    }
-);
-```
-
-UTC cron schedule:
+UTC cron example:
 
 ```ts
 await scheduler.schedule(
@@ -316,11 +164,9 @@ await scheduler.schedule(
 );
 ```
 
-Read more: [Job Scheduling Platform](docs/job-scheduling.md)
-
 ## Durable Jobs Platform — 0.2.10
 
-Workers 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:
 
 ```ts
 const worker =
@@ -329,68 +175,13 @@ const 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,
-    }
-);
-```
-
-Redis-compatible durable adapters:
-
-```ts
-import {
-    createJobQueue,
-    createJobScheduler,
-    createRedisJobQueueAdapter,
-    createRedisJobScheduleStore,
-} from "bcp/jobs";
-
-const queueAdapter =
-    createRedisJobQueueAdapter({
-        client: redisCommandClient,
-        namespace: "my-app:{jobs}",
-    });
-
-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",
     });
 ```
 
-BCP does not read `REDIS_URL` or own the Redis client connection lifecycle automatically.
-
-Read more: [Durable Jobs Platform](docs/durable-jobs.md)
+Redis-compatible adapters are available from `bcp/jobs`. BCP does not install or own the Redis client; applications provide a command client and manage credentials/TLS/Cluster/lifecycle themselves.
 
 ## Workflow Orchestration — 0.2.11
 
-Create a server-only workflow with typed input:
-
 ```ts
 import {
     createWorkflow,
@@ -404,11 +195,7 @@ export const onboarding =
         workflow => {
             workflow.step(
                 "profile",
-                async ({ input }) => {
-                    await createProfile(
-                        input.userId
-                    );
-                }
+                createProfile
             );
 
             workflow.parallel(
@@ -433,66 +220,157 @@ export const onboarding =
     );
 ```
 
-Per-step retries:
+Workflows support retries, compensation and optional execution through the durable job queue.
+
+## Transactional Outbox & Events — 0.2.12
+
+`0.2.12` adds the server-only `bcp/events` entrypoint.
+
+The problem it solves:
+
+```text
+DB commit succeeds
+       +
+external publish fails
+       =
+missing integration event
+```
+
+The outbox writes the event in the **same SQL transaction** as the business data:
 
 ```ts
-workflow.step(
-    "charge-card",
-    chargeCard,
-    {
-        maxAttempts: 3,
-        retryDelayMs:
-            attempt =>
-                attempt * 1_000,
+import {
+    db,
+} from "bcp/database";
+
+import {
+    createSqlOutboxStore,
+    createTransactionalOutbox,
+} from "bcp/events";
+
+const outboxStore =
+    createSqlOutboxStore({
+        database: db,
+        driver: "postgresql",
+    });
+
+const outbox =
+    createTransactionalOutbox({
+        store: outboxStore,
+    });
+
+await db.transaction(
+    async tx => {
+        await tx.execute(
+            "INSERT INTO orders ..."
+        );
+
+        await outbox.publish(
+            tx,
+            "order.created",
+            {
+                orderId: 42,
+            },
+            {
+                aggregateId: "42",
+                correlationId: requestId,
+            }
+        );
     }
 );
 ```
 
-Saga-style compensation:
+Generate the outbox table migration for the configured provider:
 
 ```ts
-workflow.step(
-    "reserve-stock",
-    reserveStock,
-    {
-        compensate:
-            releaseStock,
-    }
-);
+import {
+    createOutboxMigrationSql,
+} from "bcp/events";
+
+const sql =
+    createOutboxMigrationSql(
+        "postgresql"
+    );
 ```
 
-A failed run can be compensated in reverse completion order:
+Supported providers:
+
+```text
+mysql
+postgresql
+sqlite
+```
+
+### Dispatcher
+
+After the SQL transaction commits, a dispatcher claims due events and delivers them:
 
 ```ts
-await onboarding.compensate(
-    runId
-);
+import {
+    createOutboxDispatcher,
+} from "bcp/events";
+
+export const dispatcher =
+    createOutboxDispatcher({
+        store: outboxStore,
+        queue: jobs,
+        ownerId: "outbox-a",
+        leaseMs: 30_000,
+        batchSize: 100,
+        pollIntervalMs: 1_000,
+    });
+
+const runner =
+    dispatcher.start();
+```
+
+With `queue: jobs`, event type:
+
+```text
+order.created
+```
+
+is handed off as:
+
+```text
+event.order.created
 ```
 
-For durable execution, supply an existing BCP job queue and a shared workflow store:
+Register its durable consumer:
 
 ```ts
-export const fulfillment =
-    createWorkflow(
-        "order.fulfillment",
-        defineWorkflow,
-        {
-            queue: jobs,
-            store:
-                workflowStore,
-        }
-    );
+jobs.register(
+    "event.order.created",
+    async ({ payload }) => {
+        await handleOrderCreated(
+            payload
+        );
+    }
+);
 ```
 
-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.
+Dispatcher features include:
 
-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.
+- batched claims,
+- lease ownership,
+- stale lease recovery,
+- retry/backoff,
+- terminal failed state,
+- queue delivery,
+- custom publisher callbacks,
+- local `EventBus`,
+- retention cleanup,
+- outbox statistics.
 
-Read more: [Workflow Orchestration](docs/workflow-orchestration.md)
+`published` means the configured destination accepted the event. For queue delivery, it means enqueue succeeded; it does not mean the downstream job handler has completed.
+
+Delivery remains **at-least-once**, so consumers that perform non-idempotent side effects should use stable event IDs/idempotency controls.
+
+Read more: [Transactional Outbox & Events](docs/transactional-outbox-events.md)
 
 ## Public entrypoints
 
-The current `0.2.x` platform contract recognizes:
+The current documented platform surface is:
 
 ```text
 bcp
@@ -505,24 +383,17 @@ bcp/database
 bcp/auth
 bcp/jobs
 bcp/workflow
+bcp/events
 bcp/observability
 bcp/server
 bcp/server-only
 bcp/middleware
 ```
 
-Application code should use public entrypoints instead of importing framework internals under `packages/`.
-
-See:
-
-- [API Reference](docs/api-reference.md)
-- [Platform Manifest](docs/platform-manifest.json)
-- [API Manifest](docs/api-manifest.json)
+Application code should use public entrypoints instead of importing private `packages/*` implementation files.
 
 ## CLI
 
-Core commands:
-
 ```bash
 bcp dev
 bcp build
@@ -536,16 +407,7 @@ bcp inspect
 bcp version
 ```
 
-Database migrations:
-
-```bash
-bcp db create create_users
-bcp db migrate
-bcp db status
-bcp db rollback
-```
-
-Project generators:
+Generators:
 
 ```bash
 bcp generate page dashboard/users
@@ -557,27 +419,35 @@ bcp generate migration create_users
 ## Production model
 
 ```text
-Browser / API clients
-        ↓
-security + middleware + auth
-        ↓
+Browser / API
+     |
+security + auth + middleware
+     |
 loaders / actions / API routes
-        ↓
-SSR / application responses
-
-Operational side channels:
-workflow orchestration
-        ↓
-shared jobs + scheduler
-        ↓
-workers + structured logs + metrics + health/readiness
+     |
+Database transaction
+     |\
+     | +--> transactional outbox
+     |          |
+     |      dispatcher
+     |          |
+     |      durable jobs
+     |          |
+     |       workers
+     |
+SSR / response
+
+Workflow + scheduler + logs + metrics + health
+operate alongside the request path.
 ```
 
-Raw standalone build:
+## Packaging
+
+Raw production build:
 
 ```bash
 npm run build
-npm run start
+npm start
 ```
 
 Deployment package:
@@ -590,31 +460,30 @@ bcp package
 
 The framework repository is the documentation source of truth.
 
-`bcp-docs-web` consumes:
+Machine-readable contracts:
 
 ```text
-docs/docs-web-manifest.json
 docs/platform-manifest.json
+docs/docs-web-manifest.json
 docs/api-manifest.json
 ```
 
 ## Release validation
 
-Framework releases must pass:
+Before publishing `0.2.12`:
 
 ```bash
-npm install
 npm run typecheck
 npm run test:unit
 npm run test:integration
-npm run test:package
 npm run test:e2e
+npm run test:package
 npm run rc:check
 ```
 
-`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.
+`0.2.12` adds unit and prepared-package smoke coverage for transaction-bound outbox writes, dispatcher queue handoff, retry/failure behavior, stale lease recovery, SQL migration generation, public export/runtime compilation and browser boundary enforcement.
 
-Do not tag or publish until the final release commit passes the complete RC sequence.
+Do not tag or publish until the exact final release commit passes the full RC sequence.
 
 ## Release history
 
@@ -638,12 +507,15 @@ Do not tag or publish until the final release commit passes the complete RC sequ
 | `0.2.9` | Job Scheduling Platform |
 | `0.2.10` | Durable Jobs Platform |
 | `0.2.11` | Workflow Orchestration |
+| `0.2.12` | Transactional Outbox & Events |
 
 ## Roadmap
 
-`0.2.11 — Workflow Orchestration` establishes persistent multi-step backend workflows on top of the provider-neutral jobs foundation.
+`0.2.12` closes the database-commit / external-publish gap and establishes a provider-neutral event-delivery boundary on top of Database + Durable Jobs.
+
+The next logical milestone is **`0.2.13 — Realtime Platform`**, adding WebSocket/SSE channels, rooms/presence, authenticated realtime connections and live delivery for workflow/job/event progress without changing the current outbox/job contracts.
 
-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.
+Native desktop/mobile compilation remains later roadmap work.
 
 ## License