@chidchanun/bcp 0.2.18 → 0.2.19

package/README.md

@@ -2,9 +2,9 @@
 
 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.18 — Deployment Platform v2`
+> **Development target:** `0.2.19 — Stability & API Freeze`
 >
-> `0.2.18` 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,21 +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 | 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 |
+| 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 |
-| Uploads & storage | Multipart streaming, Local/S3-compatible storage and signed URLs |
-| Configuration | Typed config/environment validation and diagnostics |
-| Production | Standalone Node.js build, compiled server entrypoints, packaging, dependency pruning and Docker starter |
-| Documentation | Manifest-driven docs, platform metadata and API reference |
+| 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
 
@@ -67,147 +64,113 @@ 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 { createTracer } from "bcp/observability";
-import { createDeploymentRuntime } from "bcp/deployment";
+```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 application infrastructure
+Application code should use these public entrypoints instead of private `packages/*` implementation files.
 
-BCP keeps durable application state separate from transient delivery:
+## Stability & API Freeze — 0.2.19
+
+The committed freeze contract is:
 
 ```text
-HTTP / API
-    |
-    +-- Database
-    |     +-- Transactional Outbox
-    |
-    +-- Jobs / Scheduler
-    |     +-- Workflow
-    |
-    +-- Realtime
-    |
-    +-- Cache
-    |
-    +-- Observability
-    |
-    +-- Deployment lifecycle
+docs/api-freeze-snapshot.json
 ```
 
-Database/outbox/jobs/workflows remain durable truth. Realtime is transient delivery. Cache is an optimization layer. Tracing correlates operations without replacing state contracts.
-
-## Deployment Platform v2 — 0.2.18
+It locks the current public entrypoint set, CLI command set, API ownership and exact prepared npm export targets.
 
-`0.2.18` adds the server-only `bcp/deployment` entrypoint.
-
-```ts
-import {
-    createDeploymentRuntime,
-} from "bcp/deployment";
+Check compatibility:
 
-export const deployment =
-    createDeploymentRuntime({
-        serviceName: "orders-api",
-        version: "1.0.0",
-    });
+```bash
+npm run api:check
 ```
 
-Register resources in dependency order:
+Regenerate the snapshot only when an intentional platform-baseline change is reviewed:
 
-```ts
-deployment.addResource({
-    name: "database",
-
-    async start() {
-        await db.connect();
-    },
+```bash
+npm run api:snapshot
+```
 
-    async ready() {
-        return db.status === "ready";
-    },
+Release metadata readiness:
 
-    async stop() {
-        await db.close();
-    },
-});
+```bash
+npm run release:readiness
+```
 
-deployment.addResource({
-    name: "workers",
+Persist a local machine-readable report:
 
-    start() {
-        worker = jobs.startWorker();
-    },
+```bash
+npm run release:readiness:report
+```
 
-    async stop() {
-        await worker.stop();
-    },
-});
+Output:
 
-await deployment.start();
+```text
+.bcp-framework/release-readiness.json
 ```
 
-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.
+Read more: [Stability & API Freeze](docs/stability-api-freeze.md)
 
-Readiness:
+## Core backend entrypoints
 
 ```ts
-import {
-    createDeploymentReadinessResponse,
-} from "bcp/deployment";
-
-export function GET() {
-    return createDeploymentReadinessResponse(
-        deployment
-    );
-}
+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";
 ```
 
-A ready runtime returns `200`; starting, draining, failed or unhealthy runtimes return `503`.
-
-Diagnostics:
+## Deployment lifecycle
 
 ```ts
 import {
-    createDeploymentDiagnosticsResponse,
+    createDeploymentRuntime,
 } from "bcp/deployment";
-```
 
-Deployment metadata can use:
-
-```text
-BCP_DEPLOYMENT_ID
-BCP_INSTANCE_ID
-BCP_RELEASE
-NODE_ENV
-BCP_SHUTDOWN_TIMEOUT_MS
-```
+const deployment =
+    createDeploymentRuntime({
+        serviceName: "orders-api",
+    });
 
-Signal ownership is optional:
+deployment.addResource({
+    name: "database",
+    start: () => db.connect(),
+    ready: () => db.status === "ready",
+    stop: () => db.close(),
+});
 
-```ts
-const removeSignalHandlers =
-    deployment.installSignalHandlers();
+await deployment.start();
 ```
 
-Default signals are `SIGTERM` and `SIGINT`. BCP sets `process.exitCode` after graceful shutdown instead of immediately terminating the process.
-
-The runtime can also integrate with the existing framework shutdown registry:
-
-```ts
-const unregister =
-    deployment.registerShutdownHook();
-```
+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.
 
 Read more: [Deployment Platform v2](docs/deployment-platform-v2.md)
 
@@ -232,94 +195,7 @@ 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 {
-    createTracer,
-} from "bcp/observability";
-
-export const tracer =
-    createTracer({
-        serviceName: "orders-api",
-    });
-```
-
-`bcp/observability` supports root/child spans, AsyncLocalStorage context, W3C `traceparent`, correlation IDs, request tracing, trace carriers, memory/composite exporters and trace-to-Prometheus metrics.
-
-Read more: [Observability Platform v3](docs/observability-v3.md)
-
-## Cache Platform v2 — 0.2.16
-
-```ts
-import {
-    createCacheStore,
-    createRedisCacheAdapter,
-    createRedisCacheLockAdapter,
-} from "bcp/cache";
-```
-
-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.
-
-Read more: [Cache Platform v2](docs/cache-platform-v2.md)
-
-## Plugin & Module Platform — 0.2.15
-
-`bcp/plugins` supports dependency ordering, setup/start/stop/dispose lifecycle, modules, config parsing, shared services and async hooks.
-
-Read more: [Plugin & Module Platform](docs/plugin-module-platform.md)
-
-## Testing Platform — 0.2.14
-
-`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)
-
-## Realtime Platform — 0.2.13
-
-`bcp/realtime` provides channels/rooms, presence, broker delivery, provider-neutral socket adapters, SSE and heartbeat handling.
-
-Read more: [Realtime Platform](docs/realtime-platform.md)
-
-## 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.
-
-Read more: [Transactional Outbox & Events](docs/transactional-outbox-events.md)
-
-## Workflow Orchestration — 0.2.11
-
-`bcp/workflow` supports sequential/parallel steps, retries, persisted delays, run leases, compensation and optional durable queue execution.
-
-Read more: [Workflow Orchestration](docs/workflow-orchestration.md)
-
-## Public entrypoints
-
-```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
-```
-
-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
 
@@ -356,34 +232,25 @@ bcp generate migration create_users
 
 ## Packaging
 
-Build and run directly:
-
 ```bash
 npm run build
-npm start
-```
-
-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.
+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:
+## 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.18`:
+Before publishing `0.2.19`:
 
 ```bash
 npm run typecheck
@@ -391,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.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.
+`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
 
@@ -427,14 +296,13 @@ Do not tag or publish until the exact final release commit passes the full RC se
 | `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.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`.
+`0.2.19` freezes the supported `0.2.x` application/runtime contract and becomes the compatibility reference for the next platform generation.
 
-`0.3.0` is planned as the next BCP Application 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.
 

package/docs/README.md

@@ -2,7 +2,7 @@
 
 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.18 — Deployment Platform v2`
+> **Documentation target:** BCP Framework `0.2.19 — Stability & API Freeze`
 >
 > **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
 
@@ -17,6 +17,9 @@ docs/platform-manifest.json
 
 docs/api-manifest.json
   -> public package entrypoints, source ownership and guide mapping
+
+docs/api-freeze-snapshot.json
+  -> frozen public/CLI/prepared-package compatibility contract
 ```
 
 Framework source and tests remain authoritative for runtime behavior.
@@ -44,56 +47,41 @@ Framework source and tests remain authoritative for runtime behavior.
 | `0.2.16` | Cache Platform v2 |
 | `0.2.17` | Observability Platform v3 |
 | `0.2.18` | Deployment Platform v2 |
+| `0.2.19` | Stability & API Freeze |
 
-## 0.2.18 — Deployment Platform v2
+## 0.2.19 — Stability & API Freeze
 
-`0.2.18` adds the server-only `bcp/deployment` entrypoint and completes compiled production runtime coverage for key server package surfaces.
+`0.2.19` freezes the supported `0.2.x` public package and CLI contract without adding a new application subsystem.
 
-Primary APIs:
+Primary stability commands:
 
-```ts
-import {
-    createDeploymentDiagnosticsResponse,
-    createDeploymentReadinessResponse,
-    createDeploymentRuntime,
-} from "bcp/deployment";
+```bash
+npm run api:check
+npm run api:snapshot
+npm run release:readiness
+npm run release:readiness:report
 ```
 
-Runtime model:
+The freeze snapshot captures:
 
-```text
-process start
-    |
-    v
-DeploymentRuntime
-    |
-    +-- resource start order
-    +-- readiness checks
-    +-- diagnostics
-    +-- deployment metadata
-    +-- SIGTERM / SIGINT
-    |
-    v
-state = ready
-    |
-shutdown/drain
-    |
-    v
-reverse-order resource stop
-```
+- public `bcp/*` entrypoints;
+- CLI command names;
+- prepared npm export targets;
+- browser poison boundaries;
+- API source/environment ownership;
+- compatibility with `0.2.18`.
 
-Prepared npm runtime targets now include compiled ESM for `bcp/config`, `bcp/auth`, `bcp/deployment`, `bcp/server` and `bcp/middleware` in addition to the server entrypoints compiled in earlier releases.
+`npm run api:check` prepares the exact npm staging package and rejects drift from the committed snapshot.
 
 New/updated sources:
 
 | Source | Purpose |
 | --- | --- |
-| `deployment-platform-v2.md` | Runtime lifecycle, readiness, diagnostics, metadata and graceful shutdown |
-| `api-reference.md` | `bcp/deployment` APIs |
-| `platform-manifest.json` | Deployment/compiled-runtime capability flags |
-| `api-manifest.json` | `bcp/deployment` source/guide ownership |
-| `docs-web-manifest.json` | Deployment v2 navigation and `0.2.18` release route |
-| `releases/0.2.18.md` | Deployment Platform v2 release notes |
+| `stability-api-freeze.md` | Freeze policy, compatibility checks and release readiness |
+| `api-freeze-snapshot.json` | Frozen public/CLI/package contract |
+| `platform-manifest.json` | Stability capability flags and `0.2.18` compatibility baseline |
+| `docs-web-manifest.json` | Stability guide and `0.2.19` release route |
+| `releases/0.2.19.md` | Stability & API Freeze release notes |
 
 ## Update rule
 
@@ -105,13 +93,15 @@ When framework behavior or public surface changes:
 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.
+7. Review `api-freeze-snapshot.json`; do not regenerate it casually during `0.2.19`.
+8. Update `docs/releases/<version>.md`.
+9. Change release state only after the release workflow reaches that state.
 
 ## Important docs-web routes
 
 | Website route | Markdown source |
 | --- | --- |
+| `/docs/stability-api-freeze` | `stability-api-freeze.md` |
 | `/docs/observability-v3` | `observability-v3.md` |
 | `/docs/deployment-platform-v2` | `deployment-platform-v2.md` |
 | `/docs/durable-jobs` | `durable-jobs.md` |
@@ -122,7 +112,7 @@ When framework behavior or public surface changes:
 | `/docs/plugin-module-platform` | `plugin-module-platform.md` |
 | `/docs/cache-platform-v2` | `cache-platform-v2.md` |
 | `/docs/api-reference` | `api-reference.md` |
-| `/releases/0.2.18` | `releases/0.2.18.md` |
+| `/releases/0.2.19` | `releases/0.2.19.md` |
 
 Every route/source pair is validated by unit tests.
 
@@ -150,11 +140,11 @@ bcp/server-only
 bcp/middleware
 ```
 
-The API-manifest entrypoint set must match the platform public-entrypoint set exactly.
+The API-manifest entrypoint set, platform public-entrypoint set and freeze snapshot must remain aligned.
 
 ## Release validation
 
-Before publishing `0.2.18`:
+Before publishing `0.2.19`:
 
 ```bash
 npm run typecheck
@@ -162,9 +152,11 @@ 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
 ```
 
-Deployment Platform v2 validation covers resource lifecycle ordering, startup rollback, readiness/diagnostics, runtime metadata, server-only boundaries, compiled production entrypoints and docs/platform/API parity.
+Stability validation covers public/CLI/export parity, prepared-package browser/runtime boundaries, release metadata and deployment lifecycle idempotency in addition to all existing subsystem suites.
 
 The final release tag must point to the exact commit that passed the complete RC sequence.