@chidchanun/bcp 0.2.16 → 0.2.18

package/README.md

@@ -1,10 +1,10 @@
 # BCP Framework
 
-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, realtime delivery, framework-native testing, plugin/module composition, distributed caching, observability, uploads, storage and standalone Node.js 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, realtime delivery, framework-native testing, plugin/module composition, distributed caching, observability, deployment lifecycle, uploads, storage and standalone Node.js deployment.
 
-> **Development target:** `0.2.16 — Cache Platform v2`
+> **Development target:** `0.2.18 — Deployment Platform v2`
 >
-> `0.2.16` remains unreleased until local validation, RC checks, tagging and npm publication complete.
+> `0.2.18` remains unreleased until local validation, RC checks, tagging and npm publication complete.
 
 ## Current platform
 
@@ -27,11 +27,12 @@ BCP Framework is a React full-stack framework for file-based routing, SSR, SPA n
 | Realtime | Channels/rooms, presence, broker delivery, WebSocket adapter contract, SSE and heartbeat |
 | Testing | Request/route/page/auth/database/middleware/jobs/workflow/outbox/realtime/SSE test harnesses |
 | Plugins & modules | Dependency ordering, lifecycle hooks, config parsing, service registry and async extension hooks |
-| Caching | Legacy request/data cache plus Cache Platform v2 adapters, Redis-compatible cache/locks, stampede protection, TTL/tag/path invalidation and metrics |
-| Observability | Structured logs, metrics, Prometheus output and health/readiness checks |
+| Caching | Cache Platform v2 adapters, Redis-compatible cache/locks, stampede protection, TTL/tag/path invalidation and metrics |
+| Observability | Metrics, Prometheus, health/readiness, distributed tracing, W3C trace context and correlation IDs |
+| Deployment | Resource lifecycle, readiness, diagnostics, runtime identity, signal handling and graceful shutdown |
 | Uploads & storage | Multipart streaming, Local/S3-compatible storage and signed URLs |
 | Configuration | Typed config/environment validation and diagnostics |
-| Production | Standalone Node.js build, packaging, dependency pruning, Docker starter and graceful shutdown |
+| Production | Standalone Node.js build, compiled server entrypoints, packaging, dependency pruning and Docker starter |
 | Documentation | Manifest-driven docs, platform metadata and API reference |
 
 ## Requirements
@@ -78,468 +79,221 @@ import { createTransactionalOutbox } from "bcp/events";
 import { createRealtime } from "bcp/realtime";
 import { createTestApp } from "bcp/testing";
 import { createPluginHost } from "bcp/plugins";
-import { createMetricsRegistry } from "bcp/observability";
+import { createTracer } from "bcp/observability";
+import { createDeploymentRuntime } from "bcp/deployment";
 ```
 
-## Durable jobs and scheduling
+## Durable application infrastructure
 
-```ts
-import {
-    createJobQueue,
-    createJobScheduler,
-} from "bcp/jobs";
+BCP keeps durable application state separate from transient delivery:
 
-export const jobs =
-    createJobQueue();
-
-export const scheduler =
-    createJobScheduler({
-        queue: jobs,
-    });
+```text
+HTTP / API
+    |
+    +-- Database
+    |     +-- Transactional Outbox
+    |
+    +-- Jobs / Scheduler
+    |     +-- Workflow
+    |
+    +-- Realtime
+    |
+    +-- Cache
+    |
+    +-- Observability
+    |
+    +-- Deployment lifecycle
 ```
 
-Production adapters can provide Redis-compatible durable queue/schedule storage without BCP owning the Redis connection.
+Database/outbox/jobs/workflows remain durable truth. Realtime is transient delivery. Cache is an optimization layer. Tracing correlates operations without replacing state contracts.
 
-## Workflow Orchestration — 0.2.11
+## Deployment Platform v2 — 0.2.18
+
+`0.2.18` adds the server-only `bcp/deployment` entrypoint.
 
 ```ts
 import {
-    createWorkflow,
-} from "bcp/workflow";
-
-export 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
-            );
-        }
-    );
-```
+    createDeploymentRuntime,
+} from "bcp/deployment";
 
-Workflows support retries, compensation, persisted delays and optional durable queue execution.
-
-## Transactional Outbox & Events — 0.2.12
+export const deployment =
+    createDeploymentRuntime({
+        serviceName: "orders-api",
+        version: "1.0.0",
+    });
+```
 
-Use the same SQL transaction for business data and its outbox event:
+Register resources in dependency order:
 
 ```ts
-await db.transaction(
-    async tx => {
-        await tx.execute(
-            "INSERT INTO orders ..."
-        );
-
-        await outbox.publish(
-            tx,
-            "order.created",
-            {
-                orderId: 42,
-            }
-        );
-    }
-);
-```
+deployment.addResource({
+    name: "database",
 
-After commit, an outbox dispatcher can deliver through `bcp/jobs`, a custom publisher or the local event bus.
+    async start() {
+        await db.connect();
+    },
 
-Read more: [Transactional Outbox & Events](docs/transactional-outbox-events.md)
+    async ready() {
+        return db.status === "ready";
+    },
 
-## Realtime Platform — 0.2.13
+    async stop() {
+        await db.close();
+    },
+});
 
-```ts
-import {
-    createRealtime,
-} from "bcp/realtime";
+deployment.addResource({
+    name: "workers",
 
-export const realtime =
-    createRealtime();
-```
+    start() {
+        worker = jobs.startWorker();
+    },
 
-Join a channel and broadcast:
+    async stop() {
+        await worker.stop();
+    },
+});
 
-```ts
-const connection =
-    await realtime.connect();
-
-await connection.join(
-    "orders:42"
-);
-
-await realtime.broadcast(
-    "orders:42",
-    "order.updated",
-    {
-        status: "paid",
-    }
-);
+await deployment.start();
 ```
 
-BCP intentionally does not install a WebSocket server library. Applications adapt `ws`, uWebSockets.js or another transport to `RealtimeSocket`. SSE is built in through Web `Response`.
-
-Read more: [Realtime Platform](docs/realtime-platform.md)
-
-## Testing Platform — 0.2.14
-
-`0.2.14` adds the server-only `bcp/testing` entrypoint. It is test-runner neutral and does not add Jest or Vitest as framework dependencies.
+Startup follows registration order. Shutdown runs in reverse order, so workers can stop before their database/cache/Redis dependencies close. If startup fails midway, already-started resources are rolled back in reverse order.
 
-### Request and route tests
+Readiness:
 
 ```ts
 import {
-    createRouteTestHandler,
-    createTestApp,
-    expectResponse,
-} from "bcp/testing";
-
-const handler =
-    createRouteTestHandler({
-        GET() {
-            return {
-                ok: true,
-            };
-        },
-    });
-
-const app =
-    createTestApp({
-        handler,
-    });
+    createDeploymentReadinessResponse,
+} from "bcp/deployment";
 
-const response =
-    await app.get(
-        "/api/health"
+export function GET() {
+    return createDeploymentReadinessResponse(
+        deployment
     );
-
-await expectResponse(response)
-    .status(200)
-    .json({
-        ok: true,
-    });
+}
 ```
 
-`createTestApp()` keeps an in-memory cookie jar, supports default headers and can send JSON bodies directly.
-
-### Authentication tests
+A ready runtime returns `200`; starting, draining, failed or unhealthy runtimes return `503`.
 
-Create a real signed BCP session token instead of a fake test-only user header:
+Diagnostics:
 
 ```ts
 import {
-    createTestAuthSession,
-} from "bcp/testing";
-
-const session =
-    await createTestAuthSession(
-        {
-            id: 42,
-            role: "admin",
-        },
-        {
-            secret:
-                process.env.BCP_SESSION_SECRET,
-            store:
-                authSessionStore,
-        }
-    );
-
-app.setCookie(
-    session.cookieName,
-    session.token
-);
+    createDeploymentDiagnosticsResponse,
+} from "bcp/deployment";
 ```
 
-When `store` is provided, the matching server-side auth session record is inserted as well.
-
-### Rollback database tests
+Deployment metadata can use:
 
-```ts
-import {
-    withTestTransaction,
-} from "bcp/testing";
-
-await withTestTransaction(
-    db,
-    async tx => {
-        await tx.execute(
-            "INSERT INTO users ..."
-        );
-
-        // assertions run here
-    }
-);
+```text
+BCP_DEPLOYMENT_ID
+BCP_INSTANCE_ID
+BCP_RELEASE
+NODE_ENV
+BCP_SHUTDOWN_TIMEOUT_MS
 ```
 
-The callback uses the real BCP transaction and is deliberately rolled back after the test callback succeeds.
-
-### Infrastructure harnesses
+Signal ownership is optional:
 
 ```ts
-import {
-    createJobTestHarness,
-    createOutboxTestHarness,
-    createRealtimeTestHarness,
-    createWorkflowTestHarness,
-} from "bcp/testing";
+const removeSignalHandlers =
+    deployment.installSignalHandlers();
 ```
 
-These harnesses use the real platform contracts rather than separate mock implementations.
+Default signals are `SIGTERM` and `SIGINT`. BCP sets `process.exitCode` after graceful shutdown instead of immediately terminating the process.
 
-Background jobs:
+The runtime can also integrate with the existing framework shutdown registry:
 
 ```ts
-const jobTest =
-    createJobTestHarness(
-        jobs
-    );
-
-await jobTest.drain();
-
-await jobTest.expectCount(
-    1,
-    {
-        name: "email.welcome",
-        state: "succeeded",
-    }
-);
+const unregister =
+    deployment.registerShutdownHook();
 ```
 
-Realtime:
+Read more: [Deployment Platform v2](docs/deployment-platform-v2.md)
 
-```ts
-const realtimeTest =
-    createRealtimeTestHarness(
-        realtime
-    );
+## Compiled production entrypoints
 
-const {
-    socket,
-    connection,
-} =
-    await realtimeTest.connect();
-
-await connection.join(
-    "orders:42"
-);
-
-await realtime.broadcast(
-    "orders:42",
-    "order.updated",
-    {
-        status: "paid",
-    }
-);
-
-realtimeTest.expectEvent(
-    socket,
-    "order.updated",
-    "orders:42"
-);
-```
-
-Other testing primitives include:
+Prepared npm packages use compiled ESM for the main server runtime surfaces:
 
 ```text
-createFakeClock()
-createSequenceIdFactory()
-runTestMiddleware()
-createRealtimeTestSocket()
-readSseEvents()
-```
-
-Read more: [Testing Platform](docs/testing-platform.md)
-
-## Plugin & Module Platform — 0.2.15
-
-`0.2.15` adds the server-only `bcp/plugins` entrypoint for reusable application/framework extensions.
-
-Define plugins with explicit dependencies:
+bcp/cache          -> cache.mjs
+bcp/config         -> config.mjs
+bcp/database       -> database.mjs
+bcp/auth           -> auth.mjs
+bcp/jobs           -> jobs.mjs
+bcp/workflow       -> workflow.mjs
+bcp/events         -> events.mjs
+bcp/realtime       -> realtime.mjs
+bcp/testing        -> testing.mjs
+bcp/plugins        -> plugins.mjs
+bcp/observability  -> observability.mjs
+bcp/deployment     -> deployment.mjs
+bcp/server         -> server.mjs
+bcp/middleware     -> middleware.mjs
+```
+
+TypeScript source remains the type surface, while prepared production runtime resolution points to compiled `.mjs` files.
+
+## Observability Platform v3 — 0.2.17
 
 ```ts
 import {
-    createPluginHost,
-    definePlugin,
-} from "bcp/plugins";
-
-const databasePlugin =
-    definePlugin({
-        name: "database",
-        setup(context) {
-            context.services.provide(
-                "database",
-                db
-            );
-        },
-        start() {
-            return db.connect();
-        },
-        stop() {
-            return db.disconnect();
-        },
-    });
+    createTracer,
+} from "bcp/observability";
 
-const jobsPlugin =
-    definePlugin({
-        name: "jobs",
-        requires: [
-            "database",
-        ],
-    });
-
-const host =
-    createPluginHost({
-        plugins: [
-            jobsPlugin,
-            databasePlugin,
-        ],
-    });
-
-await host.start();
-```
-
-Dependency order is resolved automatically. Startup follows dependency order while stop/dispose runs in reverse order.
-
-Modules group reusable plugin sets:
-
-```ts
-import {
-    defineModule,
-} from "bcp/plugins";
-
-const backendModule =
-    defineModule({
-        name: "backend",
-        plugins: [
-            databasePlugin,
-            jobsPlugin,
-        ],
+export const tracer =
+    createTracer({
+        serviceName: "orders-api",
     });
 ```
 
-Plugin configuration can be parsed at setup time and overridden through `createPluginHost({ configs })`.
-
-Plugins share a service registry and awaited in-process hook bus through `context.services` and `context.hooks`.
+`bcp/observability` supports root/child spans, AsyncLocalStorage context, W3C `traceparent`, correlation IDs, request tracing, trace carriers, memory/composite exporters and trace-to-Prometheus metrics.
 
-If startup fails, already-started plugins are stopped in reverse order before the lifecycle error is propagated.
-
-Read more: [Plugin & Module Platform](docs/plugin-module-platform.md)
+Read more: [Observability Platform v3](docs/observability-v3.md)
 
 ## Cache Platform v2 — 0.2.16
 
-`0.2.16` keeps the original `cache()` and `dedupe()` APIs while adding provider-neutral asynchronous cache stores for production multi-instance applications.
-
-Create a cache store:
-
 ```ts
 import {
     createCacheStore,
+    createRedisCacheAdapter,
+    createRedisCacheLockAdapter,
 } from "bcp/cache";
-
-export const applicationCache =
-    createCacheStore();
 ```
 
-Cache-aside loading:
+Cache Store v2 supports local singleflight, distributed cache-fill leases, heartbeat renewal, TTL, tag/path invalidation and cache metrics while keeping the original `cache()` / `dedupe()` APIs available.
 
-```ts
-const user =
-    await applicationCache.getOrSet(
-        "user:42",
-        async () =>
-            loadUser(42),
-        {
-            ttlMs: 60_000,
-            tags: [
-                "users",
-            ],
-            paths: [
-                "/users/42",
-            ],
-        }
-    );
-```
+Read more: [Cache Platform v2](docs/cache-platform-v2.md)
 
-Within one store, concurrent misses share one loader automatically.
+## Plugin & Module Platform — 0.2.15
 
-For multiple application instances, use shared cache and lock adapters:
+`bcp/plugins` supports dependency ordering, setup/start/stop/dispose lifecycle, modules, config parsing, shared services and async hooks.
 
-```ts
-import {
-    createRedisCacheAdapter,
-    createRedisCacheLockAdapter,
-} from "bcp/cache";
+Read more: [Plugin & Module Platform](docs/plugin-module-platform.md)
 
-const redisCache =
-    createRedisCacheAdapter({
-        client: redisClient,
-    });
+## Testing Platform — 0.2.14
 
-const redisLock =
-    createRedisCacheLockAdapter({
-        client: redisClient,
-    });
+`bcp/testing` provides runner-neutral request/route/page/auth/database/middleware/jobs/workflow/outbox/realtime/SSE test helpers.
 
-export const cache =
-    createCacheStore({
-        adapter: redisCache,
-        lock: redisLock,
-    });
-```
+Read more: [Testing Platform](docs/testing-platform.md)
 
-The default Redis namespace is `bcp:{cache}`. BCP does not install or own a Redis library/connection.
+## Realtime Platform — 0.2.13
 
-Distributed `getOrSet()` uses owner-scoped lock leases, heartbeat renewal when supported, double-check-after-lock, contention wait/poll and configurable lock-timeout behavior.
+`bcp/realtime` provides channels/rooms, presence, broker delivery, provider-neutral socket adapters, SSE and heartbeat handling.
 
-Tag/path invalidation remains available through the new async store:
+Read more: [Realtime Platform](docs/realtime-platform.md)
 
-```ts
-await cache.revalidateTag(
-    "users"
-);
+## Transactional Outbox & Events — 0.2.12
 
-await cache.revalidatePath(
-    "/dashboard"
-);
-```
+Use `bcp/events` to persist integration events in the same SQL transaction as business data, then dispatch after commit through durable jobs or custom publishers.
 
-Connect cache events to BCP metrics:
+Read more: [Transactional Outbox & Events](docs/transactional-outbox-events.md)
 
-```ts
-const cache =
-    createCacheStore({
-        metrics:
-            createCacheMetrics(
-                metricsRegistry
-            ),
-    });
-```
+## Workflow Orchestration — 0.2.11
 
-Prepared npm packages compile `bcp/cache` to `cache.mjs` for standalone Node runtime use.
+`bcp/workflow` supports sequential/parallel steps, retries, persisted delays, run leases, compensation and optional durable queue execution.
 
-Read more: [Cache Platform v2](docs/cache-platform-v2.md)
+Read more: [Workflow Orchestration](docs/workflow-orchestration.md)
 
 ## Public entrypoints
 
@@ -559,6 +313,7 @@ bcp/realtime
 bcp/testing
 bcp/plugins
 bcp/observability
+bcp/deployment
 bcp/server
 bcp/server-only
 bcp/middleware
@@ -599,40 +354,23 @@ bcp generate middleware
 bcp generate migration create_users
 ```
 
-## Production model
-
-```text
-Browser / API / Realtime clients
-              |
-      security + auth
-              |
-          Plugin Host
-       /      |       \
- database  workflows  realtime
-    |          |         ^
- outbox       jobs       |
-    \__________|_________/
-           durable state
-              |
-       shared cache layer
-          Redis / other
-```
-
-Cache is an optimization layer and must not replace durable application truth or transactional invariants.
-
 ## Packaging
 
+Build and run directly:
+
 ```bash
 npm run build
 npm start
 ```
 
-Deployment package:
+Create a standalone deployment package:
 
 ```bash
 bcp package
 ```
 
+Application packages include production dependency manifests, deployment/environment metadata, file integrity metadata and a Docker starter while excluding `.env` secrets and application devDependencies.
+
 ## Documentation Platform
 
 Machine-readable contracts:
@@ -645,7 +383,7 @@ docs/api-manifest.json
 
 ## Release validation
 
-Before publishing `0.2.16`:
+Before publishing `0.2.18`:
 
 ```bash
 npm run typecheck
@@ -656,7 +394,7 @@ npm run test:package
 npm run rc:check
 ```
 
-`0.2.16` adds unit and prepared-package smoke coverage for TTL/tag/path invalidation, local singleflight, distributed lock contention, lock timeout behavior, Redis cache/lock command contracts, cache metrics and compiled `cache.mjs` execution.
+`0.2.18` adds unit and prepared-package smoke coverage for deployment lifecycle ordering, startup rollback, readiness/diagnostics, runtime metadata, server-only boundaries and compiled config/auth/observability/deployment/server/middleware runtimes.
 
 Do not tag or publish until the exact final release commit passes the full RC sequence.
 
@@ -687,12 +425,16 @@ Do not tag or publish until the exact final release commit passes the full RC se
 | `0.2.14` | Testing Platform |
 | `0.2.15` | Plugin & Module Platform |
 | `0.2.16` | Cache Platform v2 |
+| `0.2.17` | Observability Platform v3 |
+| `0.2.18` | Deployment Platform v2 |
 
 ## Roadmap
 
-`0.2.16` establishes provider-neutral shared caching and distributed cache-fill coordination while preserving the original process-local cache API.
+`0.2.18` establishes a consistent production lifecycle and compiled server runtime boundary for the current BCP 0.2.x platform.
+
+The next milestone is **`0.2.19 — Stability & API Freeze`**, focused on final API consistency, deprecation policy, performance/regression hardening, migration diagnostics and release-quality compatibility before `0.3.0`.
 
-The next logical milestone is **`0.2.17 — Observability Platform v3`**, focused on tracing, correlation across HTTP/jobs/workflows/events/realtime/cache, richer runtime metrics and exporter/provider integration.
+`0.3.0` is planned as the next BCP Application Platform baseline.
 
 Native desktop/mobile compilation remains later roadmap work.