@chidchanun/bcp 0.2.19 → 0.3.1

package/docs/platform-contract.md

@@ -1,8 +1,8 @@
 # Framework Platform Contract
 
-BCP Framework `0.2.x` exposes an explicit, machine-readable application-platform contract rather than relying on private repository structure.
+BCP Framework exposes an explicit, machine-readable application-platform contract rather than relying on private repository structure.
 
-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.
+The current development baseline is **`0.3.1 — Dependency Injection & Service Container`** and remains unreleased until the complete RC sequence passes, the exact release commit is tagged and npm publication completes.
 
 ## Sources of truth
 
@@ -14,17 +14,17 @@ docs/api-manifest.json
   -> public package source/environment/documentation ownership
 
 docs/api-freeze-snapshot.json
-  -> frozen 0.2.19 CLI and prepared npm export contract
+  -> reviewed CLI and prepared npm export baseline
 
 docs/docs-web-manifest.json
   -> documentation routes and release navigation
 ```
 
-Framework source and tests remain authoritative for runtime behavior. The manifests make that supported surface testable during release validation.
+Framework source and tests remain authoritative for runtime behavior.
 
-## Frozen public entrypoints
+## Public entrypoints
 
-The `0.2.19` baseline supports:
+The `0.3.1` baseline supports:
 
 ```text
 bcp
@@ -43,18 +43,61 @@ bcp/testing
 bcp/plugins
 bcp/observability
 bcp/deployment
+bcp/container
+bcp/application
 bcp/server
 bcp/server-only
 bcp/middleware
 ```
 
-Application code should use these entrypoints instead of private `packages/*` implementation paths.
+`bcp/container` is the new entrypoint relative to `0.3.0`. No `0.3.0` public entrypoint is intentionally removed.
 
-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.
+The prepared package also exposes `./package.json`; it is part of package-export snapshot validation but is not an application API module.
+
+## Application and DI baseline
+
+`bcp/application` remains the composition root while `bcp/container` adds typed dependency injection:
+
+```text
+ServiceToken<T>
+value providers
+factory providers
+class providers
+singleton/scoped/transient lifetimes
+child/request scopes
+test overrides
+dependency graph diagnostics
+circular dependency detection
+reverse disposal
+```
+
+Application integration exposes:
+
+```text
+app.container
+app.context.container
+app.register(provider)
+app.createScope(options)
+```
+
+The existing Plugin Platform registry remains available through `app.services` / `context.services` for compatibility.
+
+## Lifecycle contract
+
+Application deployment resources start in this order:
+
+```text
+bcp:container
+bcp:plugins
+application resources
+bcp:application
+```
+
+Shutdown reverses that order. This keeps injected dependencies available while workers/resources/plugins stop, then disposes injected services before final application disposal.
 
 ## CLI baseline
 
-The frozen command families are:
+The command families remain:
 
 ```text
 bcp dev
@@ -83,21 +126,25 @@ build target: standalone-node
 package target: standalone-node
 ```
 
-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`.
+Prepared npm packages expose compiled server ESM. `0.3.1` adds:
+
+```text
+bcp/container -> container.mjs
+```
+
+and preserves compiled `application.mjs` from `0.3.0`.
 
 ## Compatibility policy
 
-For `0.2.19`:
+For `0.3.1`:
 
 ```text
-previous baseline: 0.2.18
+previous baseline: 0.3.0
 intentional breaking changes: false
-freeze state: frozen
+baseline: dependency-injection-service-container
 ```
 
-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.
-
-Intentional public-platform changes should normally move to `0.3.0` with explicit compatibility metadata and migration documentation.
+Bug fixes must not silently remove a documented entrypoint or change its prepared package-resolution/browser-boundary contract.
 
 ## API compatibility gate
 
@@ -105,16 +152,14 @@ Intentional public-platform changes should normally move to `0.3.0` with explici
 npm run api:check
 ```
 
-The gate prepares the publish package, regenerates the current contract in memory and compares it to `docs/api-freeze-snapshot.json`.
+The gate prepares the publish package, regenerates the current contract in memory and compares it with `docs/api-freeze-snapshot.json`.
 
-To intentionally regenerate the snapshot:
+Regenerate the snapshot only for an intentional reviewed baseline change:
 
 ```bash
 npm run api:snapshot
 ```
 
-Snapshot changes during `0.2.19` require explicit review; regeneration is not a routine fix for a failing compatibility check.
-
 ## Release readiness
 
 ```bash
@@ -122,11 +167,11 @@ npm run release:readiness
 npm run release:readiness:report
 ```
 
-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`.
+The readiness gate checks package/lock/manifests parity, the `0.3.0` previous baseline, public entrypoint/API snapshot parity, container/application ownership, release docs and DI/Application capability flags.
 
 ## Release validation
 
-Before `0.2.19` is tagged or published:
+Before `0.3.1` is tagged or published:
 
 ```bash
 npm run typecheck
@@ -141,4 +186,4 @@ npm run rc:check
 
 `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).
+See [Dependency Injection & Service Container](service-container.md), [Application Platform](application-platform.md), [Migrating to 0.3.x](migration-0.3.md), and the historical [Stability & API Freeze](stability-api-freeze.md).

package/docs/platform-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.19",
+  "version": "0.3.1",
   "releaseState": "unreleased",
-  "baseline": "stability-api-freeze",
+  "baseline": "dependency-injection-service-container",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -27,6 +27,8 @@
     "bcp/plugins",
     "bcp/observability",
     "bcp/deployment",
+    "bcp/container",
+    "bcp/application",
     "bcp/server",
     "bcp/server-only",
     "bcp/middleware"
@@ -95,6 +97,34 @@
     "compiledAuthRuntime": true,
     "compiledServerRuntime": true,
     "compiledMiddlewareRuntime": true,
+    "applicationPlatform": true,
+    "applicationDefinitions": true,
+    "applicationRuntime": true,
+    "applicationConfigSchemas": true,
+    "applicationServiceRegistry": true,
+    "applicationPluginComposition": true,
+    "applicationModuleComposition": true,
+    "applicationResourceLifecycle": true,
+    "applicationReadiness": true,
+    "applicationDiagnostics": true,
+    "applicationLifecycleRollback": true,
+    "applicationLifecycleIdempotency": true,
+    "compiledApplicationRuntime": true,
+    "dependencyInjectionContainer": true,
+    "typedServiceTokens": true,
+    "serviceValueProviders": true,
+    "serviceFactoryProviders": true,
+    "serviceClassProviders": true,
+    "serviceSingletonLifetime": true,
+    "serviceScopedLifetime": true,
+    "serviceTransientLifetime": true,
+    "serviceChildScopes": true,
+    "serviceScopeOverrides": true,
+    "serviceDependencyGraph": true,
+    "serviceCircularDependencyDetection": true,
+    "serviceReverseDisposal": true,
+    "applicationServiceContainer": true,
+    "compiledContainerRuntime": true,
     "stabilityApiFreeze": true,
     "apiFreezeSnapshot": true,
     "apiCompatibilityGate": true,
@@ -230,9 +260,9 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.18",
+    "previousBaseline": "0.3.0",
     "intentionalBreakingChangesFromPreviousBaseline": false,
-    "migrationGuide": "migration-0.2.md"
+    "migrationGuide": "migration-0.3.md"
   },
   "documentation": {
     "navigationManifest": "docs-web-manifest.json",
@@ -243,6 +273,8 @@
     "documentationPlatform": "documentation-platform.md",
     "apiReference": "api-reference.md",
     "stabilityApiFreeze": "stability-api-freeze.md",
+    "applicationPlatform": "application-platform.md",
+    "serviceContainer": "service-container.md",
     "environmentValidation": "environment-validation.md",
     "applicationPackaging": "application-packaging.md",
     "authentication": "authentication.md",
@@ -260,7 +292,7 @@
     "testingPlatform": "testing-platform.md",
     "pluginModulePlatform": "plugin-module-platform.md",
     "cachePlatformV2": "cache-platform-v2.md",
-    "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.19.md"
+    "migrationGuide": "migration-0.3.md",
+    "releaseNotes": "releases/0.3.1.md"
   }
 }

package/docs/releases/0.3.0.md

@@ -0,0 +1,129 @@
+# BCP Framework 0.3.0 — Application Platform
+
+`0.3.0` establishes the first BCP Application Platform baseline on top of the infrastructure and API freeze completed in `0.2.x`.
+
+> **Release state:** unreleased until the complete RC gate passes, `v0.3.0` is tagged and both npm packages are published successfully.
+
+## Highlights
+
+- Adds the server-only `bcp/application` public entrypoint.
+- Adds `defineApp()` for validated application definitions.
+- Adds `createApp()` for a unified application composition root.
+- Reuses the existing Plugin Platform service registry and hook bus.
+- Reuses existing plugin/module definitions without conversion.
+- Reuses Deployment Platform resources, readiness, diagnostics, signal handling and shutdown hooks.
+- Adds typed application-level config parsing.
+- Adds deterministic application lifecycle ordering.
+- Adds startup rollback and terminal cleanup through the deployment resource graph.
+- Adds concurrent/repeated start and shutdown idempotency coverage.
+- Publishes `application.mjs` as a compiled production runtime.
+- Adds prepared-package smoke coverage for the new entrypoint and lifecycle.
+
+## Public API
+
+```ts
+import {
+    ApplicationLifecycleError,
+    createApp,
+    defineApp,
+} from "bcp/application";
+```
+
+Key types:
+
+```text
+Application
+ApplicationConfigParser
+ApplicationConfigSchema
+ApplicationContext
+ApplicationDefinition
+ApplicationState
+```
+
+## Application composition
+
+```ts
+const app =
+    createApp({
+        name: "orders-api",
+        version: "1.0.0",
+        plugins: [
+            authPlugin,
+            jobsPlugin,
+        ],
+        resources: [
+            databaseResource,
+            workerResource,
+        ],
+    });
+
+await app.start();
+```
+
+The application exposes the shared platform objects directly:
+
+```text
+app.services
+app.hooks
+app.plugins
+app.deployment
+```
+
+Existing provider-native database, cache, job, workflow, event and realtime instances can be stored in the service registry or wrapped in deployment resources as appropriate.
+
+## Lifecycle
+
+Startup:
+
+```text
+application.setup
+plugin setup/start
+resources start in registration order
+application.start
+```
+
+Shutdown:
+
+```text
+application.stop
+resources stop in reverse order
+plugin stop/dispose
+application.dispose
+```
+
+Startup failures roll back already-started resources in reverse order.
+
+## Compatibility
+
+The `0.2.19` Stability & API Freeze release is the compatibility baseline for `0.3.0`.
+
+`0.3.0` intentionally adds:
+
+```text
+bcp/application
+```
+
+No existing `0.2.19` public entrypoint is intentionally removed.
+
+The API snapshot/compatibility tooling is updated to establish the reviewed `0.3.0` package baseline after the new entrypoint is added.
+
+## Validation
+
+Before tagging:
+
+```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 publish until these commands pass on the exact final release commit.
+
+## Next milestone
+
+`0.3.1 — Dependency Injection & Service Container` is planned to add typed service tokens, singleton/scoped/transient lifetimes, request scopes, factories and testing overrides on top of the shared Application Platform service composition model.

package/docs/releases/0.3.1.md

@@ -0,0 +1,116 @@
+# BCP Framework 0.3.1 — Dependency Injection & Service Container
+
+**State:** unreleased
+
+`0.3.1` adds typed dependency injection to the Application Platform without removing the Plugin Platform service registry introduced in `0.2.x`.
+
+## Highlights
+
+- new server-only `bcp/container` public entrypoint;
+- typed `ServiceToken<T>` values;
+- value, factory and class providers;
+- singleton, scoped and transient lifetimes;
+- child/request scopes;
+- scope-local provider overrides for tests;
+- dependency graph diagnostics;
+- circular dependency detection;
+- reverse-order disposal and aggregate disposal errors;
+- concurrent/repeated disposal idempotency;
+- `createApp()` integration through `providers`, `container`, `register()` and `createScope()`;
+- compiled `container.mjs` production runtime;
+- server-only browser poison boundary;
+- unit and prepared-package smoke coverage.
+
+## Public APIs
+
+```text
+createServiceToken
+createServiceContainer
+provideValue
+provideFactory
+provideClass
+ServiceNotFoundError
+ServiceResolutionError
+ServiceDisposalError
+```
+
+Important types:
+
+```text
+ServiceToken<T>
+ServiceProvider<T>
+ServiceLifetime
+ServiceFactoryContext
+ServiceContainer
+ServiceScope
+ServiceScopeOptions
+ServiceGraphNode
+```
+
+## Application Platform changes
+
+`ApplicationDefinition` now accepts:
+
+```ts
+providers?: readonly ServiceProvider<any>[];
+```
+
+`Application` and `ApplicationContext` now expose:
+
+```text
+container
+```
+
+Applications can also call:
+
+```text
+app.register(provider)
+app.createScope(options)
+```
+
+The existing `app.services` / `context.services` Plugin Platform registry remains supported for compatibility.
+
+## Lifecycle
+
+The application deployment chain now starts the DI container resource before the plugin host and application infrastructure. Shutdown reverses the chain so disposable injected services remain alive until application/plugin/resource shutdown completes.
+
+## Compatibility
+
+Previous baseline:
+
+```text
+0.3.0
+```
+
+Intentional breaking changes:
+
+```text
+false
+```
+
+`0.3.1` is additive. Existing `0.3.0` applications do not need to adopt dependency injection immediately.
+
+## Packaging
+
+Prepared npm packages expose:
+
+```text
+bcp/container -> packages/client/src/container.mjs
+```
+
+with TypeScript declarations sourced from `packages/client/src/container.ts` and browser builds redirected to the server-only poison module.
+
+## Validation
+
+Before publication run the complete framework RC sequence on the final 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
+```