@chidchanun/bcp 0.2.17 → 0.2.19

package/docs/stability-api-freeze.md

@@ -0,0 +1,179 @@
+# 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.
+
+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.
+
+## Frozen 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:
+
+```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
+```
+
+`./package.json` is also frozen as a package export, although it is not an application API entrypoint.
+
+## API compatibility gate
+
+Run:
+
+```bash
+npm run api:check
+```
+
+The compatibility checker prepares the exact npm staging package, generates the current contract and compares it to `docs/api-freeze-snapshot.json`.
+
+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 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.
+
+## Snapshot regeneration
+
+To intentionally regenerate the 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`.
+
+Large or breaking public-surface changes should normally be deferred to `0.3.0` rather than silently updating the `0.2.19` snapshot.
+
+## Release readiness
+
+Run:
+
+```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:
+
+```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:
+
+```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
+npm name/version checks
+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.
+
+## Compatibility policy
+
+`0.2.19` declares:
+
+```text
+previous baseline: 0.2.18
+intentional breaking changes: false
+freeze state: frozen
+```
+
+Bug fixes may still change incorrect implementation behavior, but they must not silently remove documented public entrypoints or change their package-resolution contract.
+
+## Moving 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:
+
+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.
+
+The `0.2.19` snapshot therefore becomes the comparison point for the next platform-generation work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.2.17",
+  "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.",
   "type": "module",
   "license": "MIT",
@@ -42,7 +42,7 @@
     },
     "./config": {
       "types": "./packages/client/src/config.ts",
-      "default": "./packages/client/src/config.ts"
+      "default": "./packages/client/src/config.mjs"
     },
     "./validation": {
       "types": "./packages/client/src/validation.ts",
@@ -60,7 +60,7 @@
     "./auth": {
       "types": "./packages/client/src/auth.ts",
       "browser": "./packages/client/src/server-only.browser.mjs",
-      "default": "./packages/client/src/auth.ts"
+      "default": "./packages/client/src/auth.mjs"
     },
     "./jobs": {
       "types": "./packages/client/src/jobs.ts",
@@ -97,10 +97,15 @@
       "browser": "./packages/client/src/server-only.browser.mjs",
       "default": "./packages/client/src/observability.mjs"
     },
+    "./deployment": {
+      "types": "./packages/client/src/deployment.ts",
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/deployment.mjs"
+    },
     "./server": {
       "types": "./packages/client/src/server.ts",
       "browser": "./packages/client/src/server-only.browser.mjs",
-      "default": "./packages/client/src/server.ts"
+      "default": "./packages/client/src/server.mjs"
     },
     "./server-only": {
       "types": "./packages/client/src/server-only.d.ts",
@@ -109,7 +114,7 @@
     },
     "./middleware": {
       "types": "./packages/server/src/middleware.ts",
-      "default": "./packages/server/src/middleware.ts"
+      "default": "./packages/server/src/middleware.mjs"
     },
     "./package.json": "./package.json"
   },

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

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