@chidchanun/bcp 0.2.19 → 0.3.0

package/docs/stability-api-freeze.md

@@ -1,27 +1,12 @@
 # Stability & API Freeze — 0.2.19
 
-BCP Framework `0.2.19` is the final stabilization milestone for the `0.2.x` platform before the next `0.3.0` application-platform baseline.
+BCP Framework `0.2.19` is the final stabilization milestone for the `0.2.x` platform and the compatibility point used to establish the `0.3.0` Application Platform baseline.
 
-This release intentionally does **not** add a new application subsystem. Its purpose is to freeze the supported public package/CLI contract, strengthen release gates and catch accidental compatibility regressions before publication.
+This release intentionally did **not** add a new application subsystem. Its purpose was to freeze the supported public package/CLI contract, strengthen release gates and catch accidental compatibility regressions.
 
-## Frozen contract
+## Historical 0.2.19 contract
 
-The committed source of truth is:
-
-```text
-docs/api-freeze-snapshot.json
-```
-
-It records:
-
-- the supported `bcp/*` public entrypoint set;
-- the supported CLI command set;
-- prepared npm `exports` including `types`, `default` and `browser` targets;
-- API source/environment ownership from `docs/api-manifest.json`;
-- the compatibility baseline (`0.2.18`);
-- the no-intentional-breaking-change policy for `0.2.19`.
-
-The frozen public package entrypoints are:
+The `0.2.19` release froze these public package entrypoints:
 
 ```text
 bcp
@@ -45,7 +30,37 @@ bcp/server-only
 bcp/middleware
 ```
 
-`./package.json` is also frozen as a package export, although it is not an application API entrypoint.
+`./package.json` was also included in the prepared npm package contract, although it is not an application API module.
+
+The historical compatibility policy was:
+
+```text
+release: 0.2.19
+previous baseline: 0.2.18
+intentional breaking changes: false
+freeze state: frozen
+```
+
+## Current snapshot file
+
+The repository continues to use:
+
+```text
+docs/api-freeze-snapshot.json
+```
+
+as the **current reviewed API baseline**, not as a permanently immutable copy of the `0.2.19` file.
+
+After the Application Platform work begins, that file advances to the reviewed `0.3.0` baseline with:
+
+```text
+version: 0.3.0
+baselineVersion: 0.2.19
+```
+
+and adds `bcp/application` while preserving the `0.2.19` entrypoints.
+
+The historical `0.2.19` release notes and this guide document why the freeze exists; the current snapshot is the contract enforced by the active release gate.
 
 ## API compatibility gate
 
@@ -59,81 +74,49 @@ The compatibility checker prepares the exact npm staging package, generates the
 
 The check fails when, for example:
 
-- a public entrypoint is removed or added;
-- a CLI command changes without an explicit new platform baseline;
-- `bcp/server` stops resolving to `server.mjs` in the prepared package;
+- a public entrypoint changes unexpectedly;
+- a CLI command changes outside an intentional baseline update;
+- a compiled runtime target drifts;
 - a server-only browser poison target disappears;
 - an entrypoint changes API source/environment ownership;
-- the current version/baseline no longer matches the committed freeze.
-
-This prevents source metadata, prepared npm metadata and documentation metadata from drifting independently.
+- version/baseline metadata no longer matches the committed contract.
 
 ## Snapshot regeneration
 
-To intentionally regenerate the contract:
+To intentionally regenerate the current contract:
 
 ```bash
 npm run api:snapshot
 ```
 
-That command rewrites:
-
-```text
-docs/api-freeze-snapshot.json
-```
-
-For `0.2.19`, snapshot changes require explicit review because the milestone promises no intentional breaking changes from `0.2.18`.
+Do not regenerate the snapshot merely to silence an unexpected compatibility failure. Snapshot updates should accompany an intentional, reviewed platform-baseline change with migration documentation and regression coverage.
 
-Large or breaking public-surface changes should normally be deferred to `0.3.0` rather than silently updating the `0.2.19` snapshot.
+`0.3.0` is such an intentional additive baseline update: it adds `bcp/application` and uses `0.2.19` as its previous compatibility baseline.
 
 ## Release readiness
 
-Run:
+The current release uses:
 
 ```bash
 npm run release:readiness
-```
-
-The readiness report checks:
-
-- root/client/create-app version parity;
-- `package-lock.json` version parity;
-- platform/API/docs-web version parity;
-- `unreleased` release state;
-- `0.2.18` previous-baseline metadata;
-- no intentional breaking changes;
-- API freeze snapshot version/baseline;
-- public entrypoint parity;
-- CLI freeze parity;
-- current release notes and docs route;
-- stability capability flags.
-
-To also persist a local machine-readable report:
-
-```bash
 npm run release:readiness:report
 ```
 
-The report is written to:
+The readiness gate evolves with the active milestone. During `0.2.19` it validated freeze metadata; for `0.3.0` it validates the Application Platform baseline, `bcp/application` ownership, package/runtime parity and the `0.2.19` previous baseline.
+
+The optional report is written to:
 
 ```text
 .bcp-framework/release-readiness.json
 ```
 
-It is a local build artifact and is not the release source of truth.
-
 ## RC integration
 
-`0.2.19` strengthens the release pipeline:
+The stability infrastructure remains part of every later RC:
 
 ```text
 npm run typecheck
 npm test
-  -> unit
-  -> integration
-  -> e2e
-  -> prepared-package smoke
-      -> Stability & API Freeze smoke
 npm run api:check
 npm run release:readiness
 release metadata check
@@ -143,37 +126,25 @@ npm publish dry-run
 
 `npm run rc:check` must pass on the exact commit that will be tagged.
 
-## Lifecycle stabilization
-
-The stability suite adds explicit idempotency coverage for Deployment Platform v2:
-
-- concurrent/repeated `start()` calls must start a resource once;
-- concurrent/repeated `shutdown()` calls must stop a resource once;
-- shutdown remains reverse ordered;
-- a stopped runtime cannot be restarted.
-
-Existing subsystem-specific suites remain authoritative for jobs, workflows, outbox/events, realtime, cache, plugins and deployment behavior.
+## Lifecycle stabilization retained
 
-## Compatibility policy
+The `0.2.19` suite added explicit idempotency coverage for Deployment Platform v2:
 
-`0.2.19` declares:
-
-```text
-previous baseline: 0.2.18
-intentional breaking changes: false
-freeze state: frozen
-```
+- concurrent/repeated `start()` calls start a resource once;
+- concurrent/repeated `shutdown()` calls stop a resource once;
+- shutdown remains reverse ordered.
 
-Bug fixes may still change incorrect implementation behavior, but they must not silently remove documented public entrypoints or change their package-resolution contract.
+Those regressions remain part of the unit suite after the baseline advances.
 
-## Moving to 0.3.0
+## Relationship to 0.3.0
 
-`0.3.0` is the next platform baseline. That milestone may intentionally revise the frozen surface, but changes should be accompanied by:
+`0.3.0 — BCP Application Platform` follows the process established by this freeze:
 
-1. a reviewed API snapshot update;
-2. explicit compatibility/breaking-change metadata;
-3. migration documentation;
-4. updated package/docs manifests;
-5. regression and prepared-package coverage.
+1. use `0.2.19` as the previous baseline;
+2. add the intentional public surface (`bcp/application`);
+3. update and review the current API snapshot;
+4. add migration documentation;
+5. update package/platform/docs manifests;
+6. add unit and prepared-package regression coverage.
 
-The `0.2.19` snapshot therefore becomes the comparison point for the next platform-generation work.
+See [Application Platform](application-platform.md) and [Migrating to 0.3.0](migration-0.3.md).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.2.19",
-  "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
+  "version": "0.3.0",
+  "description": "BCP Framework - a React full-stack application platform with routing, SSR, APIs, lifecycle composition and standalone production builds.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -16,6 +16,7 @@
     "bcp",
     "react",
     "framework",
+    "application-platform",
     "ssr",
     "routing",
     "fullstack"
@@ -102,6 +103,11 @@
       "browser": "./packages/client/src/server-only.browser.mjs",
       "default": "./packages/client/src/deployment.mjs"
     },
+    "./application": {
+      "types": "./packages/client/src/application.ts",
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/application.mjs"
+    },
     "./server": {
       "types": "./packages/client/src/server.ts",
       "browser": "./packages/client/src/server-only.browser.mjs",

package/packages/bundler/src/client-boundary.ts

@@ -36,6 +36,7 @@ const SERVER_ONLY_IMPORTS =
         "bcp/plugins",
         "bcp/observability",
         "bcp/deployment",
+        "bcp/application",
     ]);
 
 export function validateClientBoundaries(