@chidchanun/bcp 0.2.18 → 0.3.0

package/docs/migration-0.2.md

@@ -1,63 +1,62 @@
-# Migrating to BCP Framework 0.2.0
+# Migrating within BCP Framework 0.2.x
 
-BCP Framework `0.2.0` establishes the Framework Platform baseline while preserving the public application model from `0.1.29`.
+BCP Framework `0.2.19` is the final `0.2.x` stability/API-freeze baseline before `0.3.0`.
 
-> **Release state:** unreleased development target until RC validation and npm publication complete.
+> **Current development target:** `0.2.19 — Stability & API Freeze`
+>
+> Release state remains unreleased until the complete RC sequence, tagging and npm publication finish.
 
 ## Compatibility goal
 
-There are no intentional public-entrypoint removals from the `0.1.29` baseline in this milestone.
+`0.2.19` declares no intentional breaking changes from `0.2.18`.
 
-Applications already running on `0.1.29` should normally be able to move to `0.2.0` without rewriting routing, loaders, guards, actions, middleware, storage or authentication code.
+The supported `0.2.x` public entrypoint/package-resolution contract is frozen in:
 
-BCP remains pre-1.0, so every application should still validate the upgrade before production deployment.
+```text
+docs/api-freeze-snapshot.json
+```
 
-## 1. Check the current project
+Applications should continue importing documented `bcp/*` entrypoints and avoid framework-private `packages/*` paths.
 
-From the application root:
+## 1. Inspect the current application
 
 ```powershell
 npm exec -- bcp-framework doctor
 npm exec -- bcp-framework inspect --json
+npm exec -- bcp-framework update --check
 ```
 
-Resolve blocking `FAIL` results before upgrading, especially duplicate framework dependency declarations or invalid production-hardening settings.
+Resolve blocking diagnostics before upgrading.
 
-## 2. Check the available framework update
-
-```powershell
-npm exec -- bcp-framework update --check
-```
+## 2. Upgrade explicitly
 
-After `0.2.0` is published, update with:
+After `0.2.19` is published:
 
 ```powershell
-npm exec -- bcp-framework update 0.2.0
+npm exec -- bcp-framework update 0.2.19
 ```
 
-Generated projects can also use:
+Generated applications can also use:
 
 ```powershell
-npm run update -- 0.2.0
+npm run update -- 0.2.19
 ```
 
-## 3. Keep one framework dependency
-
-The recommended project dependency remains:
+The recommended dependency remains one BCP installation:
 
 ```json
 {
   "dependencies": {
-    "bcp": "npm:@chidchanun/bcp@0.2.0"
+    "bcp": "npm:@chidchanun/bcp@0.2.19"
   }
 }
 ```
 
-Do not keep both `bcp` and a second direct `@chidchanun/bcp` dependency in the same application. Two installed framework copies can produce separate React/framework contexts.
+Do not keep both the `bcp` alias and a second direct `@chidchanun/bcp` dependency in the same application.
 
-## 4. Preserve server-only boundaries
+## 3. Keep public import boundaries
 
-Continue importing public APIs through supported entrypoints such as:
+Examples:
 
 ```ts
 import {
@@ -65,37 +64,61 @@ import {
 } from "bcp";
 
 import {
-    auth,
+    createAuth,
 } from "bcp/auth";
 
 import {
     db,
 } from "bcp/database";
 
+import {
+    createJobQueue,
+} from "bcp/jobs";
+
+import {
+    createDeploymentRuntime,
+} from "bcp/deployment";
+
 import {
     cookies,
 } from "bcp/server";
 ```
 
-Do not migrate application imports to framework-internal `packages/...` paths.
+The frozen entrypoint list is documented in [Framework Platform Contract](platform-contract.md) and [Stability & API Freeze](stability-api-freeze.md).
 
-The current public entrypoint baseline is listed in `platform-manifest.json` and [Framework Platform Contract](platform-contract.md).
+## 4. Rebuild production artifacts
 
-## 5. Validate generated-project metadata
+Do not reuse an old `.bcp-framework/build` or `.bcp-framework/package` directory after changing framework versions.
 
-Projects created by `create-bcp-app` `0.1.29` or newer may contain:
+Run:
 
-```text
-bcp.project.json
+```powershell
+npm run build
+npm run package
+```
+
+Then test the production runtime:
+
+```powershell
+npm start
 ```
 
-This file is optional runtime metadata. Older applications do not need to create it manually to run on `0.2.0`.
+## 5. Deployment/runtime review
 
-If you choose to add it to an older application, keep it non-secret. Credentials, passwords, access keys, session secrets and tokens do not belong in this file.
+For applications adopting Deployment Platform v2, consider registering long-lived resources such as:
+
+```text
+database
+cache/redis connections
+background workers
+realtime services
+outbox dispatchers
+workflow workers
+```
 
-## 6. Validate production settings
+in dependency order so reverse-order shutdown drains dependents before shared infrastructure closes.
 
-For standalone production, review:
+Review production environment settings such as:
 
 ```dotenv
 BCP_REQUEST_TIMEOUT_MS=120000
@@ -105,35 +128,17 @@ BCP_SHUTDOWN_TIMEOUT_MS=10000
 BCP_TRUST_PROXY=false
 ```
 
-Only enable:
+Deployment identity may additionally use:
 
 ```dotenv
-BCP_TRUST_PROXY=true
+BCP_DEPLOYMENT_ID=
+BCP_INSTANCE_ID=
+BCP_RELEASE=
 ```
 
-when the BCP process is reachable only through a trusted reverse proxy/load balancer.
+## 6. Application validation
 
-## 7. Rebuild the standalone artifact
-
-Do not reuse `.bcp-framework/build` from the previous framework version.
-
-Run:
-
-```powershell
-npm run build
-```
-
-Then test:
-
-```powershell
-npm start
-```
-
-The supported `0.2.0` production target remains the standalone Node.js artifact under `.bcp-framework/build/`.
-
-## 8. Application validation checklist
-
-Recommended minimum after upgrading:
+Recommended minimum:
 
 ```powershell
 npm run typecheck
@@ -142,32 +147,26 @@ npm exec -- bcp-framework routes
 npm exec -- bcp-framework doctor
 ```
 
-For applications using authentication, storage or database features, also exercise representative login/session, upload/download and database paths before production deployment.
+For applications using authentication, databases, storage, jobs, workflows, events, realtime or cache, exercise representative production paths before rollout.
 
-## Local storage projects
+## 7. What the 0.2.19 freeze means for applications
 
-Projects using the Local Server storage preset should keep the scaffold:
-
-```text
-storage/
-├─ .gitkeep
-└─ README.md
-```
+The freeze is a **framework release contract**, not a new runtime requirement for applications.
 
-Runtime storage objects remain ignored by Git.
+Applications do not need to run the framework repository's `api:check` or `release:readiness` scripts. Those are maintainer release gates.
 
-## Amazon S3 / Cloudflare R2 projects
+The practical application rule is:
 
-No provider migration is required for the `0.2.0` platform baseline. Existing `createS3Storage()` configurations continue using server-only credentials/environment settings.
-
-## What is not part of this migration
+```text
+use documented bcp/* entrypoints
+avoid private packages/* imports
+validate upgrades before deployment
+```
 
-`0.2.0` does not introduce native executable compilation, desktop packaging, Android APK output or iOS application output.
+## 8. Moving from 0.2.19 to 0.3.0
 
-The supported build model remains:
+`0.2.19` becomes the compatibility reference point for the next platform baseline.
 
-```text
-BCP application -> bcp build -> standalone Node.js web application
-```
+If `0.3.0` intentionally changes the frozen public surface, its release should provide explicit compatibility metadata and migration guidance rather than silently changing a `0.2.x` contract.
 
-Future build targets can be added after the platform baseline without redefining the existing standalone contract.
+Native executable/mobile/desktop compilation is still outside the current standalone Node.js web-application target.

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,30 +1,30 @@
 # Framework Platform Contract
 
-BCP Framework `0.2.0` establishes the first explicit framework-platform baseline. The goal is to make public entrypoints, supported runtime targets, CLI capabilities and documentation metadata visible and testable instead of relying on implicit package structure.
+BCP Framework exposes an explicit, machine-readable application-platform contract rather than relying on private repository structure.
 
-> **Release state:** unreleased development target until local RC validation, tagging and npm publication complete.
+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.
 
-## What the platform contract covers
+## Sources of truth
 
-The platform contract is represented by `docs/platform-manifest.json` and release/package smoke tests.
+```text
+docs/platform-manifest.json
+  -> framework/runtime/capability/public-entrypoint contract
+
+docs/api-manifest.json
+  -> public package source/environment/documentation ownership
 
-It records:
+docs/api-freeze-snapshot.json
+  -> reviewed CLI and prepared npm export baseline
 
-- the framework version and release state,
-- the minimum supported Node.js runtime,
-- the supported production build target,
-- public package entrypoints,
-- documented CLI command families,
-- framework capability groups,
-- built-in/scaffolded storage-provider families,
-- compatibility expectations for the previous baseline,
-- documentation files used by `bcp-docs-web`.
+docs/docs-web-manifest.json
+  -> documentation routes and release navigation
+```
 
-The manifest is metadata. Framework source, package exports and tests remain authoritative for actual runtime behavior.
+Framework source and tests remain authoritative for runtime behavior. The manifests make the supported surface testable during release validation.
 
 ## Public entrypoints
 
-The `0.2.0` platform baseline recognizes these public application imports:
+The `0.3.0` baseline supports:
 
 ```text
 bcp
@@ -35,125 +35,139 @@ 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
 ```
 
-Application code should prefer these entrypoints instead of importing internal files under `packages/`.
+`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 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
+```
 
-The release package contract smoke test verifies that the prepared npm artifact still exposes these entrypoints. Accidentally removing one from the publish manifest should fail package validation before release.
+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 framework-platform CLI baseline includes:
+The command families remain:
 
 ```text
 bcp dev
 bcp build
+bcp package
 bcp start
 bcp routes
 bcp update
 bcp db ...
 bcp generate ...
+bcp config ...
 bcp doctor
 bcp inspect
 bcp help
 bcp version
 ```
 
-The Windows-safe `bcp-framework` executable remains an alias for the same CLI.
+The Windows-safe `bcp-framework` executable is an alias for the same CLI.
 
 ## Runtime baseline
 
-BCP `0.2.0` continues to target a standalone Node.js web application:
-
-```text
-BCP source application
-        ↓
-     bcp build
-        ↓
-.bcp-framework/build/
-├─ client/
-├─ public/
-└─ server/
-   └─ server.mjs
-```
-
-Minimum runtime:
-
 ```text
 Node.js >= 24.11.0
 React 19
+build target: standalone-node
+package target: standalone-node
 ```
 
-The platform baseline does not yet promise native `.exe`, mobile or desktop application compilation. Those remain future build-target work rather than part of `0.2.0`.
+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.0
+## Compatibility policy
 
-`0.2.0` is intended to preserve applications that already work on `0.1.29`. This milestone does not intentionally remove public entrypoints or change the current standalone runtime model.
+For `0.3.0`:
 
-Because BCP remains pre-1.0, applications should still validate upgrades through:
-
-```bash
-bcp update --check
-bcp doctor
-npm run typecheck
-npm run build
+```text
+previous baseline: 0.2.19
+intentional breaking changes: false
+baseline: application-platform
 ```
 
-See [Migrating to 0.2.0](migration-0.2.md).
+`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.
 
-## Package consistency validation
+Bug fixes must not silently remove a documented public entrypoint or change its prepared package-resolution/browser-boundary contract.
 
-The `0.2.0` release process adds a platform-contract package smoke check. It verifies the staged npm artifact rather than only source files.
+## API compatibility gate
 
-The check covers:
-
-1. framework version consistency,
-2. required public package exports,
-3. both BCP CLI executable aliases,
-4. minimum Node.js engine declaration,
-5. inclusion of platform/docs metadata in the packed framework,
-6. docs-web target/version consistency,
-7. create-bcp-app version parity with the framework release.
-
-This is additive to existing unit, integration, E2E, storage, production-hardening and Developer Experience package smoke checks.
+```bash
+npm run api:check
+```
 
-## Docs-web contract
+The gate prepares the publish package, regenerates the current contract in memory and compares it to `docs/api-freeze-snapshot.json`.
 
-`bcp-docs-web` should use two machine-readable files for different purposes:
+To intentionally regenerate the snapshot for a reviewed platform-baseline change:
 
-```text
-docs/docs-web-manifest.json
-  -> website sections, routes, source Markdown and release navigation
-
-docs/platform-manifest.json
-  -> framework version, public entrypoints, runtime target and capability metadata
+```bash
+npm run api:snapshot
 ```
 
-Do not duplicate the platform entrypoint list in application code when it can be sourced from `platform-manifest.json`.
+Do not regenerate the snapshot merely to silence an unexpected compatibility failure.
 
-## Stability labels
+## Release readiness
 
-Documentation should distinguish:
+```bash
+npm run release:readiness
+npm run release:readiness:report
+```
 
-- **platform baseline** — public surface covered by the `0.2.0` contract,
-- **supported** — behavior covered by current tests/docs,
-- **experimental/roadmap** — not guaranteed by the current platform manifest,
-- **internal** — not a public application import contract.
+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.0` is tagged or published:
+Before `0.3.0` is tagged or published:
 
 ```bash
 npm run typecheck
 npm run test:unit
 npm run test:integration
-npm run test:package
 npm run test:e2e
+npm run test:package
+npm run api:check
+npm run release:readiness
 npm run rc:check
 ```
 
-The release is not considered published until both `@chidchanun/bcp@0.2.0` and `create-bcp-app@0.2.0` are visible from npm.
+`rc:check` must pass on the exact commit used for the release tag.
+
+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).