@chidchanun/bcp 0.2.18 → 0.3.0

package/README.md

@@ -1,39 +1,33 @@
 # 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, deployment lifecycle, uploads, storage and standalone Node.js deployment.
+BCP Framework is a React full-stack application framework for file-based routing, SSR, server data, APIs, authentication, SQL databases, jobs, workflows, transactional events, realtime, caching, observability, plugins, deployment lifecycle and standalone Node.js production builds.
 
-> **Development target:** `0.2.18 — Deployment Platform v2`
+> **Development target:** `0.3.0 — BCP Application Platform`
 >
-> `0.2.18` remains unreleased until local validation, RC checks, tagging and npm publication complete.
+> `0.3.0` remains unreleased until local validation, RC checks, tagging and npm publication complete.
 
 ## Current platform
 
 | Area | Capability |
 | --- | --- |
-| Application | React SSR, hydration, layouts, metadata and SPA navigation |
+| Application runtime | `defineApp()` / `createApp()`, typed config, shared services, plugins/modules, resource lifecycle, readiness and diagnostics |
 | Routing | Static, dynamic, catch-all, optional catch-all and route groups |
-| Server data | Route loaders and request-scoped server APIs |
-| Mutations | Route-owned actions and `<Form>` |
-| Authentication | JWT cookie sessions, optional server-side stores, revocation, logout-all and idle timeout |
+| Rendering | React SSR, hydration, layouts, metadata and SPA navigation |
+| Server data | Route loaders, guards, actions and request-scoped server APIs |
+| Authentication | JWT cookie sessions, revocation, logout-all and idle timeout |
 | Authorization | Auth/guest/role/permission guards and resource-aware policies |
-| 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, 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 |
-| 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 |
+| Events | Transactional outbox, SQL persistence, dispatcher leases and durable handoff |
+| Realtime | Channels, presence, broker delivery, WebSocket adapter contract, SSE and heartbeat |
+| Plugins | Dependency ordering, lifecycle, config parsing, services and async hooks |
+| Cache | Redis-compatible adapters/locks, stampede protection, TTL/tag/path invalidation and metrics |
+| Observability | Prometheus metrics, health/readiness, distributed tracing, W3C context and correlation IDs |
+| Deployment | Resource lifecycle, readiness, diagnostics, runtime identity and graceful shutdown |
+| Testing | Request/route/page/auth/database/middleware/jobs/workflow/outbox/realtime/SSE harnesses |
+| Stability | API baseline snapshot, package-export parity and release-readiness gates |
+| Production | Standalone Node.js build, compiled server runtimes, dependency pruning and Docker starter |
 
 ## Requirements
 
@@ -67,149 +61,178 @@ Generated projects normally use one framework dependency:
 }
 ```
 
-## Core backend entrypoints
+## BCP Application Platform — 0.3.0
+
+`0.3.0` adds the server-only `bcp/application` composition root.
 
 ```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";
-```
+import {
+    createApp,
+} from "bcp/application";
 
-## Durable application infrastructure
+export const app =
+    createApp({
+        name: "orders-api",
+        version: "1.0.0",
+    });
+```
 
-BCP keeps durable application state separate from transient delivery:
+The runtime exposes one shared application context:
 
 ```text
-HTTP / API
-    |
-    +-- Database
-    |     +-- Transactional Outbox
-    |
-    +-- Jobs / Scheduler
-    |     +-- Workflow
-    |
-    +-- Realtime
-    |
-    +-- Cache
-    |
-    +-- Observability
-    |
-    +-- Deployment lifecycle
+app.config
+app.services
+app.hooks
+app.plugins
+app.deployment
 ```
 
-Database/outbox/jobs/workflows remain durable truth. Realtime is transient delivery. Cache is an optimization layer. Tracing correlates operations without replacing state contracts.
+Existing BCP subsystem APIs remain independent. Application Platform coordinates them; it does not replace them.
 
-## Deployment Platform v2 — 0.2.18
-
-`0.2.18` adds the server-only `bcp/deployment` entrypoint.
+### Shared services
 
 ```ts
-import {
-    createDeploymentRuntime,
-} from "bcp/deployment";
+app.provide(
+    "database",
+    database
+);
+
+app.provide(
+    "cache",
+    cache
+);
+```
 
-export const deployment =
-    createDeploymentRuntime({
-        serviceName: "orders-api",
-        version: "1.0.0",
+Existing plugins/modules use the same service registry:
+
+```ts
+const app =
+    createApp({
+        name: "orders-api",
+        modules: [
+            backendModule,
+        ],
     });
 ```
 
-Register resources in dependency order:
+### Infrastructure lifecycle
 
 ```ts
-deployment.addResource({
+app.addResource({
     name: "database",
 
-    async start() {
-        await db.connect();
+    start() {
+        return database.connect();
     },
 
-    async ready() {
-        return db.status === "ready";
+    ready() {
+        return database.ready;
     },
 
-    async stop() {
-        await db.close();
+    stop() {
+        return database.close();
     },
 });
+```
 
-deployment.addResource({
-    name: "workers",
+Startup is deterministic:
 
-    start() {
-        worker = jobs.startWorker();
-    },
+```text
+application.setup()
+        ↓
+plugin setup/start
+        ↓
+resources start
+        ↓
+application.start()
+        ↓
+ready
+```
 
-    async stop() {
-        await worker.stop();
-    },
-});
+Shutdown reverses dependencies:
 
-await deployment.start();
+```text
+application.stop()
+        ↓
+resources stop (reverse order)
+        ↓
+plugin stop/dispose
+        ↓
+application.dispose()
 ```
 
-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.
+Start failures roll back already-started resources using Deployment Platform semantics.
 
-Readiness:
+### Readiness and diagnostics
 
 ```ts
-import {
-    createDeploymentReadinessResponse,
-} from "bcp/deployment";
+const readiness =
+    await app.readiness();
 
-export function GET() {
-    return createDeploymentReadinessResponse(
-        deployment
-    );
-}
+const diagnostics =
+    await app.diagnostics();
 ```
 
-A ready runtime returns `200`; starting, draining, failed or unhealthy runtimes return `503`.
-
-Diagnostics:
+Graceful signal handling:
 
 ```ts
-import {
-    createDeploymentDiagnosticsResponse,
-} from "bcp/deployment";
+const removeSignals =
+    app.installSignalHandlers();
 ```
 
-Deployment metadata can use:
+Framework shutdown registry:
 
-```text
-BCP_DEPLOYMENT_ID
-BCP_INSTANCE_ID
-BCP_RELEASE
-NODE_ENV
-BCP_SHUTDOWN_TIMEOUT_MS
+```ts
+const unregister =
+    app.registerShutdownHook();
 ```
 
-Signal ownership is optional:
+Read more: [Application Platform](docs/application-platform.md) and [Migrating to 0.3.0](docs/migration-0.3.md).
 
-```ts
-const removeSignalHandlers =
-    deployment.installSignalHandlers();
+## Public entrypoints — 0.3.0 baseline
+
+```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/application
+bcp/server
+bcp/server-only
+bcp/middleware
 ```
 
-Default signals are `SIGTERM` and `SIGINT`. BCP sets `process.exitCode` after graceful shutdown instead of immediately terminating the process.
+Application code should use public entrypoints rather than private `packages/*` files.
 
-The runtime can also integrate with the existing framework shutdown registry:
+## Core backend composition
 
 ```ts
-const unregister =
-    deployment.registerShutdownHook();
+import { createApp } from "bcp/application";
+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 { createPluginHost } from "bcp/plugins";
+import { createTracer } from "bcp/observability";
+import { createDeploymentRuntime } from "bcp/deployment";
 ```
 
-Read more: [Deployment Platform v2](docs/deployment-platform-v2.md)
+You may use these systems independently or compose selected instances through `createApp()`.
 
 ## Compiled production entrypoints
 
@@ -228,98 +251,12 @@ bcp/testing        -> testing.mjs
 bcp/plugins        -> plugins.mjs
 bcp/observability  -> observability.mjs
 bcp/deployment     -> deployment.mjs
+bcp/application    -> application.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 {
-    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 reviewed prepared export map is recorded in `docs/api-freeze-snapshot.json` and validated by `npm run api:check`.
 
 ## CLI
 
@@ -354,36 +291,52 @@ bcp generate middleware
 bcp generate migration create_users
 ```
 
-## Packaging
+## API baseline and release readiness
 
-Build and run directly:
+`0.2.19` froze the `0.2.x` public contract. `0.3.0` intentionally establishes the next additive baseline with `bcp/application` while preserving existing entrypoints.
+
+Check the current baseline:
 
 ```bash
-npm run build
-npm start
+npm run api:check
 ```
 
-Create a standalone deployment package:
+Regenerate the snapshot only for an intentional reviewed platform-baseline change:
 
 ```bash
-bcp package
+npm run api:snapshot
 ```
 
-Application packages include production dependency manifests, deployment/environment metadata, file integrity metadata and a Docker starter while excluding `.env` secrets and application devDependencies.
+Release metadata readiness:
 
-## Documentation Platform
+```bash
+npm run release:readiness
+```
 
-Machine-readable contracts:
+Optional machine-readable report:
+
+```bash
+npm run release:readiness:report
+```
+
+Output:
+
+```text
+.bcp-framework/release-readiness.json
+```
+
+## 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.3.0`:
 
 ```bash
 npm run typecheck
@@ -391,11 +344,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
 ```
 
-`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.
 
 ## Release history
@@ -427,14 +380,14 @@ 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 |
+| `0.3.0` | BCP Application Platform |
 
 ## 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`.
+The next milestone is **`0.3.1 — Dependency Injection & Service Container`**, building typed service tokens, singleton/scoped/transient lifetimes, request scopes, factories and testing overrides on top of the Application Platform service composition model.
 
-`0.3.0` is planned as the next BCP Application Platform baseline.
+Later `0.3.x` milestones expand modules, typed APIs, SDK generation, identity/authorization, multi-tenancy, developer tooling and build/runtime targets.
 
 Native desktop/mobile compilation remains later roadmap work.