@chidchanun/bcp 0.2.18 → 0.2.19

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.18",
+  "version": "0.2.19",
   "releaseState": "unreleased",
-  "baseline": "deployment-platform-v2",
+  "baseline": "stability-api-freeze",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -95,6 +95,12 @@
     "compiledAuthRuntime": true,
     "compiledServerRuntime": true,
     "compiledMiddlewareRuntime": true,
+    "stabilityApiFreeze": true,
+    "apiFreezeSnapshot": true,
+    "apiCompatibilityGate": true,
+    "releaseReadinessReport": true,
+    "packageExportParity": true,
+    "deploymentLifecycleIdempotency": true,
     "backgroundJobsPlatform": true,
     "jobQueueAdapterContract": true,
     "inMemoryJobQueue": true,
@@ -224,7 +230,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.17",
+    "previousBaseline": "0.2.18",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -232,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",
@@ -253,6 +261,6 @@
     "pluginModulePlatform": "plugin-module-platform.md",
     "cachePlatformV2": "cache-platform-v2.md",
     "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.18.md"
+    "releaseNotes": "releases/0.2.19.md"
   }
 }

package/docs/releases/0.2.19.md

@@ -0,0 +1,125 @@
+# BCP Framework 0.2.19
+
+Status: **unreleased**
+
+Milestone: **Stability & API Freeze**
+
+`0.2.19` is the final `0.2.x` stabilization milestone before the next `0.3.0` application-platform baseline.
+
+## Highlights
+
+- freezes the documented `bcp/*` public entrypoint set;
+- freezes the supported CLI command set;
+- freezes prepared npm export resolution including browser boundaries;
+- adds deterministic API snapshot generation;
+- adds an API compatibility gate to RC validation;
+- adds a release-readiness report;
+- adds prepared-package Stability & API Freeze smoke coverage;
+- adds deployment lifecycle idempotency regression coverage;
+- keeps compatibility with `0.2.18` with no intentional breaking changes.
+
+## API freeze snapshot
+
+New source of truth:
+
+```text
+docs/api-freeze-snapshot.json
+```
+
+Generate intentionally with:
+
+```bash
+npm run api:snapshot
+```
+
+Validate without changing the snapshot:
+
+```bash
+npm run api:check
+```
+
+The compatibility check prepares the publish package and compares the current package/CLI/API ownership contract against the committed snapshot.
+
+## Release readiness
+
+New commands:
+
+```bash
+npm run release:readiness
+npm run release:readiness:report
+```
+
+The persisted report is written locally to:
+
+```text
+.bcp-framework/release-readiness.json
+```
+
+Readiness includes package/lock/manifests version parity, freeze/baseline metadata, release-note/docs presence and public API parity.
+
+## RC pipeline
+
+`release:check` now includes:
+
+```text
+typecheck
+full test suite
+API compatibility check
+release readiness check
+release metadata check
+```
+
+`test:package` / `package:check` also include `stability-api-freeze-package-smoke.mjs`.
+
+## Compatibility
+
+```text
+previous baseline: 0.2.18
+intentional breaking changes: false
+freeze state: frozen
+```
+
+The existing public package surface remains unchanged from `0.2.18`:
+
+```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
+```
+
+## Validation before release
+
+Run on the exact release commit:
+
+```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 tag or publish until the complete RC sequence passes.
+
+## Next baseline
+
+`0.3.0` is the next planned BCP Application Platform baseline. Intentional public API changes should be made there with explicit migration and compatibility metadata rather than silently changing the frozen `0.2.19` contract.