@chidchanun/bcp 0.2.17 → 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.17 — Observability Platform v3`
+> **Development target:** `0.2.18 — Deployment Platform v2`
 >
-> `0.2.17` 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 |
+| 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,345 +79,221 @@ import { createTransactionalOutbox } from "bcp/events";
 import { createRealtime } from "bcp/realtime";
 import { createTestApp } from "bcp/testing";
 import { createPluginHost } from "bcp/plugins";
-import {
-    createMetricsRegistry,
-    createTracer,
-} 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";
-
-export const jobs =
-    createJobQueue();
+BCP keeps durable application state separate from transient delivery:
 
-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";
+
+export const deployment =
+    createDeploymentRuntime({
+        serviceName: "orders-api",
+        version: "1.0.0",
+    });
 ```
 
-Workflows support retries, compensation, persisted delays and optional durable queue execution.
+Register resources in dependency order:
 
-## Transactional Outbox & Events — 0.2.12
+```ts
+deployment.addResource({
+    name: "database",
 
-Use the same SQL transaction for business data and its outbox event:
+    async start() {
+        await db.connect();
+    },
 
-```ts
-await db.transaction(
-    async tx => {
-        await tx.execute(
-            "INSERT INTO orders ..."
-        );
-
-        await outbox.publish(
-            tx,
-            "order.created",
-            {
-                orderId: 42,
-            }
-        );
-    }
-);
-```
+    async ready() {
+        return db.status === "ready";
+    },
 
-After commit, an outbox dispatcher can deliver through `bcp/jobs`, a custom publisher or the local event bus.
+    async stop() {
+        await db.close();
+    },
+});
 
-Read more: [Transactional Outbox & Events](docs/transactional-outbox-events.md)
+deployment.addResource({
+    name: "workers",
 
-## Realtime Platform — 0.2.13
+    start() {
+        worker = jobs.startWorker();
+    },
 
-```ts
-import {
-    createRealtime,
-} from "bcp/realtime";
+    async stop() {
+        await worker.stop();
+    },
+});
 
-export const realtime =
-    createRealtime();
+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)
+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.
 
-## Testing Platform — 0.2.14
-
-`bcp/testing` provides runner-neutral request/route/page/auth/database/middleware/jobs/workflow/outbox/realtime/SSE test helpers.
+Readiness:
 
 ```ts
 import {
-    createRouteTestHandler,
-    createTestApp,
-    expectResponse,
-} from "bcp/testing";
-
-const app =
-    createTestApp({
-        handler:
-            createRouteTestHandler({
-                GET() {
-                    return {
-                        ok: true,
-                    };
-                },
-            }),
-    });
+    createDeploymentReadinessResponse,
+} from "bcp/deployment";
 
-await expectResponse(
-    await app.get("/api/health")
-)
-    .status(200)
-    .json({
-        ok: true,
-    });
+export function GET() {
+    return createDeploymentReadinessResponse(
+        deployment
+    );
+}
 ```
 
-Read more: [Testing Platform](docs/testing-platform.md)
+A ready runtime returns `200`; starting, draining, failed or unhealthy runtimes return `503`.
 
-## Plugin & Module Platform — 0.2.15
+Diagnostics:
 
 ```ts
 import {
-    createPluginHost,
-    definePlugin,
-} from "bcp/plugins";
-
-const databasePlugin =
-    definePlugin({
-        name: "database",
-        setup(context) {
-            context.services.provide(
-                "database",
-                db
-            );
-        },
-    });
+    createDeploymentDiagnosticsResponse,
+} from "bcp/deployment";
+```
 
-const jobsPlugin =
-    definePlugin({
-        name: "jobs",
-        requires: [
-            "database",
-        ],
-    });
+Deployment metadata can use:
 
-export const plugins =
-    createPluginHost({
-        plugins: [
-            jobsPlugin,
-            databasePlugin,
-        ],
-    });
+```text
+BCP_DEPLOYMENT_ID
+BCP_INSTANCE_ID
+BCP_RELEASE
+NODE_ENV
+BCP_SHUTDOWN_TIMEOUT_MS
 ```
 
-Startup follows dependency order; stop/dispose runs in reverse order. Modules, config parsing, shared services and async hook buses are supported.
+Signal ownership is optional:
 
-Read more: [Plugin & Module Platform](docs/plugin-module-platform.md)
+```ts
+const removeSignalHandlers =
+    deployment.installSignalHandlers();
+```
 
-## Cache Platform v2 — 0.2.16
+Default signals are `SIGTERM` and `SIGINT`. BCP sets `process.exitCode` after graceful shutdown instead of immediately terminating the process.
 
-`0.2.16` keeps the original `cache()` / `dedupe()` APIs and adds provider-neutral asynchronous cache stores.
+The runtime can also integrate with the existing framework shutdown registry:
 
 ```ts
-import {
-    createCacheStore,
-    createRedisCacheAdapter,
-    createRedisCacheLockAdapter,
-} from "bcp/cache";
-
-export const cache =
-    createCacheStore({
-        adapter:
-            createRedisCacheAdapter({
-                client: redisClient,
-            }),
-        lock:
-            createRedisCacheLockAdapter({
-                client: redisClient,
-            }),
-    });
+const unregister =
+    deployment.registerShutdownHook();
 ```
 
-Distributed `getOrSet()` supports local singleflight, owner-scoped lock leases, heartbeat renewal, double-check-after-lock and contention wait/poll.
+Read more: [Deployment Platform v2](docs/deployment-platform-v2.md)
 
-Read more: [Cache Platform v2](docs/cache-platform-v2.md)
+## Compiled production entrypoints
 
-## Observability Platform v3 — 0.2.17
+Prepared npm packages use compiled ESM for the main server runtime surfaces:
 
-`0.2.17` keeps the metrics/Prometheus/health APIs from Observability v2 and adds provider-neutral tracing and correlation.
+```text
+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
+```
 
-Create a tracer:
+TypeScript source remains the type surface, while prepared production runtime resolution points to compiled `.mjs` files.
+
+## Observability Platform v3 — 0.2.17
 
 ```ts
 import {
-    createMemoryTraceSpanExporter,
     createTracer,
 } from "bcp/observability";
 
-const traces =
-    createMemoryTraceSpanExporter();
-
 export const tracer =
     createTracer({
-        exporter: traces,
-        serviceName: "api",
+        serviceName: "orders-api",
     });
 ```
 
-Create root/child spans:
+`bcp/observability` supports root/child spans, AsyncLocalStorage context, W3C `traceparent`, correlation IDs, request tracing, trace carriers, memory/composite exporters and trace-to-Prometheus metrics.
 
-```ts
-await tracer.withSpan(
-    "order.checkout",
-    async () => {
-        await tracer.withSpan(
-            "database.order.insert",
-            createOrder,
-            {
-                kind: "client",
-            }
-        );
-    }
-);
-```
-
-Tracing context flows through normal awaited async work via Node `AsyncLocalStorage`.
+Read more: [Observability Platform v3](docs/observability-v3.md)
 
-### HTTP tracing
+## Cache Platform v2 — 0.2.16
 
 ```ts
 import {
-    createRequestTracingMiddleware,
-} from "bcp/observability";
-
-export const middleware =
-    createRequestTracingMiddleware(
-        tracer
-    );
+    createCacheStore,
+    createRedisCacheAdapter,
+    createRedisCacheLockAdapter,
+} from "bcp/cache";
 ```
 
-The middleware continues valid W3C `traceparent` headers, preserves `x-correlation-id`, creates a server span and returns current trace headers on the response.
+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.
 
-### Jobs / workflow / events / realtime propagation
+Read more: [Cache Platform v2](docs/cache-platform-v2.md)
 
-```ts
-import {
-    createTraceCarrier,
-    runWithTraceCarrier,
-} from "bcp/observability";
+## Plugin & Module Platform — 0.2.15
 
-const trace =
-    createTraceCarrier();
+`bcp/plugins` supports dependency ordering, setup/start/stop/dispose lifecycle, modules, config parsing, shared services and async hooks.
 
-await jobs.enqueue(
-    "order.process",
-    {
-        orderId,
-        trace,
-    }
-);
-```
+Read more: [Plugin & Module Platform](docs/plugin-module-platform.md)
 
-Consumer:
+## Testing Platform — 0.2.14
 
-```ts
-await runWithTraceCarrier(
-    payload.trace,
-    () =>
-        tracer.withSpan(
-            "job order.process",
-            handler,
-            {
-                kind: "consumer",
-            }
-        )
-);
-```
+`bcp/testing` provides runner-neutral request/route/page/auth/database/middleware/jobs/workflow/outbox/realtime/SSE test helpers.
+
+Read more: [Testing Platform](docs/testing-platform.md)
 
-The same carrier can be placed in workflow input, outbox/event metadata and realtime payloads when trace continuity is needed across those boundaries.
+## Realtime Platform — 0.2.13
 
-### Trace-to-metrics and logs
+`bcp/realtime` provides channels/rooms, presence, broker delivery, provider-neutral socket adapters, SSE and heartbeat handling.
 
-```ts
-import {
-    createCompositeTraceSpanExporter,
-    createMetricsRegistry,
-    createTraceMetricsExporter,
-    getTraceLogFields,
-} from "bcp/observability";
+Read more: [Realtime Platform](docs/realtime-platform.md)
 
-const metrics =
-    createMetricsRegistry();
-
-const exporter =
-    createCompositeTraceSpanExporter([
-        createTraceMetricsExporter(
-            metrics
-        ),
-        productionTraceExporter,
-    ]);
-
-logger.info(
-    "order created",
-    {
-        ...getTraceLogFields(),
-        orderId,
-    }
-);
-```
+## Transactional Outbox & Events — 0.2.12
+
+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.
 
-Default trace metrics use low-cardinality `kind` and `status` labels. Span-name labels are opt-in.
+Read more: [Transactional Outbox & Events](docs/transactional-outbox-events.md)
 
-BCP does not install an OpenTelemetry SDK or vendor APM package; production exporters remain application-owned through `TraceSpanExporter`.
+## Workflow Orchestration — 0.2.11
 
-Prepared npm packages compile `bcp/observability` to `observability.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: [Observability Platform v3](docs/observability-v3.md)
+Read more: [Workflow Orchestration](docs/workflow-orchestration.md)
 
 ## Public entrypoints
 
@@ -436,6 +313,7 @@ bcp/realtime
 bcp/testing
 bcp/plugins
 bcp/observability
+bcp/deployment
 bcp/server
 bcp/server-only
 bcp/middleware
@@ -476,41 +354,23 @@ bcp generate middleware
 bcp generate migration create_users
 ```
 
-## Production model
-
-```text
-Browser / API / Realtime clients
-              |
-       tracing + security
-              |
-          Plugin Host
-       /      |       \
- database  workflows  realtime
-    |          |         ^
- outbox       jobs       |
-    \__________|_________/
-           durable state
-              |
-       shared cache layer
-              |
-      metrics + trace export
-```
-
-Cache remains an optimization layer. Database/outbox/jobs/workflows remain the durable truth. Realtime remains transient delivery. Tracing correlates those operations without replacing their state contracts.
-
 ## 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:
@@ -523,7 +383,7 @@ docs/api-manifest.json
 
 ## Release validation
 
-Before publishing `0.2.17`:
+Before publishing `0.2.18`:
 
 ```bash
 npm run typecheck
@@ -534,7 +394,7 @@ npm run test:package
 npm run rc:check
 ```
 
-`0.2.17` adds unit and prepared-package smoke coverage for root/child spans, async context propagation, W3C trace headers, correlation carriers, request tracing, error spans, trace metrics and compiled `observability.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.
 
@@ -566,14 +426,15 @@ Do not tag or publish until the exact final release commit passes the full RC se
 | `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.17` establishes trace/correlation continuity across the current server platform without coupling BCP to a specific telemetry vendor.
+`0.2.18` establishes a consistent production lifecycle and compiled server runtime boundary for the current BCP 0.2.x platform.
 
-The next logical milestone is **`0.2.18 — Deployment Platform v2`**, focused on completing compiled production entrypoints, deployment/runtime adapters, process lifecycle integration, container/runtime metadata and production diagnostics.
+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`.
 
-`0.2.19` is planned as the stabilization/API-freeze pass before the next `0.3.0` platform baseline.
+`0.3.0` is planned as the next BCP Application Platform baseline.
 
 Native desktop/mobile compilation remains later roadmap work.