@chidchanun/bcp 0.2.17 → 0.2.19

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.19 — Stability & API Freeze`
 >
-> `0.2.17` remains unreleased until local validation, RC checks, tagging and npm publication complete.
+> `0.2.19` remains unreleased until local validation, RC checks, tagging and npm publication complete.
 
 ## Current platform
 
@@ -19,20 +19,18 @@ BCP Framework is a React full-stack framework for file-based routing, SSR, SPA n
 | Security | Same-origin validation and signed CSRF tokens |
 | Middleware | Middleware System v2 with onion execution |
 | Database | MySQL, PostgreSQL and SQLite adapters, transactions, lifecycle and migrations |
-| Background jobs | Delay, retry/backoff, cancellation and concurrent workers |
-| Scheduling | Interval/UTC cron schedules and scheduler leases |
-| Durable jobs | Redis-compatible queue/schedule adapters, visibility timeout, heartbeat, stale recovery and DLQ |
+| Jobs | Delay, retries, scheduling, Redis-compatible durable queues, heartbeat, stale recovery and DLQ |
 | Workflows | Sequential/parallel steps, retries, persisted delays, compensation and run leases |
-| Events | Transactional outbox, SQL persistence, dispatcher leases, retries, event bus and durable queue handoff |
-| 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 | Metrics, Prometheus, health/readiness, distributed tracing, W3C trace context and correlation IDs |
-| 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 |
-| Documentation | Manifest-driven docs, platform metadata and API reference |
+| Events | Transactional outbox, SQL persistence, dispatcher leases, retries and durable queue handoff |
+| Realtime | Channels/rooms, presence, broker delivery, socket adapter contract, SSE and heartbeat |
+| Testing | Request/route/page/auth/database/middleware/jobs/workflow/outbox/realtime/SSE harnesses |
+| Plugins & modules | Dependency ordering, lifecycle hooks, config parsing, shared services and async hooks |
+| Caching | Redis-compatible adapters/locks, stampede protection, TTL/tag/path invalidation and metrics |
+| Observability | Prometheus metrics, health/readiness, distributed tracing, W3C trace context and correlation IDs |
+| Deployment | Resource lifecycle, readiness, diagnostics, runtime identity, signal handling and graceful shutdown |
+| Stability | Frozen public/CLI/package contract, compatibility gate and release-readiness report |
+| Production | Standalone Node.js build, compiled server entrypoints, dependency pruning and Docker starter |
+| Documentation | Manifest-driven docs, API/platform metadata and release contracts |
 
 ## Requirements
 
@@ -66,382 +64,138 @@ Generated projects normally use one framework dependency:
 }
 ```
 
-## Core backend entrypoints
+## Public entrypoints — frozen for 0.2.19
 
-```ts
-import { createCacheStore } from "bcp/cache";
-import { db } from "bcp/database";
-import { createAuth } from "bcp/auth";
-import { createJobQueue } from "bcp/jobs";
-import { createWorkflow } from "bcp/workflow";
-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";
+```text
+bcp
+bcp/island
+bcp/cache
+bcp/config
+bcp/validation
+bcp/error
+bcp/database
+bcp/auth
+bcp/jobs
+bcp/workflow
+bcp/events
+bcp/realtime
+bcp/testing
+bcp/plugins
+bcp/observability
+bcp/deployment
+bcp/server
+bcp/server-only
+bcp/middleware
 ```
 
-## Durable jobs and scheduling
+Application code should use these public entrypoints instead of private `packages/*` implementation files.
 
-```ts
-import {
-    createJobQueue,
-    createJobScheduler,
-} from "bcp/jobs";
+## Stability & API Freeze — 0.2.19
 
-export const jobs =
-    createJobQueue();
+The committed freeze contract is:
 
-export const scheduler =
-    createJobScheduler({
-        queue: jobs,
-    });
+```text
+docs/api-freeze-snapshot.json
 ```
 
-Production adapters can provide Redis-compatible durable queue/schedule storage without BCP owning the Redis connection.
+It locks the current public entrypoint set, CLI command set, API ownership and exact prepared npm export targets.
 
-## Workflow Orchestration — 0.2.11
+Check compatibility:
 
-```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
-            );
-        }
-    );
+```bash
+npm run api:check
 ```
 
-Workflows support retries, compensation, persisted delays and optional durable queue execution.
-
-## Transactional Outbox & Events — 0.2.12
-
-Use the same SQL transaction for business data and its outbox event:
+Regenerate the snapshot only when an intentional platform-baseline change is reviewed:
 
-```ts
-await db.transaction(
-    async tx => {
-        await tx.execute(
-            "INSERT INTO orders ..."
-        );
-
-        await outbox.publish(
-            tx,
-            "order.created",
-            {
-                orderId: 42,
-            }
-        );
-    }
-);
+```bash
+npm run api:snapshot
 ```
 
-After commit, an outbox dispatcher can deliver through `bcp/jobs`, a custom publisher or the local event bus.
-
-Read more: [Transactional Outbox & Events](docs/transactional-outbox-events.md)
-
-## Realtime Platform — 0.2.13
+Release metadata readiness:
 
-```ts
-import {
-    createRealtime,
-} from "bcp/realtime";
-
-export const realtime =
-    createRealtime();
+```bash
+npm run release:readiness
 ```
 
-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)
+Persist a local machine-readable report:
 
-## Testing Platform — 0.2.14
-
-`bcp/testing` provides runner-neutral request/route/page/auth/database/middleware/jobs/workflow/outbox/realtime/SSE test helpers.
-
-```ts
-import {
-    createRouteTestHandler,
-    createTestApp,
-    expectResponse,
-} from "bcp/testing";
-
-const app =
-    createTestApp({
-        handler:
-            createRouteTestHandler({
-                GET() {
-                    return {
-                        ok: true,
-                    };
-                },
-            }),
-    });
-
-await expectResponse(
-    await app.get("/api/health")
-)
-    .status(200)
-    .json({
-        ok: true,
-    });
+```bash
+npm run release:readiness:report
 ```
 
-Read more: [Testing Platform](docs/testing-platform.md)
-
-## Plugin & Module Platform — 0.2.15
-
-```ts
-import {
-    createPluginHost,
-    definePlugin,
-} from "bcp/plugins";
-
-const databasePlugin =
-    definePlugin({
-        name: "database",
-        setup(context) {
-            context.services.provide(
-                "database",
-                db
-            );
-        },
-    });
+Output:
 
-const jobsPlugin =
-    definePlugin({
-        name: "jobs",
-        requires: [
-            "database",
-        ],
-    });
-
-export const plugins =
-    createPluginHost({
-        plugins: [
-            jobsPlugin,
-            databasePlugin,
-        ],
-    });
+```text
+.bcp-framework/release-readiness.json
 ```
 
-Startup follows dependency order; stop/dispose runs in reverse order. Modules, config parsing, shared services and async hook buses are supported.
+Read more: [Stability & API Freeze](docs/stability-api-freeze.md)
 
-Read more: [Plugin & Module Platform](docs/plugin-module-platform.md)
-
-## Cache Platform v2 — 0.2.16
-
-`0.2.16` keeps the original `cache()` / `dedupe()` APIs and adds provider-neutral asynchronous cache stores.
+## Core backend entrypoints
 
 ```ts
-import {
-    createCacheStore,
-    createRedisCacheAdapter,
-    createRedisCacheLockAdapter,
-} from "bcp/cache";
-
-export const cache =
-    createCacheStore({
-        adapter:
-            createRedisCacheAdapter({
-                client: redisClient,
-            }),
-        lock:
-            createRedisCacheLockAdapter({
-                client: redisClient,
-            }),
-    });
+import { createCacheStore } from "bcp/cache";
+import { db } from "bcp/database";
+import { createAuth } from "bcp/auth";
+import { createJobQueue } from "bcp/jobs";
+import { createWorkflow } from "bcp/workflow";
+import { createTransactionalOutbox } from "bcp/events";
+import { createRealtime } from "bcp/realtime";
+import { createTestApp } from "bcp/testing";
+import { createPluginHost } from "bcp/plugins";
+import { createTracer } from "bcp/observability";
+import { createDeploymentRuntime } from "bcp/deployment";
 ```
 
-Distributed `getOrSet()` supports local singleflight, owner-scoped lock leases, heartbeat renewal, double-check-after-lock and contention wait/poll.
-
-Read more: [Cache Platform v2](docs/cache-platform-v2.md)
-
-## Observability Platform v3 — 0.2.17
-
-`0.2.17` keeps the metrics/Prometheus/health APIs from Observability v2 and adds provider-neutral tracing and correlation.
-
-Create a tracer:
+## Deployment lifecycle
 
 ```ts
 import {
-    createMemoryTraceSpanExporter,
-    createTracer,
-} from "bcp/observability";
+    createDeploymentRuntime,
+} from "bcp/deployment";
 
-const traces =
-    createMemoryTraceSpanExporter();
-
-export const tracer =
-    createTracer({
-        exporter: traces,
-        serviceName: "api",
+const deployment =
+    createDeploymentRuntime({
+        serviceName: "orders-api",
     });
-```
 
-Create root/child spans:
+deployment.addResource({
+    name: "database",
+    start: () => db.connect(),
+    ready: () => db.status === "ready",
+    stop: () => db.close(),
+});
 
-```ts
-await tracer.withSpan(
-    "order.checkout",
-    async () => {
-        await tracer.withSpan(
-            "database.order.insert",
-            createOrder,
-            {
-                kind: "client",
-            }
-        );
-    }
-);
+await deployment.start();
 ```
 
-Tracing context flows through normal awaited async work via Node `AsyncLocalStorage`.
+Startup follows registration order. Shutdown runs in reverse order. Repeated/concurrent start while active and repeated/concurrent shutdown are covered by the `0.2.19` stability suite.
 
-### HTTP tracing
+Read more: [Deployment Platform v2](docs/deployment-platform-v2.md)
 
-```ts
-import {
-    createRequestTracingMiddleware,
-} from "bcp/observability";
-
-export const middleware =
-    createRequestTracingMiddleware(
-        tracer
-    );
-```
-
-The middleware continues valid W3C `traceparent` headers, preserves `x-correlation-id`, creates a server span and returns current trace headers on the response.
-
-### Jobs / workflow / events / realtime propagation
-
-```ts
-import {
-    createTraceCarrier,
-    runWithTraceCarrier,
-} from "bcp/observability";
-
-const trace =
-    createTraceCarrier();
-
-await jobs.enqueue(
-    "order.process",
-    {
-        orderId,
-        trace,
-    }
-);
-```
+## Compiled production entrypoints
 
-Consumer:
-
-```ts
-await runWithTraceCarrier(
-    payload.trace,
-    () =>
-        tracer.withSpan(
-            "job order.process",
-            handler,
-            {
-                kind: "consumer",
-            }
-        )
-);
-```
-
-The same carrier can be placed in workflow input, outbox/event metadata and realtime payloads when trace continuity is needed across those boundaries.
-
-### Trace-to-metrics and logs
-
-```ts
-import {
-    createCompositeTraceSpanExporter,
-    createMetricsRegistry,
-    createTraceMetricsExporter,
-    getTraceLogFields,
-} from "bcp/observability";
-
-const metrics =
-    createMetricsRegistry();
-
-const exporter =
-    createCompositeTraceSpanExporter([
-        createTraceMetricsExporter(
-            metrics
-        ),
-        productionTraceExporter,
-    ]);
-
-logger.info(
-    "order created",
-    {
-        ...getTraceLogFields(),
-        orderId,
-    }
-);
-```
-
-Default trace metrics use low-cardinality `kind` and `status` labels. Span-name labels are opt-in.
-
-BCP does not install an OpenTelemetry SDK or vendor APM package; production exporters remain application-owned through `TraceSpanExporter`.
-
-Prepared npm packages compile `bcp/observability` to `observability.mjs` for standalone Node runtime use.
-
-Read more: [Observability Platform v3](docs/observability-v3.md)
-
-## Public entrypoints
+Prepared npm packages use compiled ESM for the main server runtime surfaces:
 
 ```text
-bcp
-bcp/island
-bcp/cache
-bcp/config
-bcp/validation
-bcp/error
-bcp/database
-bcp/auth
-bcp/jobs
-bcp/workflow
-bcp/events
-bcp/realtime
-bcp/testing
-bcp/plugins
-bcp/observability
-bcp/server
-bcp/server-only
-bcp/middleware
+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
 ```
 
-Application code should use public entrypoints instead of private `packages/*` implementation files.
+The exact prepared export map is now part of the API freeze contract.
 
 ## CLI
 
@@ -476,54 +230,27 @@ 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
 
 ```bash
 npm run build
-npm start
-```
-
-Deployment package:
-
-```bash
 bcp package
 ```
 
-## Documentation Platform
+Application packages include production dependency manifests, deployment/environment metadata, file-integrity metadata and a Docker starter while excluding `.env` secrets and application devDependencies.
 
-Machine-readable contracts:
+## Machine-readable contracts
 
 ```text
 docs/platform-manifest.json
 docs/docs-web-manifest.json
 docs/api-manifest.json
+docs/api-freeze-snapshot.json
 ```
 
 ## Release validation
 
-Before publishing `0.2.17`:
+Before publishing `0.2.19`:
 
 ```bash
 npm run typecheck
@@ -531,12 +258,14 @@ npm run test:unit
 npm run test:integration
 npm run test:e2e
 npm run test:package
+npm run api:check
+npm run release:readiness
 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.
+`release:check` now runs the full tests, API compatibility gate, release-readiness gate and release metadata validation.
 
-Do not tag or publish until the exact final release commit passes the full RC sequence.
+Do not tag or publish until the exact final release commit passes the complete RC sequence.
 
 ## Release history
 
@@ -566,14 +295,14 @@ 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 |
+| `0.2.19` | Stability & API Freeze |
 
 ## Roadmap
 
-`0.2.17` establishes trace/correlation continuity across the current server platform without coupling BCP to a specific telemetry vendor.
-
-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.
+`0.2.19` freezes the supported `0.2.x` application/runtime contract and becomes the compatibility reference for the next platform generation.
 
-`0.2.19` is planned as the stabilization/API-freeze pass before the next `0.3.0` platform baseline.
+The next planned milestone is **`0.3.0 — BCP Application Platform`**. Intentional public API changes should be made there with explicit migration documentation and compatibility metadata.
 
 Native desktop/mobile compilation remains later roadmap work.