@chidchanun/bcp 0.2.17 → 0.2.19

package/docs/README.md

@@ -2,7 +2,7 @@
 
 The `docs/` directory is the documentation source of truth for BCP Framework and is organized for **`bcp-docs-web`**.
 
-> **Documentation target:** BCP Framework `0.2.17 — Observability Platform v3`
+> **Documentation target:** BCP Framework `0.2.19 — Stability & API Freeze`
 >
 > **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
 
@@ -17,6 +17,9 @@ docs/platform-manifest.json
 
 docs/api-manifest.json
   -> public package entrypoints, source ownership and guide mapping
+
+docs/api-freeze-snapshot.json
+  -> frozen public/CLI/prepared-package compatibility contract
 ```
 
 Framework source and tests remain authoritative for runtime behavior.
@@ -43,64 +46,42 @@ Framework source and tests remain authoritative for runtime behavior.
 | `0.2.15` | Plugin & Module Platform |
 | `0.2.16` | Cache Platform v2 |
 | `0.2.17` | Observability Platform v3 |
+| `0.2.18` | Deployment Platform v2 |
+| `0.2.19` | Stability & API Freeze |
 
-## 0.2.17 — Observability Platform v3
-
-`0.2.17` extends the existing server-only `bcp/observability` public entrypoint while preserving Observability Platform v2 metrics and health APIs.
-
-Primary tracing APIs:
+## 0.2.19 — Stability & API Freeze
 
-```ts
-import {
-    createCompositeTraceSpanExporter,
-    createMemoryTraceSpanExporter,
-    createRequestTracingMiddleware,
-    createTraceCarrier,
-    createTraceMetricsExporter,
-    createTracer,
-    getTraceLogFields,
-    runWithTraceCarrier,
-} from "bcp/observability";
-```
+`0.2.19` freezes the supported `0.2.x` public package and CLI contract without adding a new application subsystem.
 
-Runtime model:
+Primary stability commands:
 
-```text
-Incoming HTTP
-    |
-    v
-request tracing middleware
-    |
-    +-- AsyncLocalStorage trace context
-    +-- W3C traceparent
-    +-- correlationId
-    |
-    +-- database/cache child spans
-    +-- trace carrier -> jobs/workflows/events/realtime
-    |
-    v
-TraceSpanExporter
-    +-- memory exporter
-    +-- trace metrics exporter
-    +-- application/vendor exporter
+```bash
+npm run api:check
+npm run api:snapshot
+npm run release:readiness
+npm run release:readiness:report
 ```
 
-A root trace owns a stable `traceId` and `correlationId`. Nested spans inherit that identity and receive their own `spanId` / `parentSpanId` relationship.
+The freeze snapshot captures:
 
-`createTraceCarrier()` and `runWithTraceCarrier()` provide explicit provider-neutral propagation through non-HTTP transports without changing persisted job/workflow/outbox schemas.
+- public `bcp/*` entrypoints;
+- CLI command names;
+- prepared npm export targets;
+- browser poison boundaries;
+- API source/environment ownership;
+- compatibility with `0.2.18`.
 
-Prepared npm packages compile `bcp/observability` to `observability.mjs` for standalone Node runtime use.
+`npm run api:check` prepares the exact npm staging package and rejects drift from the committed snapshot.
 
 New/updated sources:
 
 | Source | Purpose |
 | --- | --- |
-| `observability-v3.md` | Tracing, propagation, W3C trace context, exporters, correlation and trace metrics |
-| `api-reference.md` | `bcp/observability` tracing APIs |
-| `platform-manifest.json` | Observability v3 capability flags |
-| `api-manifest.json` | Updated observability source/guide ownership |
-| `docs-web-manifest.json` | Observability v3 docs navigation and `0.2.17` release route |
-| `releases/0.2.17.md` | Observability Platform v3 release notes |
+| `stability-api-freeze.md` | Freeze policy, compatibility checks and release readiness |
+| `api-freeze-snapshot.json` | Frozen public/CLI/package contract |
+| `platform-manifest.json` | Stability capability flags and `0.2.18` compatibility baseline |
+| `docs-web-manifest.json` | Stability guide and `0.2.19` release route |
+| `releases/0.2.19.md` | Stability & API Freeze release notes |
 
 ## Update rule
 
@@ -112,17 +93,17 @@ When framework behavior or public surface changes:
 4. Update `platform-manifest.json` for runtime/public-entrypoint/capability changes.
 5. Update `api-manifest.json` for public API ownership/guide changes.
 6. Update `docs-web-manifest.json` for website route/navigation changes.
-7. Update `docs/releases/<version>.md`.
-8. Change release state only after the release workflow reaches that state.
+7. Review `api-freeze-snapshot.json`; do not regenerate it casually during `0.2.19`.
+8. Update `docs/releases/<version>.md`.
+9. Change release state only after the release workflow reaches that state.
 
 ## Important docs-web routes
 
 | Website route | Markdown source |
 | --- | --- |
-| `/docs/authentication` | `authentication.md` |
-| `/docs/observability` | `observability.md` |
+| `/docs/stability-api-freeze` | `stability-api-freeze.md` |
 | `/docs/observability-v3` | `observability-v3.md` |
-| `/docs/background-jobs` | `background-jobs.md` |
+| `/docs/deployment-platform-v2` | `deployment-platform-v2.md` |
 | `/docs/durable-jobs` | `durable-jobs.md` |
 | `/docs/workflow-orchestration` | `workflow-orchestration.md` |
 | `/docs/transactional-outbox-events` | `transactional-outbox-events.md` |
@@ -131,7 +112,7 @@ When framework behavior or public surface changes:
 | `/docs/plugin-module-platform` | `plugin-module-platform.md` |
 | `/docs/cache-platform-v2` | `cache-platform-v2.md` |
 | `/docs/api-reference` | `api-reference.md` |
-| `/releases/0.2.17` | `releases/0.2.17.md` |
+| `/releases/0.2.19` | `releases/0.2.19.md` |
 
 Every route/source pair is validated by unit tests.
 
@@ -153,16 +134,17 @@ bcp/realtime
 bcp/testing
 bcp/plugins
 bcp/observability
+bcp/deployment
 bcp/server
 bcp/server-only
 bcp/middleware
 ```
 
-The API-manifest entrypoint set must match the platform public-entrypoint set exactly.
+The API-manifest entrypoint set, platform public-entrypoint set and freeze snapshot must remain aligned.
 
 ## Release validation
 
-Before publishing `0.2.17`:
+Before publishing `0.2.19`:
 
 ```bash
 npm run typecheck
@@ -170,9 +152,11 @@ 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
 ```
 
-Observability Platform v3 validation covers root/child spans, async trace context, W3C traceparent parsing/injection, correlation IDs, request middleware, trace carriers, error spans, metrics integration, compiled `observability.mjs` package execution and docs/platform/API parity.
+Stability validation covers public/CLI/export parity, prepared-package browser/runtime boundaries, release metadata and deployment lifecycle idempotency in addition to all existing subsystem suites.
 
 The final release tag must point to the exact commit that passed the complete RC sequence.

package/docs/api-freeze-snapshot.json

@@ -0,0 +1,232 @@
+{
+  "schemaVersion": 1,
+  "framework": "bcp",
+  "version": "0.2.19",
+  "baselineVersion": "0.2.18",
+  "state": "frozen",
+  "intentionalBreakingChanges": false,
+  "publicEntrypoints": [
+    "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"
+  ],
+  "cliCommands": [
+    "dev",
+    "build",
+    "package",
+    "start",
+    "routes",
+    "update",
+    "db",
+    "generate",
+    "config",
+    "doctor",
+    "inspect",
+    "help",
+    "version"
+  ],
+  "packageExports": {
+    ".": {
+      "default": "./packages/client/src/index.tsx",
+      "types": "./packages/client/src/index.tsx"
+    },
+    "./auth": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/auth.mjs",
+      "types": "./packages/client/src/auth.ts"
+    },
+    "./cache": {
+      "default": "./packages/client/src/cache.mjs",
+      "types": "./packages/client/src/cache.ts"
+    },
+    "./config": {
+      "default": "./packages/client/src/config.mjs",
+      "types": "./packages/client/src/config.ts"
+    },
+    "./database": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/database.mjs",
+      "types": "./packages/client/src/database.ts"
+    },
+    "./deployment": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/deployment.mjs",
+      "types": "./packages/client/src/deployment.ts"
+    },
+    "./error": {
+      "default": "./packages/client/src/http-error.ts",
+      "types": "./packages/client/src/http-error.ts"
+    },
+    "./events": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/events.mjs",
+      "types": "./packages/client/src/events.ts"
+    },
+    "./island": {
+      "default": "./packages/client/src/islands.tsx",
+      "types": "./packages/client/src/islands.tsx"
+    },
+    "./jobs": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/jobs.mjs",
+      "types": "./packages/client/src/jobs.ts"
+    },
+    "./middleware": {
+      "default": "./packages/server/src/middleware.mjs",
+      "types": "./packages/server/src/middleware.ts"
+    },
+    "./observability": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/observability.mjs",
+      "types": "./packages/client/src/observability.ts"
+    },
+    "./package.json": "./package.json",
+    "./plugins": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/plugins.mjs",
+      "types": "./packages/client/src/plugins.ts"
+    },
+    "./realtime": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/realtime.mjs",
+      "types": "./packages/client/src/realtime.ts"
+    },
+    "./server": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/server.mjs",
+      "types": "./packages/client/src/server.ts"
+    },
+    "./server-only": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/server-only.mjs",
+      "types": "./packages/client/src/server-only.d.ts"
+    },
+    "./testing": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/testing.mjs",
+      "types": "./packages/client/src/testing.ts"
+    },
+    "./validation": {
+      "default": "./packages/client/src/validation.ts",
+      "types": "./packages/client/src/validation.ts"
+    },
+    "./workflow": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/workflow.mjs",
+      "types": "./packages/client/src/workflow.ts"
+    }
+  },
+  "apiOwnership": [
+    {
+      "package": "bcp",
+      "source": "packages/client/src/index.tsx",
+      "environment": "universal"
+    },
+    {
+      "package": "bcp/island",
+      "source": "packages/client/src/islands.tsx",
+      "environment": "universal"
+    },
+    {
+      "package": "bcp/cache",
+      "source": "packages/client/src/cache.ts",
+      "environment": "server-preferred"
+    },
+    {
+      "package": "bcp/config",
+      "source": "packages/client/src/config.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/validation",
+      "source": "packages/client/src/validation.ts",
+      "environment": "universal"
+    },
+    {
+      "package": "bcp/error",
+      "source": "packages/client/src/http-error.ts",
+      "environment": "universal"
+    },
+    {
+      "package": "bcp/database",
+      "source": "packages/client/src/database.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/auth",
+      "source": "packages/client/src/auth.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/jobs",
+      "source": "packages/client/src/jobs.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/workflow",
+      "source": "packages/client/src/workflow.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/events",
+      "source": "packages/client/src/events.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/realtime",
+      "source": "packages/client/src/realtime.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/testing",
+      "source": "packages/client/src/testing.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/plugins",
+      "source": "packages/client/src/plugins.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/observability",
+      "source": "packages/client/src/observability.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/deployment",
+      "source": "packages/client/src/deployment.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/server",
+      "source": "packages/client/src/server.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/server-only",
+      "source": "packages/client/src/server-only.mjs",
+      "environment": "server-marker"
+    },
+    {
+      "package": "bcp/middleware",
+      "source": "packages/server/src/middleware.ts",
+      "environment": "server"
+    }
+  ]
+}

package/docs/api-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.17",
+  "version": "0.2.19",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [
@@ -34,8 +34,8 @@
       "source": "packages/client/src/config.ts",
       "environment": "server",
       "route": "/docs/api-reference#bcp-config",
-      "summary": "Typed BCP configuration, environment-schema validation and configuration diagnostics APIs.",
-      "guides": ["/docs/configuration", "/docs/environment-validation"]
+      "summary": "Typed BCP configuration, environment-schema validation and configuration diagnostics APIs with a compiled production runtime.",
+      "guides": ["/docs/configuration", "/docs/environment-validation", "/docs/deployment-platform-v2"]
     },
     {
       "package": "bcp/validation",
@@ -59,15 +59,15 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-database",
       "summary": "Provider-neutral MySQL, PostgreSQL and SQLite query, transaction, lifecycle and migration primitives.",
-      "guides": ["/docs/database", "/docs/database-migrations", "/docs/transactional-outbox-events", "/docs/testing-platform", "/docs/observability-v3"]
+      "guides": ["/docs/database", "/docs/database-migrations", "/docs/transactional-outbox-events", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2"]
     },
     {
       "package": "bcp/auth",
       "source": "packages/client/src/auth.ts",
       "environment": "server",
       "route": "/docs/api-reference#bcp-auth",
-      "summary": "Authentication Platform v2 plus permission checks, authorization policies and auth/guest/role/permission route guards.",
-      "guides": ["/docs/authentication", "/docs/auth-session-store", "/docs/auth-route-guards", "/docs/authorization-security", "/docs/session-auth", "/docs/testing-platform"]
+      "summary": "Authentication Platform v2 plus permission checks, authorization policies and auth/guest/role/permission route guards, published with a compiled Node runtime.",
+      "guides": ["/docs/authentication", "/docs/auth-session-store", "/docs/auth-route-guards", "/docs/authorization-security", "/docs/session-auth", "/docs/testing-platform", "/docs/deployment-platform-v2"]
     },
     {
       "package": "bcp/jobs",
@@ -75,7 +75,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-jobs",
       "summary": "Background queues and schedules with visibility leases, heartbeats, stale recovery, DLQ maintenance and Redis-compatible durable adapters.",
-      "guides": ["/docs/background-jobs", "/docs/job-scheduling", "/docs/durable-jobs", "/docs/transactional-outbox-events", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability-v3"]
+      "guides": ["/docs/background-jobs", "/docs/job-scheduling", "/docs/durable-jobs", "/docs/transactional-outbox-events", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2"]
     },
     {
       "package": "bcp/workflow",
@@ -83,7 +83,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-workflow",
       "summary": "Persistent workflow orchestration with sequential and parallel steps, retries, delays, compensation, run leases and optional durable queue execution.",
-      "guides": ["/docs/workflow-orchestration", "/docs/durable-jobs", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability-v3"]
+      "guides": ["/docs/workflow-orchestration", "/docs/durable-jobs", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2"]
     },
     {
       "package": "bcp/events",
@@ -91,7 +91,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-events",
       "summary": "Transactional outbox and event delivery APIs with SQL persistence, dispatcher leases, retries, stale recovery, queue handoff and in-process event bus delivery.",
-      "guides": ["/docs/transactional-outbox-events", "/docs/database", "/docs/durable-jobs", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability-v3"]
+      "guides": ["/docs/transactional-outbox-events", "/docs/database", "/docs/durable-jobs", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2"]
     },
     {
       "package": "bcp/realtime",
@@ -99,7 +99,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-realtime",
       "summary": "Realtime channels, cross-hub broker delivery, presence, channel authorization, WebSocket adapter integration, heartbeat handling and built-in Server-Sent Events responses.",
-      "guides": ["/docs/realtime-platform", "/docs/authentication", "/docs/testing-platform", "/docs/observability-v3"]
+      "guides": ["/docs/realtime-platform", "/docs/authentication", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2"]
     },
     {
       "package": "bcp/testing",
@@ -115,7 +115,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-plugins",
       "summary": "Plugin and module composition with dependency ordering, lifecycle hooks, typed config parsing, shared services and asynchronous extension hooks.",
-      "guides": ["/docs/plugin-module-platform", "/docs/configuration", "/docs/testing-platform", "/docs/observability-v3"]
+      "guides": ["/docs/plugin-module-platform", "/docs/configuration", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2"]
     },
     {
       "package": "bcp/observability",
@@ -123,15 +123,23 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-observability",
       "summary": "Metrics, Prometheus output, health checks and Observability Platform v3 distributed tracing with W3C trace context, correlation IDs, request tracing, span exporters and trace-to-metrics integration.",
-      "guides": ["/docs/observability", "/docs/observability-v3", "/docs/development-logging", "/docs/cache-platform-v2"]
+      "guides": ["/docs/observability", "/docs/observability-v3", "/docs/development-logging", "/docs/cache-platform-v2", "/docs/deployment-platform-v2"]
+    },
+    {
+      "package": "bcp/deployment",
+      "source": "packages/client/src/deployment.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-deployment",
+      "summary": "Deployment Platform v2 runtime lifecycle with resource startup/shutdown ordering, readiness, diagnostics, deployment metadata, signal handling and framework shutdown-hook integration.",
+      "guides": ["/docs/deployment-platform-v2", "/docs/application-packaging", "/docs/production-hardening", "/docs/observability-v3"]
     },
     {
       "package": "bcp/server",
       "source": "packages/client/src/server.ts",
       "environment": "server",
       "route": "/docs/api-reference#bcp-server",
-      "summary": "Request context, cookies, CSRF/same-origin protection, logging, production hardening, upload, storage, response and session APIs.",
-      "guides": ["/docs/server-request-apis", "/docs/authorization-security", "/docs/file-upload", "/docs/storage", "/docs/storage-ecosystem", "/docs/production-hardening", "/docs/testing-platform", "/docs/observability-v3"]
+      "summary": "Request context, cookies, CSRF/same-origin protection, logging, production hardening, upload, storage, response and session APIs, published with a compiled Node runtime.",
+      "guides": ["/docs/server-request-apis", "/docs/authorization-security", "/docs/file-upload", "/docs/storage", "/docs/storage-ecosystem", "/docs/production-hardening", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2"]
     },
     {
       "package": "bcp/server-only",
@@ -146,8 +154,8 @@
       "source": "packages/server/src/middleware.ts",
       "environment": "server",
       "route": "/docs/api-reference#bcp-middleware",
-      "summary": "Middleware System v2 request/response pipeline types and helpers.",
-      "guides": ["/docs/middleware", "/docs/testing-platform", "/docs/observability-v3"]
+      "summary": "Middleware System v2 request/response pipeline types and helpers, published with a compiled Node runtime.",
+      "guides": ["/docs/middleware", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2"]
     }
   ]
 }