@chidchanun/bcp 0.2.19 → 0.3.0

package/README.md

@@ -1,36 +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.19 — Stability & API Freeze`
+> **Development target:** `0.3.0 — BCP Application Platform`
 >
-> `0.2.19` 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 |
-| Jobs | Delay, retries, scheduling, Redis-compatible durable queues, 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 and durable queue handoff |
-| Realtime | Channels/rooms, presence, broker delivery, socket adapter contract, SSE and heartbeat |
+| 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 |
-| 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 |
+| 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
 
@@ -64,77 +61,165 @@ Generated projects normally use one framework dependency:
 }
 ```
 
-## Public entrypoints — frozen for 0.2.19
+## BCP Application Platform — 0.3.0
+
+`0.3.0` adds the server-only `bcp/application` composition root.
+
+```ts
+import {
+    createApp,
+} from "bcp/application";
+
+export const app =
+    createApp({
+        name: "orders-api",
+        version: "1.0.0",
+    });
+```
+
+The runtime exposes one shared application context:
 
 ```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
+app.config
+app.services
+app.hooks
+app.plugins
+app.deployment
 ```
 
-Application code should use these public entrypoints instead of private `packages/*` implementation files.
+Existing BCP subsystem APIs remain independent. Application Platform coordinates them; it does not replace them.
 
-## Stability & API Freeze — 0.2.19
+### Shared services
 
-The committed freeze contract is:
+```ts
+app.provide(
+    "database",
+    database
+);
+
+app.provide(
+    "cache",
+    cache
+);
+```
 
-```text
-docs/api-freeze-snapshot.json
+Existing plugins/modules use the same service registry:
+
+```ts
+const app =
+    createApp({
+        name: "orders-api",
+        modules: [
+            backendModule,
+        ],
+    });
 ```
 
-It locks the current public entrypoint set, CLI command set, API ownership and exact prepared npm export targets.
+### Infrastructure lifecycle
+
+```ts
+app.addResource({
+    name: "database",
 
-Check compatibility:
+    start() {
+        return database.connect();
+    },
 
-```bash
-npm run api:check
+    ready() {
+        return database.ready;
+    },
+
+    stop() {
+        return database.close();
+    },
+});
 ```
 
-Regenerate the snapshot only when an intentional platform-baseline change is reviewed:
+Startup is deterministic:
 
-```bash
-npm run api:snapshot
+```text
+application.setup()
+        ↓
+plugin setup/start
+        ↓
+resources start
+        ↓
+application.start()
+        ↓
+ready
 ```
 
-Release metadata readiness:
+Shutdown reverses dependencies:
 
-```bash
-npm run release:readiness
+```text
+application.stop()
+        ↓
+resources stop (reverse order)
+        ↓
+plugin stop/dispose
+        ↓
+application.dispose()
 ```
 
-Persist a local machine-readable report:
+Start failures roll back already-started resources using Deployment Platform semantics.
 
-```bash
-npm run release:readiness:report
+### Readiness and diagnostics
+
+```ts
+const readiness =
+    await app.readiness();
+
+const diagnostics =
+    await app.diagnostics();
 ```
 
-Output:
+Graceful signal handling:
+
+```ts
+const removeSignals =
+    app.installSignalHandlers();
+```
+
+Framework shutdown registry:
+
+```ts
+const unregister =
+    app.registerShutdownHook();
+```
+
+Read more: [Application Platform](docs/application-platform.md) and [Migrating to 0.3.0](docs/migration-0.3.md).
+
+## Public entrypoints — 0.3.0 baseline
 
 ```text
-.bcp-framework/release-readiness.json
+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
 ```
 
-Read more: [Stability & API Freeze](docs/stability-api-freeze.md)
+Application code should use public entrypoints rather than private `packages/*` files.
 
-## Core backend entrypoints
+## Core backend composition
 
 ```ts
+import { createApp } from "bcp/application";
 import { createCacheStore } from "bcp/cache";
 import { db } from "bcp/database";
 import { createAuth } from "bcp/auth";
@@ -142,37 +227,12 @@ 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";
 ```
 
-## Deployment lifecycle
-
-```ts
-import {
-    createDeploymentRuntime,
-} from "bcp/deployment";
-
-const deployment =
-    createDeploymentRuntime({
-        serviceName: "orders-api",
-    });
-
-deployment.addResource({
-    name: "database",
-    start: () => db.connect(),
-    ready: () => db.status === "ready",
-    stop: () => db.close(),
-});
-
-await deployment.start();
-```
-
-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)
+You may use these systems independently or compose selected instances through `createApp()`.
 
 ## Compiled production entrypoints
 
@@ -191,11 +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
 ```
 
-The exact prepared export map is now part of the API freeze contract.
+The reviewed prepared export map is recorded in `docs/api-freeze-snapshot.json` and validated by `npm run api:check`.
 
 ## CLI
 
@@ -230,14 +291,39 @@ bcp generate middleware
 bcp generate migration create_users
 ```
 
-## Packaging
+## API baseline and release readiness
+
+`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
-bcp package
+npm run api:check
+```
+
+Regenerate the snapshot only for an intentional reviewed platform-baseline change:
+
+```bash
+npm run api:snapshot
+```
+
+Release metadata readiness:
+
+```bash
+npm run release:readiness
 ```
 
-Application packages include production dependency manifests, deployment/environment metadata, file-integrity metadata and a Docker starter while excluding `.env` secrets and application devDependencies.
+Optional machine-readable report:
+
+```bash
+npm run release:readiness:report
+```
+
+Output:
+
+```text
+.bcp-framework/release-readiness.json
+```
 
 ## Machine-readable contracts
 
@@ -250,7 +336,7 @@ docs/api-freeze-snapshot.json
 
 ## Release validation
 
-Before publishing `0.2.19`:
+Before publishing `0.3.0`:
 
 ```bash
 npm run typecheck
@@ -263,9 +349,7 @@ npm run release:readiness
 npm run rc:check
 ```
 
-`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 complete RC sequence.
+Do not tag or publish until the exact final release commit passes the full RC sequence.
 
 ## Release history
 
@@ -297,12 +381,13 @@ Do not tag or publish until the exact final release commit passes the complete R
 | `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.19` freezes the supported `0.2.x` application/runtime contract and becomes the compatibility reference for the next platform generation.
+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.
 
-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.
+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.
 

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.19 — Stability & API Freeze`
+> **Documentation target:** BCP Framework `0.3.0 — BCP Application Platform`
 >
 > **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
 
@@ -19,12 +19,12 @@ docs/api-manifest.json
   -> public package entrypoints, source ownership and guide mapping
 
 docs/api-freeze-snapshot.json
-  -> frozen public/CLI/prepared-package compatibility contract
+  -> reviewed public/CLI/prepared-package API baseline
 ```
 
 Framework source and tests remain authoritative for runtime behavior.
 
-## Current 0.2.x milestones
+## Current platform milestones
 
 | Version | Milestone |
 | --- | --- |
@@ -48,40 +48,84 @@ Framework source and tests remain authoritative for runtime behavior.
 | `0.2.17` | Observability Platform v3 |
 | `0.2.18` | Deployment Platform v2 |
 | `0.2.19` | Stability & API Freeze |
+| `0.3.0` | BCP Application Platform |
 
-## 0.2.19 — Stability & API Freeze
+## 0.3.0 — BCP Application Platform
 
-`0.2.19` freezes the supported `0.2.x` public package and CLI contract without adding a new application subsystem.
+`0.3.0` adds one server-only public composition root:
 
-Primary stability commands:
+```text
+bcp/application
+```
+
+Primary APIs:
+
+```ts
+import {
+    createApp,
+    defineApp,
+} from "bcp/application";
+```
+
+The application runtime composes existing Plugin and Deployment platforms instead of duplicating them. It provides:
+
+- typed application config parsing;
+- a shared service registry and hook bus;
+- existing plugin/module composition;
+- application-owned deployment resources;
+- deterministic startup/shutdown ordering;
+- startup rollback;
+- readiness and diagnostics;
+- signal/shutdown-hook integration;
+- compiled `application.mjs` production runtime.
+
+Lifecycle:
+
+```text
+application.setup
+    ↓
+plugins
+    ↓
+resources
+    ↓
+application.start
+    ↓
+ready
+
+shutdown:
+application.stop
+    ↓
+resources (reverse)
+    ↓
+plugins
+    ↓
+application.dispose
+```
+
+Read [Application Platform](application-platform.md) and [Migrating to 0.3.0](migration-0.3.md).
+
+## API baseline
+
+`0.2.19` froze the final `0.2.x` public contract. `0.3.0` establishes the next reviewed baseline by adding `bcp/application` without intentionally removing existing `0.2.19` entrypoints.
+
+Validate the current baseline:
 
 ```bash
 npm run api:check
-npm run api:snapshot
-npm run release:readiness
-npm run release:readiness:report
 ```
 
-The freeze snapshot captures:
+Regenerate only when an intentional platform-baseline change is being reviewed:
 
-- public `bcp/*` entrypoints;
-- CLI command names;
-- prepared npm export targets;
-- browser poison boundaries;
-- API source/environment ownership;
-- compatibility with `0.2.18`.
-
-`npm run api:check` prepares the exact npm staging package and rejects drift from the committed snapshot.
+```bash
+npm run api:snapshot
+```
 
-New/updated sources:
+Release metadata readiness:
 
-| Source | Purpose |
-| --- | --- |
-| `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 |
+```bash
+npm run release:readiness
+npm run release:readiness:report
+```
 
 ## Update rule
 
@@ -93,7 +137,7 @@ 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. Review `api-freeze-snapshot.json`; do not regenerate it casually during `0.2.19`.
+7. Review the API baseline snapshot when public/package contracts change.
 8. Update `docs/releases/<version>.md`.
 9. Change release state only after the release workflow reaches that state.
 
@@ -101,6 +145,8 @@ When framework behavior or public surface changes:
 
 | Website route | Markdown source |
 | --- | --- |
+| `/docs/application-platform` | `application-platform.md` |
+| `/docs/migration-0.3` | `migration-0.3.md` |
 | `/docs/stability-api-freeze` | `stability-api-freeze.md` |
 | `/docs/observability-v3` | `observability-v3.md` |
 | `/docs/deployment-platform-v2` | `deployment-platform-v2.md` |
@@ -112,7 +158,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.19` | `releases/0.2.19.md` |
+| `/releases/0.3.0` | `releases/0.3.0.md` |
 
 Every route/source pair is validated by unit tests.
 
@@ -135,16 +181,17 @@ bcp/testing
 bcp/plugins
 bcp/observability
 bcp/deployment
+bcp/application
 bcp/server
 bcp/server-only
 bcp/middleware
 ```
 
-The API-manifest entrypoint set, platform public-entrypoint set and freeze snapshot must remain aligned.
+The API manifest, platform manifest and reviewed API baseline must remain aligned.
 
 ## Release validation
 
-Before publishing `0.2.19`:
+Before publishing `0.3.0`:
 
 ```bash
 npm run typecheck
@@ -157,6 +204,4 @@ npm run release:readiness
 npm run rc:check
 ```
 
-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.