@chidchanun/bcp 0.2.19 → 0.3.0

package/docs/migration-0.3.md

@@ -0,0 +1,159 @@
+# Migrating to BCP Framework 0.3.0
+
+BCP Framework `0.3.0` establishes the Application Platform baseline while preserving the public entrypoints frozen in `0.2.19`.
+
+> **Release state:** unreleased until RC validation, tagging and npm publication complete.
+
+## Compatibility goal
+
+`0.3.0` intentionally adds one public server-only package entrypoint:
+
+```text
+bcp/application
+```
+
+No `0.2.19` public entrypoint is intentionally removed. Existing applications do not have to adopt the new application runtime immediately.
+
+## Upgrade
+
+After `0.3.0` is published:
+
+```powershell
+npm exec -- bcp-framework update --check
+npm run update -- 0.3.0
+```
+
+Then rebuild the application:
+
+```powershell
+npm run typecheck
+npm run build
+npm exec -- bcp-framework doctor
+```
+
+Do not reuse a `.bcp-framework/build` directory produced by `0.2.x`.
+
+## Existing 0.2.x composition remains valid
+
+These imports remain public:
+
+```ts
+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 { createCacheStore } from "bcp/cache";
+import { createPluginHost } from "bcp/plugins";
+import { createTracer } from "bcp/observability";
+import { createDeploymentRuntime } from "bcp/deployment";
+```
+
+You can continue owning lifecycle manually if that is already appropriate for the project.
+
+## Optional migration to createApp
+
+New or gradually modernized applications can centralize composition:
+
+```ts
+import {
+    createApp,
+} from "bcp/application";
+
+export const app =
+    createApp({
+        name: "my-app",
+        version: "1.0.0",
+    });
+```
+
+Register shared service instances before startup:
+
+```ts
+app.provide("database", database);
+app.provide("cache", cache);
+app.provide("jobs", jobs);
+```
+
+Register lifecycle-owned resources:
+
+```ts
+app.addResource({
+    name: "database",
+    start: () => database.connect(),
+    stop: () => database.close(),
+});
+```
+
+Then:
+
+```ts
+await app.start();
+```
+
+## Lifecycle ownership
+
+Do not allow both the application runtime and separate application code to independently start/stop the same resource.
+
+Choose one lifecycle owner for each database pool, worker, scheduler, broker or other long-running resource.
+
+The Application Platform starts:
+
+```text
+plugins
+resources
+application hook
+```
+
+and stops them in reverse dependency order.
+
+## Plugins and modules
+
+Existing `definePlugin()` and `defineModule()` values work directly:
+
+```ts
+const app =
+    createApp({
+        name: "my-app",
+        modules: [
+            backendModule,
+        ],
+    });
+```
+
+No plugin rewrite is required for `0.3.0`.
+
+## Server-only boundary
+
+`bcp/application` owns process lifecycle and infrastructure composition. Do not import it from React client pages or islands.
+
+Use it from server bootstrap/application composition modules.
+
+## API baseline
+
+`0.2.19` remains the previous compatibility baseline. The reviewed `0.3.0` API snapshot adds `bcp/application` and becomes the new release contract used by `npm run api:check`.
+
+## Validation checklist
+
+For framework development:
+
+```powershell
+npm run typecheck
+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
+```
+
+For an application upgrading from `0.2.19`:
+
+```powershell
+npm run typecheck
+npm run build
+npm exec -- bcp-framework routes
+npm exec -- bcp-framework doctor
+```

package/docs/platform-contract.md

@@ -1,8 +1,8 @@
 # Framework Platform Contract
 
-BCP Framework `0.2.x` exposes an explicit, machine-readable application-platform contract rather than relying on private repository structure.
+BCP Framework exposes an explicit, machine-readable application-platform contract rather than relying on private repository structure.
 
-The current development baseline is **`0.2.19 — Stability & API Freeze`** and remains unreleased until the complete RC sequence passes, the exact release commit is tagged and npm publication completes.
+The current development baseline is **`0.3.0 — BCP Application Platform`** and remains unreleased until the complete RC sequence passes, the exact release commit is tagged and npm publication completes.
 
 ## Sources of truth
 
@@ -14,17 +14,17 @@ docs/api-manifest.json
   -> public package source/environment/documentation ownership
 
 docs/api-freeze-snapshot.json
-  -> frozen 0.2.19 CLI and prepared npm export contract
+  -> reviewed CLI and prepared npm export baseline
 
 docs/docs-web-manifest.json
   -> documentation routes and release navigation
 ```
 
-Framework source and tests remain authoritative for runtime behavior. The manifests make that supported surface testable during release validation.
+Framework source and tests remain authoritative for runtime behavior. The manifests make the supported surface testable during release validation.
 
-## Frozen public entrypoints
+## Public entrypoints
 
-The `0.2.19` baseline supports:
+The `0.3.0` baseline supports:
 
 ```text
 bcp
@@ -43,18 +43,47 @@ bcp/testing
 bcp/plugins
 bcp/observability
 bcp/deployment
+bcp/application
 bcp/server
 bcp/server-only
 bcp/middleware
 ```
 
+`bcp/application` is the one new entrypoint relative to the `0.2.19` baseline. No existing `0.2.19` public entrypoint is intentionally removed.
+
 Application code should use these entrypoints instead of private `packages/*` implementation paths.
 
-The prepared npm package also exposes `./package.json`; that package export is included in the freeze snapshot even though it is not an application API module.
+The prepared npm package also exposes `./package.json`; that package export is included in the API snapshot even though it is not an application API module.
+
+## Application Platform baseline
+
+`bcp/application` adds a server-only composition root:
+
+```ts
+import {
+    createApp,
+    defineApp,
+} from "bcp/application";
+```
+
+The Application Platform reuses the existing Plugin and Deployment platforms for:
+
+```text
+typed application config
+shared services and hooks
+plugins/modules
+resource lifecycle
+startup rollback
+readiness/diagnostics
+signal handling
+graceful shutdown
+```
+
+It does not replace existing database, jobs, cache, events, realtime or other subsystem APIs. Applications may use those independently or compose selected instances through the application root.
 
 ## CLI baseline
 
-The frozen command families are:
+The command families remain:
 
 ```text
 bcp dev
@@ -83,21 +112,21 @@ build target: standalone-node
 package target: standalone-node
 ```
 
-Prepared server/runtime entrypoints resolve to compiled ESM where required by the package contract. Their exact `types`, `default` and `browser` targets are frozen in `api-freeze-snapshot.json`.
+Prepared server/runtime entrypoints resolve to compiled ESM where required by the package contract. `0.3.0` adds compiled `application.mjs`.
 
 ## Compatibility policy
 
-For `0.2.19`:
+For `0.3.0`:
 
 ```text
-previous baseline: 0.2.18
+previous baseline: 0.2.19
 intentional breaking changes: false
-freeze state: frozen
+baseline: application-platform
 ```
 
-Bug fixes may correct implementation behavior, but they must not silently remove a documented public entrypoint or change its prepared package-resolution/browser-boundary contract.
+`0.2.19` remains the historical freeze point for `0.2.x`. `0.3.0` intentionally advances the reviewed API snapshot by adding `bcp/application` and becomes the next compatibility baseline.
 
-Intentional public-platform changes should normally move to `0.3.0` with explicit compatibility metadata and migration documentation.
+Bug fixes must not silently remove a documented public entrypoint or change its prepared package-resolution/browser-boundary contract.
 
 ## API compatibility gate
 
@@ -107,13 +136,13 @@ npm run api:check
 
 The gate prepares the publish package, regenerates the current contract in memory and compares it to `docs/api-freeze-snapshot.json`.
 
-To intentionally regenerate the snapshot:
+To intentionally regenerate the snapshot for a reviewed platform-baseline change:
 
 ```bash
 npm run api:snapshot
 ```
 
-Snapshot changes during `0.2.19` require explicit review; regeneration is not a routine fix for a failing compatibility check.
+Do not regenerate the snapshot merely to silence an unexpected compatibility failure.
 
 ## Release readiness
 
@@ -122,11 +151,11 @@ npm run release:readiness
 npm run release:readiness:report
 ```
 
-The readiness gate checks version/lock/manifests parity, compatibility metadata, freeze parity, release docs and stability capabilities. The optional local report is written to `.bcp-framework/release-readiness.json`.
+The readiness gate checks version/lock/manifests parity, compatibility metadata, application entrypoint ownership, API snapshot parity, release docs and Application Platform capability flags. The optional report is written to `.bcp-framework/release-readiness.json`.
 
 ## Release validation
 
-Before `0.2.19` is tagged or published:
+Before `0.3.0` is tagged or published:
 
 ```bash
 npm run typecheck
@@ -141,4 +170,4 @@ npm run rc:check
 
 `rc:check` must pass on the exact commit used for the release tag.
 
-See [Stability & API Freeze](stability-api-freeze.md) and [Migrating to 0.2.x](migration-0.2.md).
+See [Application Platform](application-platform.md), [Migrating to 0.3.0](migration-0.3.md), and the historical [Stability & API Freeze](stability-api-freeze.md).

package/docs/platform-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.19",
+  "version": "0.3.0",
   "releaseState": "unreleased",
-  "baseline": "stability-api-freeze",
+  "baseline": "application-platform",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -27,6 +27,7 @@
     "bcp/plugins",
     "bcp/observability",
     "bcp/deployment",
+    "bcp/application",
     "bcp/server",
     "bcp/server-only",
     "bcp/middleware"
@@ -95,6 +96,19 @@
     "compiledAuthRuntime": true,
     "compiledServerRuntime": true,
     "compiledMiddlewareRuntime": true,
+    "applicationPlatform": true,
+    "applicationDefinitions": true,
+    "applicationRuntime": true,
+    "applicationConfigSchemas": true,
+    "applicationServiceRegistry": true,
+    "applicationPluginComposition": true,
+    "applicationModuleComposition": true,
+    "applicationResourceLifecycle": true,
+    "applicationReadiness": true,
+    "applicationDiagnostics": true,
+    "applicationLifecycleRollback": true,
+    "applicationLifecycleIdempotency": true,
+    "compiledApplicationRuntime": true,
     "stabilityApiFreeze": true,
     "apiFreezeSnapshot": true,
     "apiCompatibilityGate": true,
@@ -230,9 +244,9 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.18",
+    "previousBaseline": "0.2.19",
     "intentionalBreakingChangesFromPreviousBaseline": false,
-    "migrationGuide": "migration-0.2.md"
+    "migrationGuide": "migration-0.3.md"
   },
   "documentation": {
     "navigationManifest": "docs-web-manifest.json",
@@ -243,6 +257,7 @@
     "documentationPlatform": "documentation-platform.md",
     "apiReference": "api-reference.md",
     "stabilityApiFreeze": "stability-api-freeze.md",
+    "applicationPlatform": "application-platform.md",
     "environmentValidation": "environment-validation.md",
     "applicationPackaging": "application-packaging.md",
     "authentication": "authentication.md",
@@ -260,7 +275,7 @@
     "testingPlatform": "testing-platform.md",
     "pluginModulePlatform": "plugin-module-platform.md",
     "cachePlatformV2": "cache-platform-v2.md",
-    "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.19.md"
+    "migrationGuide": "migration-0.3.md",
+    "releaseNotes": "releases/0.3.0.md"
   }
 }

package/docs/releases/0.3.0.md

@@ -0,0 +1,129 @@
+# BCP Framework 0.3.0 — Application Platform
+
+`0.3.0` establishes the first BCP Application Platform baseline on top of the infrastructure and API freeze completed in `0.2.x`.
+
+> **Release state:** unreleased until the complete RC gate passes, `v0.3.0` is tagged and both npm packages are published successfully.
+
+## Highlights
+
+- Adds the server-only `bcp/application` public entrypoint.
+- Adds `defineApp()` for validated application definitions.
+- Adds `createApp()` for a unified application composition root.
+- Reuses the existing Plugin Platform service registry and hook bus.
+- Reuses existing plugin/module definitions without conversion.
+- Reuses Deployment Platform resources, readiness, diagnostics, signal handling and shutdown hooks.
+- Adds typed application-level config parsing.
+- Adds deterministic application lifecycle ordering.
+- Adds startup rollback and terminal cleanup through the deployment resource graph.
+- Adds concurrent/repeated start and shutdown idempotency coverage.
+- Publishes `application.mjs` as a compiled production runtime.
+- Adds prepared-package smoke coverage for the new entrypoint and lifecycle.
+
+## Public API
+
+```ts
+import {
+    ApplicationLifecycleError,
+    createApp,
+    defineApp,
+} from "bcp/application";
+```
+
+Key types:
+
+```text
+Application
+ApplicationConfigParser
+ApplicationConfigSchema
+ApplicationContext
+ApplicationDefinition
+ApplicationState
+```
+
+## Application composition
+
+```ts
+const app =
+    createApp({
+        name: "orders-api",
+        version: "1.0.0",
+        plugins: [
+            authPlugin,
+            jobsPlugin,
+        ],
+        resources: [
+            databaseResource,
+            workerResource,
+        ],
+    });
+
+await app.start();
+```
+
+The application exposes the shared platform objects directly:
+
+```text
+app.services
+app.hooks
+app.plugins
+app.deployment
+```
+
+Existing provider-native database, cache, job, workflow, event and realtime instances can be stored in the service registry or wrapped in deployment resources as appropriate.
+
+## Lifecycle
+
+Startup:
+
+```text
+application.setup
+plugin setup/start
+resources start in registration order
+application.start
+```
+
+Shutdown:
+
+```text
+application.stop
+resources stop in reverse order
+plugin stop/dispose
+application.dispose
+```
+
+Startup failures roll back already-started resources in reverse order.
+
+## Compatibility
+
+The `0.2.19` Stability & API Freeze release is the compatibility baseline for `0.3.0`.
+
+`0.3.0` intentionally adds:
+
+```text
+bcp/application
+```
+
+No existing `0.2.19` public entrypoint is intentionally removed.
+
+The API snapshot/compatibility tooling is updated to establish the reviewed `0.3.0` package baseline after the new entrypoint is added.
+
+## Validation
+
+Before tagging:
+
+```bash
+npm run typecheck
+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
+```
+
+Do not publish until these commands pass on the exact final release commit.
+
+## Next milestone
+
+`0.3.1 — Dependency Injection & Service Container` is planned to add typed service tokens, singleton/scoped/transient lifetimes, request scopes, factories and testing overrides on top of the shared Application Platform service composition model.