@chidchanun/bcp 0.2.18 → 0.3.0

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.3.0 — BCP Application Platform`
 >
 > **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
 
@@ -17,11 +17,14 @@ docs/platform-manifest.json
 
 docs/api-manifest.json
   -> public package entrypoints, source ownership and guide mapping
+
+docs/api-freeze-snapshot.json
+  -> 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 |
 | --- | --- |
@@ -44,56 +47,85 @@ 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.3.0` | BCP Application Platform |
 
-## 0.2.18 — Deployment Platform v2
+## 0.3.0 — BCP Application Platform
 
-`0.2.18` adds the server-only `bcp/deployment` entrypoint and completes compiled production runtime coverage for key server package surfaces.
+`0.3.0` adds one server-only public composition root:
+
+```text
+bcp/application
+```
 
 Primary APIs:
 
 ```ts
 import {
-    createDeploymentDiagnosticsResponse,
-    createDeploymentReadinessResponse,
-    createDeploymentRuntime,
-} from "bcp/deployment";
+    createApp,
+    defineApp,
+} from "bcp/application";
 ```
 
-Runtime model:
+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
-process start
-    |
-    v
-DeploymentRuntime
-    |
-    +-- resource start order
-    +-- readiness checks
-    +-- diagnostics
-    +-- deployment metadata
-    +-- SIGTERM / SIGINT
-    |
-    v
-state = ready
-    |
-shutdown/drain
-    |
-    v
-reverse-order resource stop
+application.setup
+    ↓
+plugins
+    ↓
+resources
+    ↓
+application.start
+    ↓
+ready
+
+shutdown:
+application.stop
+    ↓
+resources (reverse)
+    ↓
+plugins
+    ↓
+application.dispose
 ```
 
-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.
+Read [Application Platform](application-platform.md) and [Migrating to 0.3.0](migration-0.3.md).
 
-New/updated sources:
+## API baseline
 
-| 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 |
+`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
+```
+
+Regenerate only when an intentional platform-baseline change is being reviewed:
+
+```bash
+npm run api:snapshot
+```
+
+Release metadata readiness:
+
+```bash
+npm run release:readiness
+npm run release:readiness:report
+```
 
 ## Update rule
 
@@ -105,13 +137,17 @@ 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 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.
 
 ## Important docs-web routes
 
 | 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` |
 | `/docs/durable-jobs` | `durable-jobs.md` |
@@ -122,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.18` | `releases/0.2.18.md` |
+| `/releases/0.3.0` | `releases/0.3.0.md` |
 
 Every route/source pair is validated by unit tests.
 
@@ -145,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 must match the platform public-entrypoint set exactly.
+The API manifest, platform manifest and reviewed API baseline must remain aligned.
 
 ## Release validation
 
-Before publishing `0.2.18`:
+Before publishing `0.3.0`:
 
 ```bash
 npm run typecheck
@@ -162,9 +199,9 @@ 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.
-
 The final release tag must point to the exact commit that passed the complete RC sequence.

package/docs/api-freeze-snapshot.json

@@ -0,0 +1,243 @@
+{
+  "schemaVersion": 1,
+  "framework": "bcp",
+  "version": "0.3.0",
+  "baselineVersion": "0.2.19",
+  "state": "frozen",
+  "intentionalBreakingChanges": false,
+  "publicEntrypoints": [
+    "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"
+  ],
+  "cliCommands": [
+    "dev",
+    "build",
+    "package",
+    "start",
+    "routes",
+    "update",
+    "db",
+    "generate",
+    "config",
+    "doctor",
+    "inspect",
+    "help",
+    "version"
+  ],
+  "packageExports": {
+    ".": {
+      "default": "./packages/client/src/index.tsx",
+      "types": "./packages/client/src/index.tsx"
+    },
+    "./application": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/application.mjs",
+      "types": "./packages/client/src/application.ts"
+    },
+    "./auth": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/auth.mjs",
+      "types": "./packages/client/src/auth.ts"
+    },
+    "./cache": {
+      "default": "./packages/client/src/cache.mjs",
+      "types": "./packages/client/src/cache.ts"
+    },
+    "./config": {
+      "default": "./packages/client/src/config.mjs",
+      "types": "./packages/client/src/config.ts"
+    },
+    "./database": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/database.mjs",
+      "types": "./packages/client/src/database.ts"
+    },
+    "./deployment": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/deployment.mjs",
+      "types": "./packages/client/src/deployment.ts"
+    },
+    "./error": {
+      "default": "./packages/client/src/http-error.ts",
+      "types": "./packages/client/src/http-error.ts"
+    },
+    "./events": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/events.mjs",
+      "types": "./packages/client/src/events.ts"
+    },
+    "./island": {
+      "default": "./packages/client/src/islands.tsx",
+      "types": "./packages/client/src/islands.tsx"
+    },
+    "./jobs": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/jobs.mjs",
+      "types": "./packages/client/src/jobs.ts"
+    },
+    "./middleware": {
+      "default": "./packages/server/src/middleware.mjs",
+      "types": "./packages/server/src/middleware.ts"
+    },
+    "./observability": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/observability.mjs",
+      "types": "./packages/client/src/observability.ts"
+    },
+    "./package.json": "./package.json",
+    "./plugins": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/plugins.mjs",
+      "types": "./packages/client/src/plugins.ts"
+    },
+    "./realtime": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/realtime.mjs",
+      "types": "./packages/client/src/realtime.ts"
+    },
+    "./server": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/server.mjs",
+      "types": "./packages/client/src/server.ts"
+    },
+    "./server-only": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/server-only.mjs",
+      "types": "./packages/client/src/server-only.d.ts"
+    },
+    "./testing": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/testing.mjs",
+      "types": "./packages/client/src/testing.ts"
+    },
+    "./validation": {
+      "default": "./packages/client/src/validation.ts",
+      "types": "./packages/client/src/validation.ts"
+    },
+    "./workflow": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/workflow.mjs",
+      "types": "./packages/client/src/workflow.ts"
+    }
+  },
+  "apiOwnership": [
+    {
+      "package": "bcp",
+      "source": "packages/client/src/index.tsx",
+      "environment": "universal"
+    },
+    {
+      "package": "bcp/island",
+      "source": "packages/client/src/islands.tsx",
+      "environment": "universal"
+    },
+    {
+      "package": "bcp/cache",
+      "source": "packages/client/src/cache.ts",
+      "environment": "server-preferred"
+    },
+    {
+      "package": "bcp/config",
+      "source": "packages/client/src/config.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/validation",
+      "source": "packages/client/src/validation.ts",
+      "environment": "universal"
+    },
+    {
+      "package": "bcp/error",
+      "source": "packages/client/src/http-error.ts",
+      "environment": "universal"
+    },
+    {
+      "package": "bcp/database",
+      "source": "packages/client/src/database.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/auth",
+      "source": "packages/client/src/auth.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/jobs",
+      "source": "packages/client/src/jobs.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/workflow",
+      "source": "packages/client/src/workflow.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/events",
+      "source": "packages/client/src/events.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/realtime",
+      "source": "packages/client/src/realtime.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/testing",
+      "source": "packages/client/src/testing.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/plugins",
+      "source": "packages/client/src/plugins.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/observability",
+      "source": "packages/client/src/observability.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/deployment",
+      "source": "packages/client/src/deployment.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/application",
+      "source": "packages/client/src/application.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/server",
+      "source": "packages/client/src/server.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/server-only",
+      "source": "packages/client/src/server-only.mjs",
+      "environment": "server-marker"
+    },
+    {
+      "package": "bcp/middleware",
+      "source": "packages/server/src/middleware.ts",
+      "environment": "server"
+    }
+  ]
+}

package/docs/api-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.18",
+  "version": "0.3.0",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [
@@ -27,7 +27,7 @@
       "environment": "server-preferred",
       "route": "/docs/api-reference#bcp-cache",
       "summary": "Backward-compatible request/data caching plus Cache Platform v2 adapters, Redis-compatible distributed cache and locks, stampede protection, TTL/tag/path invalidation and metrics integration.",
-      "guides": ["/docs/caching", "/docs/cache-platform-v2", "/docs/observability-v3"]
+      "guides": ["/docs/caching", "/docs/cache-platform-v2", "/docs/observability-v3", "/docs/application-platform"]
     },
     {
       "package": "bcp/config",
@@ -35,7 +35,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-config",
       "summary": "Typed BCP configuration, environment-schema validation and configuration diagnostics APIs with a compiled production runtime.",
-      "guides": ["/docs/configuration", "/docs/environment-validation", "/docs/deployment-platform-v2"]
+      "guides": ["/docs/configuration", "/docs/environment-validation", "/docs/deployment-platform-v2", "/docs/application-platform"]
     },
     {
       "package": "bcp/validation",
@@ -59,7 +59,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-database",
       "summary": "Provider-neutral MySQL, PostgreSQL and SQLite query, transaction, lifecycle and migration primitives.",
-      "guides": ["/docs/database", "/docs/database-migrations", "/docs/transactional-outbox-events", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2"]
+      "guides": ["/docs/database", "/docs/database-migrations", "/docs/transactional-outbox-events", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2", "/docs/application-platform"]
     },
     {
       "package": "bcp/auth",
@@ -67,7 +67,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-auth",
       "summary": "Authentication Platform v2 plus permission checks, authorization policies and auth/guest/role/permission route guards, published with a compiled Node runtime.",
-      "guides": ["/docs/authentication", "/docs/auth-session-store", "/docs/auth-route-guards", "/docs/authorization-security", "/docs/session-auth", "/docs/testing-platform", "/docs/deployment-platform-v2"]
+      "guides": ["/docs/authentication", "/docs/auth-session-store", "/docs/auth-route-guards", "/docs/authorization-security", "/docs/session-auth", "/docs/testing-platform", "/docs/deployment-platform-v2", "/docs/application-platform"]
     },
     {
       "package": "bcp/jobs",
@@ -75,7 +75,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-jobs",
       "summary": "Background queues and schedules with visibility leases, heartbeats, stale recovery, DLQ maintenance and Redis-compatible durable adapters.",
-      "guides": ["/docs/background-jobs", "/docs/job-scheduling", "/docs/durable-jobs", "/docs/transactional-outbox-events", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2"]
+      "guides": ["/docs/background-jobs", "/docs/job-scheduling", "/docs/durable-jobs", "/docs/transactional-outbox-events", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2", "/docs/application-platform"]
     },
     {
       "package": "bcp/workflow",
@@ -83,7 +83,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-workflow",
       "summary": "Persistent workflow orchestration with sequential and parallel steps, retries, delays, compensation, run leases and optional durable queue execution.",
-      "guides": ["/docs/workflow-orchestration", "/docs/durable-jobs", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2"]
+      "guides": ["/docs/workflow-orchestration", "/docs/durable-jobs", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2", "/docs/application-platform"]
     },
     {
       "package": "bcp/events",
@@ -91,7 +91,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-events",
       "summary": "Transactional outbox and event delivery APIs with SQL persistence, dispatcher leases, retries, stale recovery, queue handoff and in-process event bus delivery.",
-      "guides": ["/docs/transactional-outbox-events", "/docs/database", "/docs/durable-jobs", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2"]
+      "guides": ["/docs/transactional-outbox-events", "/docs/database", "/docs/durable-jobs", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2", "/docs/application-platform"]
     },
     {
       "package": "bcp/realtime",
@@ -99,7 +99,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-realtime",
       "summary": "Realtime channels, cross-hub broker delivery, presence, channel authorization, WebSocket adapter integration, heartbeat handling and built-in Server-Sent Events responses.",
-      "guides": ["/docs/realtime-platform", "/docs/authentication", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2"]
+      "guides": ["/docs/realtime-platform", "/docs/authentication", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2", "/docs/application-platform"]
     },
     {
       "package": "bcp/testing",
@@ -107,7 +107,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-testing",
       "summary": "Framework-native testing utilities for Request/Response handlers, signed auth sessions, rollback transactions, page/server execution, middleware, jobs, workflows, outbox delivery, realtime sockets and SSE.",
-      "guides": ["/docs/testing-platform", "/docs/authentication", "/docs/database", "/docs/durable-jobs", "/docs/workflow-orchestration", "/docs/transactional-outbox-events", "/docs/realtime-platform", "/docs/observability-v3"]
+      "guides": ["/docs/testing-platform", "/docs/authentication", "/docs/database", "/docs/durable-jobs", "/docs/workflow-orchestration", "/docs/transactional-outbox-events", "/docs/realtime-platform", "/docs/observability-v3", "/docs/application-platform"]
     },
     {
       "package": "bcp/plugins",
@@ -115,7 +115,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-plugins",
       "summary": "Plugin and module composition with dependency ordering, lifecycle hooks, typed config parsing, shared services and asynchronous extension hooks.",
-      "guides": ["/docs/plugin-module-platform", "/docs/configuration", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2"]
+      "guides": ["/docs/plugin-module-platform", "/docs/configuration", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2", "/docs/application-platform"]
     },
     {
       "package": "bcp/observability",
@@ -123,7 +123,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-observability",
       "summary": "Metrics, Prometheus output, health checks and Observability Platform v3 distributed tracing with W3C trace context, correlation IDs, request tracing, span exporters and trace-to-metrics integration.",
-      "guides": ["/docs/observability", "/docs/observability-v3", "/docs/development-logging", "/docs/cache-platform-v2", "/docs/deployment-platform-v2"]
+      "guides": ["/docs/observability", "/docs/observability-v3", "/docs/development-logging", "/docs/cache-platform-v2", "/docs/deployment-platform-v2", "/docs/application-platform"]
     },
     {
       "package": "bcp/deployment",
@@ -131,7 +131,15 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-deployment",
       "summary": "Deployment Platform v2 runtime lifecycle with resource startup/shutdown ordering, readiness, diagnostics, deployment metadata, signal handling and framework shutdown-hook integration.",
-      "guides": ["/docs/deployment-platform-v2", "/docs/application-packaging", "/docs/production-hardening", "/docs/observability-v3"]
+      "guides": ["/docs/deployment-platform-v2", "/docs/application-packaging", "/docs/production-hardening", "/docs/observability-v3", "/docs/application-platform"]
+    },
+    {
+      "package": "bcp/application",
+      "source": "packages/client/src/application.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-application",
+      "summary": "Application Platform composition root for typed app config, shared services, plugins/modules, deployment resources, lifecycle ordering, readiness, diagnostics and graceful shutdown.",
+      "guides": ["/docs/application-platform", "/docs/plugin-module-platform", "/docs/deployment-platform-v2", "/docs/observability-v3", "/docs/migration-0.3"]
     },
     {
       "package": "bcp/server",