@chidchanun/bcp 0.2.10 → 0.2.12

package/docs/releases/0.2.11.md

@@ -0,0 +1,180 @@
+# BCP Framework 0.2.11 — Workflow Orchestration
+
+> Release state: unreleased development target until RC validation, tagging and npm publication complete.
+
+`0.2.11` adds server-side workflow orchestration on top of the durable jobs foundation introduced in `0.2.8`–`0.2.10`.
+
+## Highlights
+
+- new `bcp/workflow` server-only public entrypoint,
+- sequential workflow steps,
+- parallel step groups,
+- per-step retry policies,
+- persisted workflow delays,
+- manual resume/retry/cancel controls,
+- saga-style compensation in reverse completion order,
+- `WorkflowStore` persistence contract,
+- workflow run leases via atomic `claim()` / `release()`,
+- optional `bcp/jobs` queue-backed execution,
+- delayed workflow continuation through the job queue,
+- compiled `workflow.mjs` runtime in the npm package,
+- browser/client bundle boundary enforcement,
+- unit and prepared-package smoke coverage.
+
+## Basic API
+
+```ts
+import {
+    createWorkflow,
+} from "bcp/workflow";
+
+const onboarding =
+    createWorkflow<{
+        userId: number;
+    }>(
+        "user.onboarding",
+        workflow => {
+            workflow.step(
+                "profile",
+                createProfile
+            );
+
+            workflow.parallel(
+                "initialize",
+                parallel => {
+                    parallel.step(
+                        "preferences",
+                        createPreferences
+                    );
+                    parallel.step(
+                        "workspace",
+                        createWorkspace
+                    );
+                }
+            );
+
+            workflow.delay(
+                "cooldown",
+                1_000
+            );
+        }
+    );
+```
+
+## Queue-backed workflows
+
+Applications may provide an existing `BackgroundJobQueue`:
+
+```ts
+const workflow =
+    createWorkflow(
+        "order.fulfillment",
+        defineWorkflow,
+        {
+            queue: jobs,
+            store:
+                workflowStore,
+        }
+    );
+```
+
+`start()`, `retry()` and `resume()` then enqueue workflow execution rather than executing the run inline. Delay steps enqueue delayed continuation jobs.
+
+The queue retains responsibility for delivery, worker concurrency, visibility timeout, heartbeat and stale-job recovery.
+
+## Persistence
+
+`createMemoryWorkflowStore()` is included for development/tests.
+
+Production multi-instance deployments should implement `WorkflowStore` with shared durable storage. `claim()` must atomically lease a workflow run so multiple workers cannot execute the same run concurrently.
+
+## Retry behavior
+
+A step can define:
+
+```ts
+{
+    maxAttempts: 3,
+    retryDelayMs:
+        attempt =>
+            attempt * 1_000,
+}
+```
+
+A run that remains failed after its step retry policy is exhausted can later be retried with:
+
+```ts
+await workflow.retry(
+    runId
+);
+```
+
+Already-successful preceding steps remain complete.
+
+## Compensation
+
+Steps can define compensation handlers:
+
+```ts
+workflow.step(
+    "reserve-stock",
+    reserveStock,
+    {
+        compensate:
+            releaseStock,
+    }
+);
+```
+
+Then:
+
+```ts
+await workflow.compensate(
+    runId
+);
+```
+
+Successful compensatable steps execute in reverse completion order.
+
+## Delays
+
+Delay steps persist `waiting` state and `waitUntil` rather than holding a long-running process timer.
+
+Without a queue, application code calls `resume()` after the due time. With a queue, BCP schedules a delayed workflow continuation job.
+
+## Compatibility
+
+`0.2.11` is additive relative to `0.2.10`.
+
+Existing `bcp/jobs`, scheduler, Redis durable adapters and all prior public entrypoints remain supported.
+
+No intentional breaking changes are introduced from the `0.2.10` baseline.
+
+## Validation
+
+Before release:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:e2e
+npm run test:package
+npm run rc:check
+```
+
+Workflow validation covers:
+
+- sequential step execution,
+- transient step retry,
+- parallel groups,
+- persisted delay/resume semantics,
+- manual failed-run retry,
+- reverse compensation order,
+- queue-backed execution,
+- workflow store lease behavior,
+- browser bundle rejection,
+- compiled `workflow.mjs` package execution,
+- API/platform/docs manifest parity.
+
+The final release tag must point to the exact commit that passed the complete RC sequence.

package/docs/releases/0.2.12.md

@@ -0,0 +1,147 @@
+# BCP Framework 0.2.12 — Transactional Outbox & Events
+
+Release state: unreleased development target.
+
+`0.2.12` adds a server-only transactional outbox and event-delivery platform that bridges BCP Database transactions with durable jobs or application-owned publishers without performing external side effects inside the business transaction.
+
+## New public entrypoint
+
+```ts
+import {
+    createEventBus,
+    createMemoryOutboxStore,
+    createOutboxDispatcher,
+    createOutboxMigrationSql,
+    createSqlOutboxStore,
+    createTransactionalOutbox,
+} from "bcp/events";
+```
+
+`bcp/events` is server-only and receives the same browser/client boundary protection as `bcp/database`, `bcp/jobs` and `bcp/workflow`.
+
+## Transaction-bound outbox writes
+
+Application code can insert business rows and outbox rows through the same `TransactionDatabase`:
+
+```ts
+await db.transaction(async tx => {
+    await tx.execute(
+        "INSERT INTO orders ..."
+    );
+
+    await outbox.publish(
+        tx,
+        "order.created",
+        {
+            orderId: 42,
+        }
+    );
+});
+```
+
+`createSqlOutboxStore()` writes through the caller transaction rather than the root database connection.
+
+## SQL providers
+
+Provider-specific migration SQL is available for:
+
+```text
+mysql
+postgresql
+sqlite
+```
+
+The SQL store persists:
+
+- event ID/type/payload,
+- metadata,
+- correlation/causation/aggregate IDs,
+- state,
+- attempts/max attempts,
+- created/available/processing/published/failed timestamps,
+- delivery errors,
+- lease owner/expiry.
+
+## Dispatcher
+
+`createOutboxDispatcher()` adds:
+
+- batched claiming,
+- dispatcher leases,
+- stale-lease recovery,
+- retry/backoff,
+- terminal failed state,
+- durable job-queue handoff,
+- custom publisher delivery,
+- in-process EventBus delivery,
+- polling runner lifecycle,
+- cleanup/statistics through the store.
+
+## Durable job handoff
+
+With `queue: jobs`, event type:
+
+```text
+order.created
+```
+
+is handed off as:
+
+```text
+event.order.created
+```
+
+The queued payload contains the event envelope and uses stable job ID:
+
+```text
+outbox:<event-id>
+```
+
+A successful enqueue marks the outbox event `published`. Downstream job completion remains the responsibility of the job runtime.
+
+## Event bus
+
+`createEventBus()` provides local server-side handler registration and sequential event delivery for tests, local composition and single-process handlers.
+
+It is not a distributed durable broker.
+
+## States
+
+```text
+pending
+processing
+published
+failed
+```
+
+Expired `processing` leases can return to `pending` for another dispatcher attempt.
+
+## Delivery semantics
+
+The platform closes the database-commit / external-publish gap but intentionally uses at-least-once delivery semantics.
+
+Consumers should use stable event IDs and application-level idempotency when duplicate external side effects are unsafe.
+
+## Backward compatibility
+
+`0.2.12` is additive relative to `0.2.11`:
+
+- existing `bcp/jobs` APIs remain unchanged,
+- existing `bcp/workflow` APIs remain unchanged,
+- no database adapter contract method was removed,
+- existing applications do not need an outbox unless they opt into `bcp/events`.
+
+## Validation
+
+The release candidate must pass:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:e2e
+npm run test:package
+npm run rc:check
+```
+
+Package validation executes the compiled `events.mjs` runtime and verifies the `bcp/events` export, transaction/outbox API, dispatcher delivery and migration helper.