@chidchanun/bcp 0.2.18 → 0.3.0

package/docs/api-reference.md

@@ -37,15 +37,15 @@ createCacheMetrics
 
 Public contracts include `CacheAdapter`, `CacheLockAdapter`, `CacheStore`, cache statistics/options and Redis command-client adapter types.
 
-Related guides: [Caching](caching.md), [Cache Platform v2](cache-platform-v2.md).
+Related guides: [Caching](caching.md), [Cache Platform v2](cache-platform-v2.md), [Application Platform](application-platform.md).
 
 ## `bcp/config`
 
 Typed BCP configuration, environment-schema validation and diagnostics APIs.
 
-Prepared npm packages resolve the production runtime to compiled `config.mjs` in `0.2.18+`.
+Prepared npm packages resolve the production runtime to compiled `config.mjs`.
 
-Related guides: [Configuration](configuration.md), [Environment Validation](environment-validation.md), [Deployment Platform v2](deployment-platform-v2.md).
+Related guides: [Configuration](configuration.md), [Environment Validation](environment-validation.md), [Application Platform](application-platform.md).
 
 ## `bcp/validation`
 
@@ -61,7 +61,7 @@ Server-only provider-neutral SQL APIs for MySQL, PostgreSQL and SQLite.
 
 Core capabilities include query/execute, transactions, lifecycle and migrations.
 
-Related guides: [Database](database.md), [Database Migrations](database-migrations.md), [Transactional Outbox & Events](transactional-outbox-events.md).
+Related guides: [Database](database.md), [Database Migrations](database-migrations.md), [Transactional Outbox & Events](transactional-outbox-events.md), [Application Platform](application-platform.md).
 
 ## `bcp/auth`
 
@@ -69,7 +69,7 @@ Server-only Authentication Platform v2 and Authorization & Security v2 APIs.
 
 Capabilities include JWT-cookie sessions, optional server-side session stores, revocation, logout-all, idle timeout, role/permission guards, policies, same-origin protection and auth/guest guards.
 
-Prepared npm packages resolve the runtime to compiled `auth.mjs` in `0.2.18+`.
+Prepared npm packages resolve the runtime to compiled `auth.mjs`.
 
 ## `bcp/jobs`
 
@@ -211,11 +211,11 @@ Active trace context uses Node `AsyncLocalStorage`. W3C `traceparent`, optional
 
 Prepared npm packages expose compiled `observability.mjs`.
 
-Related guides: [Observability Platform v2](observability.md), [Observability Platform v3](observability-v3.md).
+Related guides: [Observability Platform v2](observability.md), [Observability Platform v3](observability-v3.md), [Application Platform](application-platform.md).
 
 ## `bcp/deployment`
 
-Server-only Deployment Platform v2 lifecycle APIs introduced in `0.2.18`.
+Server-only Deployment Platform v2 lifecycle APIs.
 
 Primary functions:
 
@@ -348,13 +348,105 @@ const unregister =
 
 Prepared npm packages expose compiled `deployment.mjs`.
 
-Related guides: [Deployment Platform v2](deployment-platform-v2.md), [Application Packaging](application-packaging.md), [Production Hardening](production-hardening.md), [Observability Platform v3](observability-v3.md).
+Related guides: [Deployment Platform v2](deployment-platform-v2.md), [Application Packaging](application-packaging.md), [Production Hardening](production-hardening.md), [Observability Platform v3](observability-v3.md), [Application Platform](application-platform.md).
+
+## `bcp/application`
+
+Server-only BCP Application Platform composition APIs introduced in `0.3.0`.
+
+Primary exports:
+
+```text
+defineApp
+createApp
+ApplicationLifecycleError
+```
+
+Important public types:
+
+```text
+Application
+ApplicationState
+ApplicationDefinition
+ApplicationContext
+ApplicationConfigSchema
+ApplicationConfigParser
+```
+
+Create an application:
+
+```ts
+import {
+    createApp,
+} from "bcp/application";
+
+const app =
+    createApp({
+        name: "orders-api",
+        version: "1.0.0",
+    });
+```
+
+The application exposes the existing Plugin and Deployment platform objects:
+
+```text
+app.services
+app.hooks
+app.plugins
+app.deployment
+```
+
+Register a shared service before startup:
+
+```ts
+app.provide(
+    "database",
+    database
+);
+```
+
+Register an infrastructure resource:
+
+```ts
+app.addResource({
+    name: "database",
+    start: () => database.connect(),
+    ready: () => database.ready,
+    stop: () => database.close(),
+});
+```
+
+Application lifecycle order:
+
+```text
+application.setup
+plugins start
+resources start
+application.start
+```
+
+Shutdown runs the inverse dependency order:
+
+```text
+application.stop
+resources stop in reverse order
+plugins stop/dispose
+application.dispose
+```
+
+`readiness()` and `diagnostics()` delegate to the integrated Deployment Platform. `installSignalHandlers()` and `registerShutdownHook()` expose the same graceful-shutdown capabilities through the application root.
+
+The runtime is terminal after `stop()`/`shutdown()`/`close()` and rejects service/plugin/resource registration after startup begins.
+
+Prepared npm packages expose compiled `application.mjs`, and the entrypoint is blocked from browser/page dependency graphs.
+
+Related guides: [Application Platform](application-platform.md), [Migrating to 0.3.0](migration-0.3.md), [Plugin & Module Platform](plugin-module-platform.md), [Deployment Platform v2](deployment-platform-v2.md).
 
 ## `bcp/server`
 
 Server request/runtime APIs including request context, cookies, CSRF/same-origin protection, logging, graceful shutdown hooks, multipart upload helpers, storage adapters, file delivery, response helpers and low-level session primitives.
 
-Prepared npm packages resolve this runtime to compiled `server.mjs` in `0.2.18+`.
+Prepared npm packages resolve this runtime to compiled `server.mjs`.
 
 ## `bcp/server-only`
 
@@ -368,11 +460,11 @@ import "bcp/server-only";
 
 Middleware System v2 request/response pipeline types and helpers.
 
-Prepared npm packages resolve this runtime to compiled `middleware.mjs` in `0.2.18+`.
+Prepared npm packages resolve this runtime to compiled `middleware.mjs`.
 
 ## Prepared server runtime map
 
-For `0.2.18`, the prepared npm package uses compiled ESM runtime defaults for:
+For `0.3.0`, the prepared npm package uses compiled ESM runtime defaults for:
 
 ```text
 bcp/cache          -> cache.mjs
@@ -387,6 +479,7 @@ bcp/testing        -> testing.mjs
 bcp/plugins        -> plugins.mjs
 bcp/observability  -> observability.mjs
 bcp/deployment     -> deployment.mjs
+bcp/application    -> application.mjs
 bcp/server         -> server.mjs
 bcp/middleware     -> middleware.mjs
 ```
@@ -397,4 +490,4 @@ Types remain sourced from the TypeScript public entrypoint files.
 
 Only entrypoints listed in both `docs/platform-manifest.json` and `docs/api-manifest.json` are part of the documented platform surface.
 
-Files under internal `packages/*` paths are implementation details unless re-exported through a documented public package entrypoint.
+The reviewed `docs/api-freeze-snapshot.json` records the current package/CLI/API baseline. Files under internal `packages/*` paths remain implementation details unless re-exported through a documented public package entrypoint.

package/docs/application-platform.md

@@ -0,0 +1,378 @@
+# BCP Application Platform
+
+BCP Framework `0.3.0` adds a framework-level application runtime that composes the infrastructure platforms introduced throughout `0.2.x` without replacing their individual APIs.
+
+> **Release state:** unreleased development target until the complete RC workflow passes, the `v0.3.0` tag is created and npm publication succeeds.
+
+## Public entrypoint
+
+```ts
+import {
+    createApp,
+    defineApp,
+} from "bcp/application";
+```
+
+`bcp/application` is server-only and is blocked from browser/page dependency graphs.
+
+## Why an application runtime
+
+Before `0.3.0`, applications could use BCP databases, jobs, workflows, events, realtime, plugins, cache, observability and deployment independently. That remains supported.
+
+The Application Platform adds one composition root for applications that want those systems to share lifecycle and services:
+
+```text
+BCP Application
+    |
+    +-- typed application config
+    +-- shared service registry
+    +-- plugin/modules host
+    +-- infrastructure resources
+    +-- deployment metadata/readiness/diagnostics
+    +-- graceful shutdown
+    |
+    +-- database
+    +-- cache / Redis
+    +-- jobs / scheduler
+    +-- workflow
+    +-- events / outbox
+    +-- realtime
+    +-- observability
+```
+
+The application runtime does not create hidden database/job/cache implementations. Applications continue constructing the provider/runtime objects they need and register them with the composition root.
+
+## Basic application
+
+```ts
+import {
+    createApp,
+} from "bcp/application";
+
+export const app =
+    createApp({
+        name: "orders-api",
+        version: "1.0.0",
+    });
+
+await app.start();
+```
+
+Shutdown:
+
+```ts
+await app.stop();
+```
+
+`shutdown()` and `close()` are aliases for the same terminal application shutdown operation.
+
+## Typed application config
+
+```ts
+const app =
+    createApp<{
+        port: number;
+    }>({
+        name: "orders-api",
+        config: {
+            port: process.env.PORT,
+        },
+        schema: {
+            parse(value) {
+                const raw = value as {
+                    port?: string;
+                };
+
+                return {
+                    port:
+                        Number(
+                            raw.port ?? 3000
+                        ),
+                };
+            },
+        },
+    });
+```
+
+The schema may be an object with `parse()` or a parser function.
+
+## Shared services
+
+The application service registry is the same registry used by BCP plugins.
+
+Register before startup:
+
+```ts
+app.provide(
+    "database",
+    database
+);
+
+app.provide(
+    "cache",
+    cache
+);
+```
+
+Consume from application hooks:
+
+```ts
+const app =
+    createApp({
+        name: "orders-api",
+
+        start(context) {
+            const database =
+                context.services.get(
+                    "database"
+                );
+        },
+    });
+```
+
+Plugins receive the same registry through their normal `PluginContext`.
+
+## Plugins and modules
+
+Existing `bcp/plugins` definitions plug directly into the application runtime:
+
+```ts
+import {
+    definePlugin,
+} from "bcp/plugins";
+import {
+    createApp,
+} from "bcp/application";
+
+const mailPlugin =
+    definePlugin({
+        name: "mail",
+
+        setup(context) {
+            context.services.provide(
+                "mail",
+                mailer
+            );
+        },
+    });
+
+const app =
+    createApp({
+        name: "orders-api",
+        plugins: [
+            mailPlugin,
+        ],
+    });
+```
+
+Existing `defineModule()` plugin modules can be passed through `modules` without conversion.
+
+Before startup, applications may also register extensions fluently:
+
+```ts
+app.use(mailPlugin);
+```
+
+## Infrastructure resources
+
+Register lifecycle resources using the existing Deployment Platform resource contract:
+
+```ts
+const app =
+    createApp({
+        name: "orders-api",
+        resources: [
+            {
+                name: "database",
+
+                async start() {
+                    await database.connect();
+                },
+
+                ready() {
+                    return database.ready;
+                },
+
+                async stop() {
+                    await database.close();
+                },
+            },
+        ],
+    });
+```
+
+Or before `start()`:
+
+```ts
+app.addResource({
+    name: "workers",
+
+    start() {
+        worker = jobs.startWorker();
+    },
+
+    stop() {
+        return worker.stop();
+    },
+});
+```
+
+## Lifecycle order
+
+Application startup has one deterministic order:
+
+```text
+application.setup()
+        |
+        v
+plugin setup/start
+        |
+        v
+resource 1 start
+resource 2 start
+...
+        |
+        v
+application.start()
+        |
+        v
+state = ready
+```
+
+Shutdown reverses the dependency order:
+
+```text
+application.stop()
+        |
+        v
+resource N stop
+...
+resource 1 stop
+        |
+        v
+plugin stop/dispose
+        |
+        v
+application.dispose()
+```
+
+This allows application logic and workers to stop before their shared database/cache/Redis dependencies disappear.
+
+Startup failures use Deployment Platform rollback. Already-started resources are stopped in reverse order and application/plugin disposal still runs.
+
+## Setup versus start
+
+`setup()` runs before the deployment resource graph starts. It is useful for service registration and in-process configuration:
+
+```ts
+createApp({
+    name: "orders-api",
+
+    setup(context) {
+        context.services.provide(
+            "feature-flags",
+            flags
+        );
+    },
+});
+```
+
+`start()` runs after plugins and infrastructure resources have started:
+
+```ts
+createApp({
+    name: "orders-api",
+
+    start(context) {
+        const database =
+            context.services.get(
+                "database"
+            );
+
+        // Application-level startup after infrastructure is available.
+    },
+});
+```
+
+## Readiness and diagnostics
+
+Application readiness delegates to the Deployment Platform:
+
+```ts
+const report =
+    await app.readiness();
+```
+
+The report includes the internal plugin host, registered resources and the application lifecycle resource.
+
+Diagnostics:
+
+```ts
+const diagnostics =
+    await app.diagnostics();
+```
+
+Application diagnostics include deployment identity plus lifecycle information for every registered resource.
+
+## Signals and framework shutdown hooks
+
+If this process owns termination signals:
+
+```ts
+const removeSignals =
+    app.installSignalHandlers();
+```
+
+The default deployment signals remain `SIGTERM` and `SIGINT`.
+
+To participate in the existing BCP production shutdown registry:
+
+```ts
+const unregister =
+    app.registerShutdownHook();
+```
+
+## Application state
+
+The public state model is:
+
+```text
+created
+starting
+ready
+stopping
+stopped
+failed
+```
+
+Startup and shutdown are idempotent for concurrent/repeated calls while the application remains in the corresponding active/terminal lifecycle.
+
+A stopped application is terminal and cannot be started again. Create a new application runtime for a new process lifecycle.
+
+## Mutation boundary
+
+Plugins, services and deployment resources must be registered before `start()`.
+
+The following are intentionally rejected after startup begins:
+
+```ts
+app.use(...)
+app.provide(...)
+app.addResource(...)
+```
+
+This keeps the production lifecycle graph deterministic.
+
+## Relationship to 0.2.19 API freeze
+
+`0.2.19` froze the `0.2.x` package/API baseline. `0.3.0` intentionally establishes the next baseline by adding one public server-only entrypoint:
+
+```text
+bcp/application
+```
+
+Existing `0.2.19` public entrypoints remain available. `0.3.0` does not intentionally remove them.
+
+## Next platform work
+
+The next planned milestone is `0.3.1 — Dependency Injection & Service Container`, which can build typed service tokens, scopes and testing overrides on top of the shared service composition introduced here.

package/docs/docs-web-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.2.18",
+  "versionTarget": "0.3.0",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -58,8 +58,9 @@
     {
       "id": "runtime",
       "title": "Runtime & Infrastructure",
-      "description": "Middleware, jobs, scheduling, workflows, event delivery, realtime channels, observability, deployment lifecycle, distributed caching, security and production hardening.",
+      "description": "Application composition, middleware, jobs, scheduling, workflows, event delivery, realtime channels, observability, deployment lifecycle, distributed caching, security and production hardening.",
       "pages": [
+        { "route": "/docs/application-platform", "source": "application-platform.md", "title": "Application Platform" },
         { "route": "/docs/middleware", "source": "middleware.md", "title": "Middleware" },
         { "route": "/docs/hydration", "source": "hydration.md", "title": "Hydration" },
         { "route": "/docs/development-logging", "source": "development-logging.md", "title": "Logging" },
@@ -102,10 +103,12 @@
     {
       "id": "platform-compatibility",
       "title": "Platform & Compatibility",
-      "description": "Supported platform contracts, documentation integration and migration guidance.",
+      "description": "Supported platform contracts, API baselines, documentation integration and migration guidance.",
       "pages": [
         { "route": "/docs/platform-contract", "source": "platform-contract.md", "title": "Framework Platform Contract" },
+        { "route": "/docs/stability-api-freeze", "source": "stability-api-freeze.md", "title": "0.2 Stability & API Freeze" },
         { "route": "/docs/documentation-platform", "source": "documentation-platform.md", "title": "Documentation Platform" },
+        { "route": "/docs/migration-0.3", "source": "migration-0.3.md", "title": "Migrating to 0.3.0" },
         { "route": "/docs/migration-0.2", "source": "migration-0.2.md", "title": "Migrating to 0.2.x" }
       ]
     },
@@ -119,7 +122,9 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.18", "source": "releases/0.2.18.md", "version": "0.2.18", "state": "unreleased" },
+    { "route": "/releases/0.3.0", "source": "releases/0.3.0.md", "version": "0.3.0", "state": "unreleased" },
+    { "route": "/releases/0.2.19", "source": "releases/0.2.19.md", "version": "0.2.19" },
+    { "route": "/releases/0.2.18", "source": "releases/0.2.18.md", "version": "0.2.18" },
     { "route": "/releases/0.2.17", "source": "releases/0.2.17.md", "version": "0.2.17" },
     { "route": "/releases/0.2.16", "source": "releases/0.2.16.md", "version": "0.2.16" },
     { "route": "/releases/0.2.15", "source": "releases/0.2.15.md", "version": "0.2.15" },