@chidchanun/bcp 0.2.11 → 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.11 — Workflow Orchestration`
+> **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
@@ -39,53 +39,55 @@ Framework source and tests remain authoritative for runtime behavior.
 | `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.11 — Workflow Orchestration
+## 0.2.12 — Transactional Outbox & Events
 
-`0.2.11` adds a new server-only `bcp/workflow` public entrypoint for persistent multi-step backend orchestration.
-
-New/updated documentation sources:
-
-| Source | Purpose |
-| --- | --- |
-| `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 |
+`0.2.12` adds the server-only `bcp/events` public entrypoint.
 
 Primary APIs:
 
 ```ts
 import {
-    createMemoryWorkflowStore,
-    createWorkflow,
-} from "bcp/workflow";
+    createEventBus,
+    createMemoryOutboxStore,
+    createOutboxDispatcher,
+    createOutboxMigrationSql,
+    createSqlOutboxStore,
+    createTransactionalOutbox,
+} from "bcp/events";
 ```
 
-Runtime model:
+The central write model is:
 
 ```text
-application / API
+BCP Database transaction
        |
-       v
-WorkflowStore
-       |
-       v
-BCP Workflow
+       +-- business data
+       +-- SQL outbox event
        |
-       +--> sequential steps
-       +--> parallel groups
-       +--> retry / delay
-       +--> compensation
+     COMMIT
        |
        v
-optional durable bcp/jobs queue
+Outbox Dispatcher
+       |
+       +-- bcp/jobs
+       +-- custom publisher
+       +-- local EventBus
 ```
 
-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.
+`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
 
@@ -94,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 |
 | --- | --- |
@@ -113,17 +113,15 @@ Important current routes:
 | `/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/transactional-outbox-events` | `transactional-outbox-events.md` |
 | `/docs/database` | `database.md` |
 | `/docs/api-reference` | `api-reference.md` |
-| `/releases/0.2.11` | `releases/0.2.11.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 +133,7 @@ bcp/database
 bcp/auth
 bcp/jobs
 bcp/workflow
+bcp/events
 bcp/observability
 bcp/server
 bcp/server-only
@@ -145,29 +144,27 @@ The API-manifest entrypoint set must match the platform public-entrypoint set ex
 
 ## Release validation
 
-Before publishing `0.2.11`:
+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
 ```
 
-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,
+Transactional Outbox & Events validation covers:
+
+- 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.11",
+  "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,7 @@
         "/docs/background-jobs",
         "/docs/job-scheduling",
         "/docs/durable-jobs",
+        "/docs/transactional-outbox-events",
         "/docs/observability"
       ]
     },
@@ -119,6 +121,19 @@
         "/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": "bcp/observability",
       "source": "packages/client/src/observability.ts",

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,104 +68,17 @@ 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.
 
-```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";
-```
-
-Scheduling APIs:
-
-```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";
-```
-
-Durable Redis-compatible APIs added in `0.2.10`:
-
-```ts
-import {
-    createRedisJobQueueAdapter,
-    createRedisJobScheduleStore,
-    type RedisCommandClient,
-    type RedisJobQueueAdapter,
-    type RedisJobsAdapterOptions,
-    type RedisJobScheduleStore,
-} from "bcp/jobs";
-```
-
-### Queue lifecycle
+Scheduling APIs include `createJobScheduler()`, `createMemoryJobScheduleStore()`, `nextCronTime()` and `nextScheduleTime()`.
 
-`createJobQueue()` supports immediate/delayed enqueue, retry/backoff, cancellation, manual `processNext()`, worker concurrency, visibility timeout, heartbeat lease renewal, stale-running recovery, DLQ inspection/requeue, terminal retention cleanup and queue statistics.
-
-Durable adapter methods such as `heartbeat()`, `recoverStale()`, `listDeadLetters()`, `requeueDeadLetter()`, `cleanup()` and `stats()` are optional so earlier `JobQueueAdapter` implementations remain compatible.
-
-`reserve()` receives an optional second `ReserveJobOptions` argument containing `ownerId` and `visibilityTimeoutMs`. Production durable adapters should use it to create an atomic visibility lease.
-
-### Scheduling
-
-`createJobScheduler()` supports recurring interval and UTC five-field cron schedules.
-
-The scheduler leases due records from `JobScheduleStore`, then enqueues normal jobs using deterministic occurrence IDs. `nextCronTime()` and `nextScheduleTime()` are available for tooling and tests.
-
-### Redis-compatible durable adapters
-
-`createRedisJobQueueAdapter()` implements the queue contract on a shared Redis-compatible command client.
-
-`createRedisJobScheduleStore()` implements the schedule-store contract using the same minimal client shape:
-
-```ts
-interface RedisCommandClient {
-    sendCommand(
-        command: string[]
-    ): Promise<unknown>;
-}
-```
+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 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.
-
 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), [Observability Platform v2](observability.md).
+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`
 
@@ -175,29 +88,10 @@ Server-only Workflow Orchestration APIs added in `0.2.11`.
 import {
     createMemoryWorkflowStore,
     createWorkflow,
-    type CancelWorkflowOptions,
-    type MemoryWorkflowStore,
-    type ResumeWorkflowOptions,
-    type StartWorkflowOptions,
-    type Workflow,
-    type WorkflowBuilder,
-    type WorkflowCompensationHandler,
-    type WorkflowOptions,
-    type WorkflowParallelBuilder,
-    type WorkflowRetryDelay,
-    type WorkflowRunRecord,
-    type WorkflowRunState,
-    type WorkflowStepContext,
-    type WorkflowStepHandler,
-    type WorkflowStepKind,
-    type WorkflowStepOptions,
-    type WorkflowStepRecord,
-    type WorkflowStepState,
-    type WorkflowStore,
 } from "bcp/workflow";
 ```
 
-`createWorkflow()` defines a persistent server-side workflow with sequential steps, parallel groups, per-step retry policies, persisted delays and compensation handlers.
+`createWorkflow()` defines persistent server-side workflows with sequential steps, parallel groups, per-step retry policies, persisted delays and compensation handlers.
 
 Workflow controls include:
 
@@ -213,17 +107,99 @@ compensate()
 close()
 ```
 
-Without a queue, workflow execution runs in the current process until it succeeds, fails, is cancelled or reaches a persisted delay.
+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 {
+    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";
+```
+
+### Transactional publishing
 
-When an existing `BackgroundJobQueue` is passed through `WorkflowOptions.queue`, workflow execution is submitted through `bcp/jobs`. Delay steps enqueue delayed continuation jobs instead of holding a long-running timer.
+`createTransactionalOutbox()` exposes `publish(transaction, type, payload, options)`.
 
-`WorkflowStore` is the workflow persistence boundary. Its `claim()` / `release()` methods form the run-level lease contract for shared multi-instance stores.
+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.
 
-`createMemoryWorkflowStore()` is intended for development and deterministic tests. Production multi-instance applications should implement a shared durable store with atomic `claim()` behavior.
+### SQL store
 
-Compensation is saga-style and executes successful compensatable steps in reverse completion order. It does not turn external services into one distributed database transaction.
+`createSqlOutboxStore()` supports MySQL, PostgreSQL and SQLite through the existing BCP database abstraction.
 
-Related guides: [Workflow Orchestration](workflow-orchestration.md), [Durable Jobs Platform](durable-jobs.md), [Observability Platform v2](observability.md).
+`createOutboxMigrationSql()` generates the outbox table/index DDL for those providers.
+
+The SQL store persists payload/metadata, correlation/causation/aggregate IDs, retry counts, state timestamps and dispatcher lease information.
+
+### Dispatcher
+
+`createOutboxDispatcher()` supports:
+
+```text
+batched claim
+dispatcher lease
+stale recovery
+retry/backoff
+terminal failure
+durable job queue handoff
+custom publisher callback
+in-process EventBus delivery
+runner lifecycle
+```
+
+With `queue` configured, event `order.created` is enqueued as `event.order.created` using stable job ID `outbox:<event-id>`.
+
+### Stores
+
+`OutboxStore` is the persistence and concurrency boundary.
+
+`createMemoryOutboxStore()` is intended for tests and single-process development. It does not provide durable transactional persistence.
+
+### 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: [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.11",
+  "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, workflow orchestration, 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" },
@@ -112,7 +113,8 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.11", "source": "releases/0.2.11.md", "version": "0.2.11", "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" },

package/docs/platform-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "releaseState": "unreleased",
-  "baseline": "workflow-orchestration",
+  "baseline": "transactional-outbox-events",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -21,6 +21,7 @@
     "bcp/auth",
     "bcp/jobs",
     "bcp/workflow",
+    "bcp/events",
     "bcp/observability",
     "bcp/server",
     "bcp/server-only",
@@ -100,6 +101,16 @@
     "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,
@@ -139,7 +150,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.10",
+    "previousBaseline": "0.2.11",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -160,7 +171,8 @@
     "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.11.md"
+    "releaseNotes": "releases/0.2.12.md"
   }
 }