@chidchanun/bcp 0.2.10 → 0.2.12

package/docs/README.md

@@ -2,13 +2,13 @@
 
 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.12 — Transactional Outbox & Events`
 >
 > **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
 
 ## Documentation architecture
 
-BCP uses three machine-readable documentation contracts:
+BCP uses three machine-readable contracts:
 
 ```text
 docs/docs-web-manifest.json
@@ -38,56 +38,56 @@ 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.12` | Transactional Outbox & Events |
 
-## 0.2.10 — Durable Jobs Platform
+## 0.2.12 — Transactional Outbox & Events
 
-`0.2.10` makes the queue/scheduler contracts production-oriented without changing the `bcp/jobs` public entrypoint.
+`0.2.12` adds the server-only `bcp/events` public entrypoint.
 
-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 |
-
-Primary durable APIs:
+Primary APIs:
 
 ```ts
 import {
-    createJobQueue,
-    createRedisJobQueueAdapter,
-    createRedisJobScheduleStore,
-} from "bcp/jobs";
+    createEventBus,
+    createMemoryOutboxStore,
+    createOutboxDispatcher,
+    createOutboxMigrationSql,
+    createSqlOutboxStore,
+    createTransactionalOutbox,
+} from "bcp/events";
 ```
 
-Runtime model:
+The central write model is:
 
 ```text
-web / API / action
-        |
-        v
-shared JobQueueAdapter
-        |
-        +--> visibility lease + heartbeat
-        +--> retry / stale recovery
-        +--> DLQ / requeue
-        |
-        v
-worker processes
-
-scheduler processes
-        |
-        v
-shared JobScheduleStore lease
+BCP Database transaction
+       |
+       +-- business data
+       +-- SQL outbox event
+       |
+     COMMIT
+       |
+       v
+Outbox Dispatcher
+       |
+       +-- bcp/jobs
+       +-- custom publisher
+       +-- local EventBus
 ```
 
-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.
+`createSqlOutboxStore()` supports MySQL, PostgreSQL and SQLite and writes the event using the caller-provided `TransactionDatabase`. The dispatcher adds leasing, stale recovery, retry/backoff and terminal failure handling after commit.
+
+New/updated documentation sources:
+
+| Source | Purpose |
+| --- | --- |
+| `transactional-outbox-events.md` | Transactional publishing, SQL migration, dispatcher lifecycle and delivery guarantees |
+| `api-reference.md` | `bcp/events` public APIs |
+| `platform-manifest.json` | Events capability flags and public entrypoint |
+| `api-manifest.json` | `bcp/events` source/guide ownership |
+| `docs-web-manifest.json` | Outbox docs navigation and `0.2.12` release route |
+| `releases/0.2.12.md` | Transactional Outbox & Events release notes |
 
 ## Update rule
 
@@ -96,15 +96,13 @@ When framework behavior or public surface changes:
 1. Update framework source.
 2. Add/update regression tests.
 3. Update the matching Markdown guide.
-4. Update `platform-manifest.json` when runtime/public-entrypoint/capability metadata changes.
-5. Update `api-manifest.json` when public API ownership/guide mapping changes.
-6. Update `docs-web-manifest.json` when website routes/navigation change.
+4. Update `platform-manifest.json` for runtime/public-entrypoint/capability changes.
+5. Update `api-manifest.json` for public API ownership/guide changes.
+6. Update `docs-web-manifest.json` for website route/navigation changes.
 7. Update `docs/releases/<version>.md`.
 8. Change release state only after the release workflow reaches that state.
 
-## Docs-web navigation
-
-Important current routes:
+## Important docs-web routes
 
 | Website route | Markdown source |
 | --- | --- |
@@ -114,17 +112,16 @@ Important current routes:
 | `/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/workflow-orchestration` | `workflow-orchestration.md` |
+| `/docs/transactional-outbox-events` | `transactional-outbox-events.md` |
 | `/docs/database` | `database.md` |
 | `/docs/api-reference` | `api-reference.md` |
-| `/releases/0.2.10` | `releases/0.2.10.md` |
+| `/releases/0.2.12` | `releases/0.2.12.md` |
 
 Every route/source pair is validated by unit tests.
 
 ## Public entrypoints
 
-Current documented entrypoints:
-
 ```text
 bcp
 bcp/island
@@ -135,6 +132,8 @@ bcp/error
 bcp/database
 bcp/auth
 bcp/jobs
+bcp/workflow
+bcp/events
 bcp/observability
 bcp/server
 bcp/server-only
@@ -145,27 +144,27 @@ The API-manifest entrypoint set must match the platform public-entrypoint set ex
 
 ## Release validation
 
-Before publishing `0.2.10`:
+Before publishing `0.2.12`:
 
 ```bash
 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
 ```
 
-Durable Jobs Platform validation covers:
+Transactional Outbox & Events 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,
+- transaction-bound SQL outbox insertion,
+- queue handoff,
+- custom/event-bus delivery,
+- retry and terminal failure,
+- dispatcher lease recovery,
+- MySQL/PostgreSQL/SQLite migration generation,
+- server-only browser boundary enforcement,
+- compiled `events.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.12",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [
@@ -77,7 +77,8 @@
       "summary": "Provider-neutral MySQL, PostgreSQL and SQLite query, transaction, lifecycle and migration primitives.",
       "guides": [
         "/docs/database",
-        "/docs/database-migrations"
+        "/docs/database-migrations",
+        "/docs/transactional-outbox-events"
       ]
     },
     {
@@ -104,6 +105,32 @@
         "/docs/background-jobs",
         "/docs/job-scheduling",
         "/docs/durable-jobs",
+        "/docs/transactional-outbox-events",
+        "/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/events",
+      "source": "packages/client/src/events.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-events",
+      "summary": "Transactional outbox and event delivery APIs with SQL persistence, dispatcher leases, retries, stale recovery, queue handoff and in-process event bus delivery.",
+      "guides": [
+        "/docs/transactional-outbox-events",
+        "/docs/database",
+        "/docs/durable-jobs",
         "/docs/observability"
       ]
     },

package/docs/api-reference.md

@@ -54,7 +54,7 @@ Server-only Database Platform v2 APIs.
 
 Built-in SQL providers are MySQL, PostgreSQL and SQLite. `BcpDatabase` instances expose lazy query/execute/transaction operations plus explicit `connect()`, `disconnect()` and backward-compatible `close()` lifecycle methods.
 
-Related guides: [Database](database.md), [Database Migrations](database-migrations.md).
+Related guides: [Database](database.md), [Database Migrations](database-migrations.md), [Transactional Outbox & Events](transactional-outbox-events.md).
 
 ## `bcp/auth`
 
@@ -68,118 +68,138 @@ Related guides: [Authentication](authentication.md), [Auth Session Stores](auth-
 
 Server-only Background Jobs, Job Scheduling and Durable Jobs APIs.
 
-Core queue APIs:
+Core queue APIs include `createJobQueue()`, `createMemoryJobQueueAdapter()`, queue/worker records, retry/backoff, visibility leases, heartbeat renewal, stale recovery, DLQ operations, retention cleanup and queue statistics.
+
+Scheduling APIs include `createJobScheduler()`, `createMemoryJobScheduleStore()`, `nextCronTime()` and `nextScheduleTime()`.
+
+Durable Redis-compatible APIs added in `0.2.10` include `createRedisJobQueueAdapter()` and `createRedisJobScheduleStore()`.
+
+BCP does not install a Redis library and does not create the connection. Applications own authentication, TLS, Cluster/Sentinel configuration and connection shutdown.
+
+The processing model is at-least-once. Handlers that perform non-idempotent external side effects should use application-level idempotency protection.
+
+Related guides: [Background Jobs Platform](background-jobs.md), [Job Scheduling Platform](job-scheduling.md), [Durable Jobs Platform](durable-jobs.md), [Transactional Outbox & Events](transactional-outbox-events.md), [Observability Platform v2](observability.md).
+
+## `bcp/workflow`
+
+Server-only Workflow Orchestration APIs added in `0.2.11`.
 
 ```ts
 import {
-    createJobQueue,
-    createMemoryJobQueueAdapter,
-    type BackgroundJobQueue,
-    type CleanupJobsOptions,
-    type DeadLetterJobRecord,
-    type EnqueueJobOptions,
-    type HeartbeatJobOptions,
-    type JobHandler,
-    type JobHandlerContext,
-    type JobQueueAdapter,
-    type JobQueueOptions,
-    type JobQueueStats,
-    type JobRecord,
-    type JobRetryDelay,
-    type JobState,
-    type JobWorker,
-    type MemoryJobQueueAdapter,
-    type ProcessNextJobOptions,
-    type RecoverStaleJobsOptions,
-    type RequeueDeadLetterOptions,
-    type ReserveJobOptions,
-    type StartJobWorkerOptions,
-} from "bcp/jobs";
+    createMemoryWorkflowStore,
+    createWorkflow,
+} from "bcp/workflow";
 ```
 
-Scheduling APIs:
+`createWorkflow()` defines persistent server-side workflows with sequential steps, parallel groups, per-step retry policies, persisted delays and compensation handlers.
 
-```ts
-import {
-    createJobScheduler,
-    createMemoryJobScheduleStore,
-    nextCronTime,
-    nextScheduleTime,
-    type JobSchedule,
-    type JobScheduleRecord,
-    type JobScheduleStore,
-    type JobScheduler,
-    type JobSchedulerOptions,
-    type JobSchedulerRunner,
-    type MemoryJobScheduleStore,
-    type RunDueSchedulesOptions,
-    type ScheduleJobOptions,
-    type StartJobSchedulerOptions,
-} from "bcp/jobs";
+Workflow controls include:
+
+```text
+start()
+run()
+get()
+list()
+resume()
+retry()
+cancel()
+compensate()
+close()
 ```
 
-Durable Redis-compatible APIs added in `0.2.10`:
+When an existing `BackgroundJobQueue` is supplied, workflow execution and delay continuation can run through `bcp/jobs`.
+
+`WorkflowStore.claim()` / `release()` form the run-level lease boundary for multi-instance stores.
+
+Related guides: [Workflow Orchestration](workflow-orchestration.md), [Durable Jobs Platform](durable-jobs.md), [Observability Platform v2](observability.md).
+
+## `bcp/events`
+
+Server-only Transactional Outbox & Events APIs added in `0.2.12`.
 
 ```ts
 import {
-    createRedisJobQueueAdapter,
-    createRedisJobScheduleStore,
-    type RedisCommandClient,
-    type RedisJobQueueAdapter,
-    type RedisJobsAdapterOptions,
-    type RedisJobScheduleStore,
-} from "bcp/jobs";
+    createEventBus,
+    createMemoryOutboxStore,
+    createOutboxDispatcher,
+    createOutboxMigrationSql,
+    createSqlOutboxStore,
+    createTransactionalOutbox,
+    type ClaimOutboxEventsOptions,
+    type CleanupOutboxOptions,
+    type EventBus,
+    type FailOutboxEventOptions,
+    type MemoryOutboxStore,
+    type OutboxDispatcher,
+    type OutboxDispatcherOptions,
+    type OutboxDispatcherRunner,
+    type OutboxEventHandler,
+    type OutboxEventHandlerContext,
+    type OutboxEventRecord,
+    type OutboxEventState,
+    type OutboxRetryDelay,
+    type OutboxStats,
+    type OutboxStore,
+    type PublishOutboxEventOptions,
+    type SqlOutboxStore,
+    type SqlOutboxStoreOptions,
+    type TransactionalOutbox,
+    type TransactionalOutboxOptions,
+} from "bcp/events";
 ```
 
-### Queue lifecycle
+### Transactional publishing
 
-`createJobQueue()` supports:
+`createTransactionalOutbox()` exposes `publish(transaction, type, payload, options)`.
 
-```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
-```
+The supplied `TransactionDatabase` is the same object received inside `db.transaction()`, allowing the application row and outbox event row to commit or roll back together.
 
-Durable adapter methods such as `heartbeat()`, `recoverStale()`, `listDeadLetters()`, `requeueDeadLetter()`, `cleanup()` and `stats()` are optional so earlier `JobQueueAdapter` implementations remain compatible.
+### SQL store
 
-`reserve()` receives an optional second `ReserveJobOptions` argument containing `ownerId` and `visibilityTimeoutMs`. Production durable adapters should use it to create an atomic visibility lease.
+`createSqlOutboxStore()` supports MySQL, PostgreSQL and SQLite through the existing BCP database abstraction.
 
-### Scheduling
+`createOutboxMigrationSql()` generates the outbox table/index DDL for those providers.
 
-`createJobScheduler()` supports recurring interval and UTC five-field cron schedules.
+The SQL store persists payload/metadata, correlation/causation/aggregate IDs, retry counts, state timestamps and dispatcher lease information.
 
-The scheduler leases due records from `JobScheduleStore`, then enqueues normal jobs using deterministic occurrence IDs. `nextCronTime()` and `nextScheduleTime()` are available for tooling and tests.
+### Dispatcher
 
-### Redis-compatible durable adapters
+`createOutboxDispatcher()` supports:
 
-`createRedisJobQueueAdapter()` implements the queue contract on a shared Redis-compatible command client.
+```text
+batched claim
+dispatcher lease
+stale recovery
+retry/backoff
+terminal failure
+durable job queue handoff
+custom publisher callback
+in-process EventBus delivery
+runner lifecycle
+```
 
-`createRedisJobScheduleStore()` implements the schedule-store contract using the same minimal client shape:
+With `queue` configured, event `order.created` is enqueued as `event.order.created` using stable job ID `outbox:<event-id>`.
 
-```ts
-interface RedisCommandClient {
-    sendCommand(
-        command: string[]
-    ): Promise<unknown>;
-}
-```
+### Stores
 
-BCP does not install a Redis library and does not create the connection. Applications own authentication, TLS, Cluster/Sentinel configuration and connection shutdown.
+`OutboxStore` is the persistence and concurrency boundary.
 
-The reference adapters use atomic Lua state transitions. The default namespace `bcp:{jobs}` uses a Redis Cluster hash tag so all job/schedule keys share one slot.
+`createMemoryOutboxStore()` is intended for tests and single-process development. It does not provide durable transactional persistence.
 
-The processing model is at-least-once. Handlers that perform non-idempotent external side effects should use application-level idempotency protection.
+### States
+
+```text
+pending
+processing
+published
+failed
+```
+
+`published` means the configured dispatcher destination accepted the event. It does not mean a downstream queued consumer has completed.
+
+Delivery is at-least-once; consumers should use idempotency controls for non-repeatable external side effects.
 
-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).
+Related guides: [Transactional Outbox & Events](transactional-outbox-events.md), [Database](database.md), [Durable Jobs Platform](durable-jobs.md), [Observability Platform v2](observability.md).
 
 ## `bcp/observability`
 

package/docs/docs-web-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.2.10",
+  "versionTarget": "0.2.12",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -48,16 +48,17 @@
     {
       "id": "database",
       "title": "Database",
-      "description": "Provider-neutral MySQL, PostgreSQL and SQLite primitives, lifecycle and migrations.",
+      "description": "Provider-neutral MySQL, PostgreSQL and SQLite primitives, lifecycle, migrations and transactional outbox integration.",
       "pages": [
         { "route": "/docs/database", "source": "database.md", "title": "Database" },
-        { "route": "/docs/database-migrations", "source": "database-migrations.md", "title": "Database Migrations" }
+        { "route": "/docs/database-migrations", "source": "database-migrations.md", "title": "Database Migrations" },
+        { "route": "/docs/transactional-outbox-events", "source": "transactional-outbox-events.md", "title": "Transactional Outbox & Events" }
       ]
     },
     {
       "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, event delivery, 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 +67,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 +113,9 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.10", "source": "releases/0.2.10.md", "version": "0.2.10", "state": "unreleased" },
+    { "route": "/releases/0.2.12", "source": "releases/0.2.12.md", "version": "0.2.12", "state": "unreleased" },
+    { "route": "/releases/0.2.11", "source": "releases/0.2.11.md", "version": "0.2.11" },
+    { "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.12",
   "releaseState": "unreleased",
-  "baseline": "durable-jobs-platform",
+  "baseline": "transactional-outbox-events",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -20,6 +20,8 @@
     "bcp/database",
     "bcp/auth",
     "bcp/jobs",
+    "bcp/workflow",
+    "bcp/events",
     "bcp/observability",
     "bcp/server",
     "bcp/server-only",
@@ -90,6 +92,25 @@
     "deadLetterRequeue": true,
     "jobRetentionCleanup": true,
     "jobQueueStatistics": true,
+    "workflowOrchestration": true,
+    "workflowStoreContract": true,
+    "workflowRunLeases": true,
+    "workflowSequentialSteps": true,
+    "workflowParallelSteps": true,
+    "workflowStepRetries": true,
+    "workflowDelays": true,
+    "workflowCompensation": true,
+    "workflowQueueExecution": true,
+    "transactionalOutboxEvents": true,
+    "outboxStoreContract": true,
+    "sqlOutboxStore": true,
+    "outboxDispatcher": true,
+    "outboxDispatcherLeases": true,
+    "outboxRetryRecovery": true,
+    "outboxRetentionCleanup": true,
+    "outboxStatistics": true,
+    "eventBus": true,
+    "outboxJobDelivery": true,
     "databaseMigrations": true,
     "databaseAdapterContract": true,
     "databasePostgresql": true,
@@ -129,7 +150,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.9",
+    "previousBaseline": "0.2.11",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -149,7 +170,9 @@
     "backgroundJobs": "background-jobs.md",
     "jobScheduling": "job-scheduling.md",
     "durableJobs": "durable-jobs.md",
+    "workflowOrchestration": "workflow-orchestration.md",
+    "transactionalOutboxEvents": "transactional-outbox-events.md",
     "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.10.md"
+    "releaseNotes": "releases/0.2.12.md"
   }
 }