@chidchanun/bcp 0.2.17 → 0.2.19

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/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 `0.2.x` 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.2.19 — Stability & API Freeze`** 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
 
-It records:
+docs/api-manifest.json
+  -> public package source/environment/documentation ownership
 
-- 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/api-freeze-snapshot.json
+  -> frozen 0.2.19 CLI and prepared npm export contract
+
+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 that supported surface testable during release validation.
 
-## Public entrypoints
+## Frozen public entrypoints
 
-The `0.2.0` platform baseline recognizes these public application imports:
+The `0.2.19` baseline supports:
 
 ```text
 bcp
@@ -35,125 +35,110 @@ 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 prefer these entrypoints instead of importing internal files under `packages/`.
+Application code should use these entrypoints instead of private `packages/*` implementation paths.
 
-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.
+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.
 
 ## CLI baseline
 
-The framework-platform CLI baseline includes:
+The frozen command families are:
 
 ```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. Their exact `types`, `default` and `browser` targets are frozen in `api-freeze-snapshot.json`.
 
-## 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.2.19`:
 
-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.18
+intentional breaking changes: false
+freeze state: frozen
 ```
 
-See [Migrating to 0.2.0](migration-0.2.md).
+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.
 
-## Package consistency validation
+Intentional public-platform changes should normally move to `0.3.0` with explicit compatibility metadata and migration documentation.
 
-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.
-
-## Docs-web contract
+```bash
+npm run api:check
+```
 
-`bcp-docs-web` should use two machine-readable files for different purposes:
+The gate prepares the publish package, regenerates the current contract in memory and compares it to `docs/api-freeze-snapshot.json`.
 
-```text
-docs/docs-web-manifest.json
-  -> website sections, routes, source Markdown and release navigation
+To intentionally regenerate the snapshot:
 
-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`.
+Snapshot changes during `0.2.19` require explicit review; regeneration is not a routine fix for a failing compatibility check.
 
-## 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, freeze parity, release docs and stability capabilities. The optional local report is written to `.bcp-framework/release-readiness.json`.
 
 ## Release validation
 
-Before `0.2.0` is tagged or published:
+Before `0.2.19` 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 [Stability & API Freeze](stability-api-freeze.md) and [Migrating to 0.2.x](migration-0.2.md).

package/docs/platform-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.17",
+  "version": "0.2.19",
   "releaseState": "unreleased",
-  "baseline": "observability-platform-v3",
+  "baseline": "stability-api-freeze",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -26,6 +26,7 @@
     "bcp/testing",
     "bcp/plugins",
     "bcp/observability",
+    "bcp/deployment",
     "bcp/server",
     "bcp/server-only",
     "bcp/middleware"
@@ -82,6 +83,24 @@
     "traceMetricsExporter": true,
     "traceLogFields": true,
     "compiledObservabilityRuntime": true,
+    "deploymentPlatformV2": true,
+    "deploymentRuntimeLifecycle": true,
+    "deploymentResourceRegistry": true,
+    "deploymentReadiness": true,
+    "deploymentDiagnostics": true,
+    "deploymentSignalHandling": true,
+    "deploymentShutdownHooks": true,
+    "deploymentRuntimeMetadata": true,
+    "compiledConfigRuntime": true,
+    "compiledAuthRuntime": true,
+    "compiledServerRuntime": true,
+    "compiledMiddlewareRuntime": true,
+    "stabilityApiFreeze": true,
+    "apiFreezeSnapshot": true,
+    "apiCompatibilityGate": true,
+    "releaseReadinessReport": true,
+    "packageExportParity": true,
+    "deploymentLifecycleIdempotency": true,
     "backgroundJobsPlatform": true,
     "jobQueueAdapterContract": true,
     "inMemoryJobQueue": true,
@@ -211,7 +230,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.16",
+    "previousBaseline": "0.2.18",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -219,9 +238,11 @@
     "navigationManifest": "docs-web-manifest.json",
     "platformManifest": "platform-manifest.json",
     "apiManifest": "api-manifest.json",
+    "apiFreezeSnapshot": "api-freeze-snapshot.json",
     "platformContract": "platform-contract.md",
     "documentationPlatform": "documentation-platform.md",
     "apiReference": "api-reference.md",
+    "stabilityApiFreeze": "stability-api-freeze.md",
     "environmentValidation": "environment-validation.md",
     "applicationPackaging": "application-packaging.md",
     "authentication": "authentication.md",
@@ -229,6 +250,7 @@
     "authorizationSecurity": "authorization-security.md",
     "observability": "observability.md",
     "observabilityV3": "observability-v3.md",
+    "deploymentPlatformV2": "deployment-platform-v2.md",
     "backgroundJobs": "background-jobs.md",
     "jobScheduling": "job-scheduling.md",
     "durableJobs": "durable-jobs.md",
@@ -239,6 +261,6 @@
     "pluginModulePlatform": "plugin-module-platform.md",
     "cachePlatformV2": "cache-platform-v2.md",
     "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.17.md"
+    "releaseNotes": "releases/0.2.19.md"
   }
 }