@chidchanun/bcp 0.2.16 → 0.2.18

package/docs/api-reference.md

@@ -1,429 +1,360 @@
 # API Reference
 
-BCP Framework exposes a small set of supported package entrypoints. Import application APIs through these entrypoints instead of private files under `packages/`.
+BCP Framework exposes supported package entrypoints through the `bcp` package. Application code should import these public entrypoints instead of private implementation files under `packages/`.
 
 The machine-readable source for this page is `docs/api-manifest.json`.
 
 ## `bcp`
 
-Universal React application APIs.
+Universal React application APIs for routing, navigation, layouts, metadata, loaders, route guards, form actions and islands.
 
-Common exports include `Form`, `Link`, `createIsland`, `navigate`, `notFound`, loader/action/guard hooks and router/navigation APIs.
-
-Related guides: [Routing](routing.md), [Server Data Loaders](server-data-loaders.md), [Route Guards](route-guards.md), [Form Actions](form-actions.md), [Testing Platform](testing-platform.md).
+Common exports include `Form`, `Link`, `createIsland`, `navigate`, `notFound` and loader/action/guard hooks.
 
 ## `bcp/island`
 
-Partial-hydration island APIs.
-
-```ts
-import {
-    createIsland,
-} from "bcp/island";
-```
-
-Related guide: [Hydration](hydration.md).
+Partial-hydration island APIs including `createIsland` and island loading strategy types.
 
 ## `bcp/cache`
 
-Caching APIs include the original process-local request/data cache plus Cache Platform v2 provider contracts for shared production caches.
+Backward-compatible request/data caching plus Cache Platform v2 shared-store APIs.
 
-Legacy-compatible exports remain:
+Important exports:
 
-```ts
-import {
-    cache,
-    clearCache,
-    dedupe,
-    getCacheStats,
-    revalidatePath,
-    revalidateTag,
-} from "bcp/cache";
-```
-
-Cache Platform v2 adds:
-
-```ts
-import {
-    createCacheMetrics,
-    createCacheStore,
-    createMemoryCacheAdapter,
-    createMemoryCacheLockAdapter,
-    createRedisCacheAdapter,
-    createRedisCacheLockAdapter,
-    type CacheAdapter,
-    type CacheAdapterEntry,
-    type CacheAdapterSetOptions,
-    type CacheGetOrSetOptions,
-    type CacheLockAdapter,
-    type CacheMetricsRegistryLike,
-    type CacheMetricsSink,
-    type CacheStore,
-    type CacheStoreEvent,
-    type CacheStoreOptions,
-    type CacheStoreSetOptions,
-    type CacheStoreStats,
-    type MemoryCacheAdapter,
-    type MemoryCacheLockAdapter,
-    type RedisCacheAdapter,
-    type RedisCacheAdapterOptions,
-    type RedisCacheCommandClient,
-    type RedisCacheLockAdapter,
-    type RedisCacheLockAdapterOptions,
-} from "bcp/cache";
+```text
+cache
+dedupe
+clearCache
+getCacheStats
+revalidateTag
+revalidatePath
+createCacheStore
+createMemoryCacheAdapter
+createMemoryCacheLockAdapter
+createRedisCacheAdapter
+createRedisCacheLockAdapter
+createCacheMetrics
 ```
 
-`createCacheStore()` exposes async `get()`, `set()`, `delete()`, `clear()`, `revalidateTag()`, `revalidatePath()`, `getOrSet()`, `stats()` and `close()` operations.
-
-`getOrSet()` always provides local singleflight deduplication. When a `CacheLockAdapter` is supplied, cache fills can also coordinate across multiple application instances with owner-scoped leases, optional renewal and configurable contention timeout behavior.
-
-`createRedisCacheAdapter()` and `createRedisCacheLockAdapter()` use a minimal `sendCommand()` client contract. BCP does not install or own a Redis library/connection. The default namespace is `bcp:{cache}` for Redis Cluster hash-slot locality.
-
-Cache Store v2 uses millisecond TTL (`ttlMs`), while the original `cache()` API keeps its existing `revalidate`-seconds contract.
-
-`createCacheMetrics()` adapts cache events to the existing BCP `MetricsRegistry` shape without coupling the cache package directly to a specific exporter.
-
-Prepared npm packages compile the runtime entrypoint to `packages/client/src/cache.mjs`.
+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), [Observability Platform v2](observability.md).
+Related guides: [Caching](caching.md), [Cache Platform v2](cache-platform-v2.md).
 
 ## `bcp/config`
 
-Typed framework configuration, application environment-schema validation and diagnostics APIs.
+Typed BCP configuration, environment-schema validation and diagnostics APIs.
 
-Related guides: [Configuration](configuration.md), [Environment Validation](environment-validation.md).
+Prepared npm packages resolve the production runtime to compiled `config.mjs` in `0.2.18+`.
+
+Related guides: [Configuration](configuration.md), [Environment Validation](environment-validation.md), [Deployment Platform v2](deployment-platform-v2.md).
 
 ## `bcp/validation`
 
 Typed validation primitives, parse helpers and `ValidationError`.
 
-Related guide: [Validation](validation.md).
-
 ## `bcp/error`
 
 Structured HTTP error helpers and response classification.
 
-Related guide: [Error Handling](error-handling.md).
-
 ## `bcp/database`
 
-Server-only Database Platform v2 APIs.
+Server-only provider-neutral SQL APIs for MySQL, PostgreSQL and SQLite.
 
-Built-in SQL providers are MySQL, PostgreSQL and SQLite. `BcpDatabase` instances expose lazy query/execute/transaction operations plus explicit `connect()`, `disconnect()` and backward-compatible `close()` lifecycle methods.
+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), [Testing Platform](testing-platform.md).
+Related guides: [Database](database.md), [Database Migrations](database-migrations.md), [Transactional Outbox & Events](transactional-outbox-events.md).
 
 ## `bcp/auth`
 
-Server-only authentication and authorization APIs.
+Server-only Authentication Platform v2 and Authorization & Security v2 APIs.
 
-The default authentication mode remains stateless signed JWT-cookie authentication. Applications may opt into server-side session stores, revocation, logout-all, idle timeout, role/permission guards and resource-aware authorization policies.
+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.
 
-Related guides: [Authentication](authentication.md), [Auth Session Stores](auth-session-store.md), [Auth Route Guards](auth-route-guards.md), [Authorization & Security v2](authorization-security.md), [JWT Sessions](session-auth.md), [Testing Platform](testing-platform.md).
+Prepared npm packages resolve the runtime to compiled `auth.mjs` in `0.2.18+`.
 
 ## `bcp/jobs`
 
-Server-only Background Jobs, Job Scheduling and Durable Jobs APIs.
+Server-only background jobs, scheduling and durable job APIs.
 
-Core queue APIs include `createJobQueue()`, `createMemoryJobQueueAdapter()`, queue/worker records, retry/backoff, visibility leases, heartbeat renewal, stale recovery, DLQ operations, retention cleanup and queue statistics.
+Important exports:
 
-Scheduling APIs include `createJobScheduler()`, `createMemoryJobScheduleStore()`, `nextCronTime()` and `nextScheduleTime()`.
-
-Durable Redis-compatible APIs added in `0.2.10` include `createRedisJobQueueAdapter()` and `createRedisJobScheduleStore()`.
-
-BCP does not install a Redis library and does not create the connection. Applications own authentication, TLS, Cluster/Sentinel configuration and connection shutdown.
+```text
+createJobQueue
+createMemoryJobQueueAdapter
+createRedisJobQueueAdapter
+createJobScheduler
+createMemoryJobScheduleStore
+createRedisJobScheduleStore
+nextCronTime
+nextScheduleTime
+```
 
-The processing model is at-least-once. Handlers that perform non-idempotent external side effects should use application-level idempotency protection.
+Capabilities include delay, retry/backoff, worker concurrency, cancellation, visibility leases, heartbeat renewal, stale recovery, DLQ/requeue, retention cleanup, queue statistics and recurring interval/UTC cron schedules.
 
-Related guides: [Background Jobs Platform](background-jobs.md), [Job Scheduling Platform](job-scheduling.md), [Durable Jobs Platform](durable-jobs.md), [Transactional Outbox & Events](transactional-outbox-events.md), [Realtime Platform](realtime-platform.md), [Testing Platform](testing-platform.md), [Observability Platform v2](observability.md).
+Processing remains at-least-once; non-repeatable external side effects should use application-level idempotency.
 
 ## `bcp/workflow`
 
-Server-only Workflow Orchestration APIs added in `0.2.11`.
-
-```ts
-import {
-    createMemoryWorkflowStore,
-    createWorkflow,
-} from "bcp/workflow";
-```
-
-`createWorkflow()` defines persistent server-side workflows with sequential steps, parallel groups, per-step retry policies, persisted delays and compensation handlers.
-
-Workflow controls include:
+Server-only Workflow Orchestration APIs.
 
 ```text
-start()
-run()
-get()
-list()
-resume()
-retry()
-cancel()
-compensate()
-close()
+createWorkflow
+createMemoryWorkflowStore
 ```
 
-When an existing `BackgroundJobQueue` is supplied, workflow execution and delay continuation can run through `bcp/jobs`.
-
-`WorkflowStore.claim()` / `release()` form the run-level lease boundary for multi-instance stores.
+Workflow controls include `start`, `run`, `get`, `list`, `resume`, `retry`, `cancel`, `compensate` and `close`.
 
-Related guides: [Workflow Orchestration](workflow-orchestration.md), [Durable Jobs Platform](durable-jobs.md), [Realtime Platform](realtime-platform.md), [Testing Platform](testing-platform.md), [Observability Platform v2](observability.md).
+Capabilities include sequential/parallel steps, per-step retry, persisted delays, compensation, run leases and optional execution through `bcp/jobs`.
 
 ## `bcp/events`
 
-Server-only Transactional Outbox & Events APIs added in `0.2.12`.
+Server-only Transactional Outbox & Events APIs.
 
-```ts
-import {
-    createEventBus,
-    createMemoryOutboxStore,
-    createOutboxDispatcher,
-    createOutboxMigrationSql,
-    createSqlOutboxStore,
-    createTransactionalOutbox,
-} from "bcp/events";
+```text
+createTransactionalOutbox
+createMemoryOutboxStore
+createSqlOutboxStore
+createOutboxMigrationSql
+createOutboxDispatcher
+createEventBus
 ```
 
-`createTransactionalOutbox()` writes an event through the same `TransactionDatabase` used by `db.transaction()`, allowing business rows and outbox rows to commit or roll back together.
-
-`createSqlOutboxStore()` supports MySQL, PostgreSQL and SQLite. `createOutboxMigrationSql()` generates the outbox table/index DDL.
-
-`createOutboxDispatcher()` supports batched claims, leases, stale recovery, retry/backoff, terminal failure, job-queue handoff, custom publishing, local event-bus delivery and runner lifecycle.
-
-Delivery is at-least-once; consumers should use idempotency controls for non-repeatable side effects.
-
-Related guides: [Transactional Outbox & Events](transactional-outbox-events.md), [Database](database.md), [Durable Jobs Platform](durable-jobs.md), [Realtime Platform](realtime-platform.md), [Testing Platform](testing-platform.md), [Observability Platform v2](observability.md).
+SQL outbox storage supports MySQL, PostgreSQL and SQLite. Dispatch supports batched claims, leases, stale recovery, retry/backoff, terminal failure, durable-job handoff and custom publishing.
 
 ## `bcp/realtime`
 
-Server-only Realtime Platform APIs added in `0.2.13`.
+Server-only realtime APIs for channels/rooms, broker delivery, presence, channel authorization, socket adapters, heartbeat and Server-Sent Events.
 
-```ts
-import {
-    createMemoryRealtimeBroker,
-    createMemoryRealtimePresenceStore,
-    createRealtime,
-    createRealtimeSseResponse,
-    type RealtimeAuthenticate,
-    type RealtimeAuthorizeChannel,
-    type RealtimeBroker,
-    type RealtimeBroadcastOptions,
-    type RealtimeConnection,
-    type RealtimeEnvelope,
-    type RealtimeEventContext,
-    type RealtimeEventHandler,
-    type RealtimeHeartbeatOptions,
-    type RealtimeHeartbeatRunner,
-    type RealtimeHub,
-    type RealtimeJoinOptions,
-    type RealtimeOptions,
-    type RealtimePresenceMember,
-    type RealtimePresenceStore,
-    type RealtimeSocket,
-    type RealtimeSseOptions,
-} from "bcp/realtime";
+```text
+createRealtime
+createMemoryRealtimeBroker
+createMemoryRealtimePresenceStore
+createRealtimeSseResponse
 ```
 
-`createRealtime()` creates a server-side hub. Connections can `join()`, `leave()`, `emit()`, `send()`, `touch()` and `disconnect()`.
-
-`RealtimeBroker` is the cross-hub pub/sub boundary and `RealtimePresenceStore` is the channel-presence boundary. Built-in memory implementations are intended for tests/single-process use; shared deployments can supply provider adapters.
-
-`RealtimeOptions.authenticate` can resolve identity from a Request/connection payload, while `authorizeChannel` runs before channel membership is accepted.
-
-BCP does not install a WebSocket provider. `RealtimeSocket` defines the minimal transport surface consumed by `hub.attachSocket()`.
-
-`hub.sse()` and `createRealtimeSseResponse()` expose Web-standard Server-Sent Events responses with abort, filtering, retry hint and keep-alive options.
-
-Realtime delivery is transient. Use database/outbox/jobs/workflows for durable state and refetch durable state/history after reconnect when catch-up is required.
-
-Related guides: [Realtime Platform](realtime-platform.md), [Authentication](authentication.md), [Testing Platform](testing-platform.md), [Observability Platform v2](observability.md).
+BCP intentionally does not install a WebSocket server library. Applications adapt the selected provider through `RealtimeSocket`.
 
 ## `bcp/testing`
 
-Server-only Testing Platform APIs added in `0.2.14`.
+Server-only framework-native testing utilities. BCP does not require Jest or Vitest.
 
-```ts
-import {
-    createFakeClock,
-    createJobTestHarness,
-    createOutboxTestHarness,
-    createRealtimeTestHarness,
-    createRealtimeTestSocket,
-    createRouteTestHandler,
-    createSequenceIdFactory,
-    createTestApp,
-    createTestAuthSession,
-    createTestFormData,
-    createWorkflowTestHarness,
-    expectResponse,
-    readSseEvents,
-    runTestMiddleware,
-    runTestPageAction,
-    runTestPageGuards,
-    runTestPageLoader,
-    withTestTransaction,
-    type CreateTestAuthSessionOptions,
-    type FakeClock,
-    type JobTestHarness,
-    type OutboxTestHarness,
-    type ParsedSseEvent,
-    type RealtimeTestConnection,
-    type RealtimeTestHarness,
-    type RealtimeTestSocket,
-    type TestApp,
-    type TestAppOptions,
-    type TestAuthSession,
-    type TestPageActionOptions,
-    type TestPageContextOptions,
-    type TestPageGuardOptions,
-    type TestRequestHandler,
-    type TestRequestOptions,
-    type TestResponseExpectation,
-    type TestRouteFunction,
-    type TestRouteHandlerOptions,
-    type TestRouteMethod,
-    type TestRouteModule,
-    type TestTransactionDatabase,
-    type WorkflowTestHarness,
-} from "bcp/testing";
-```
-
-### Request application harness
+Important APIs include:
 
-`createTestApp()` runs a Web-standard `Request -> Response` handler with convenience methods for GET/POST/PUT/PATCH/DELETE, JSON bodies, mutable default headers and an in-memory cookie jar that consumes `Set-Cookie` responses.
-
-### API route module testing
+```text
+createTestApp
+createRouteTestHandler
+expectResponse
+createTestAuthSession
+withTestTransaction
+runTestMiddleware
+runTestPageLoader
+runTestPageGuards
+runTestPageAction
+createFakeClock
+createSequenceIdFactory
+createJobTestHarness
+createWorkflowTestHarness
+createOutboxTestHarness
+createRealtimeTestSocket
+createRealtimeTestHarness
+readSseEvents
+```
 
-`createRouteTestHandler()` adapts BCP-style method exports (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`) to a Request handler. Missing methods return 405 with an `Allow` header.
+## `bcp/plugins`
 
-Return values are normalized for tests: Response is preserved, strings become text Responses, null/undefined become 204, and other values become JSON.
+Server-only Plugin & Module Platform APIs.
 
-### Page loader, guard and form action testing
+```text
+definePlugin
+defineModule
+createPluginHost
+createPluginServiceRegistry
+createPluginHookBus
+```
 
-`runTestPageGuards()` executes one or more guards through the production `executePageGuardFunctions()` path. Guard data is chained in order and redirect/other Response short-circuits are preserved.
+Capabilities include required/optional dependency ordering, setup/start/stop/dispose lifecycle, startup rollback, typed configuration parsing, shared services and awaited in-process hooks.
 
-`runTestPageLoader()` invokes the production `executePageLoaderFunction()` path with test params, URL/search params and optional guard data. The returned value is the normal `PageLoaderExecution` contract.
+## `bcp/observability`
 
-`runTestPageAction()` invokes the production `executePageActionFunction()` path, including action-name/method validation, guard data, FormData and Response/data handling.
+Server-only metrics, health and tracing APIs.
 
-`createTestFormData()` creates a FormData object from string/Blob fields and supports repeated values.
+Metrics/health APIs:
 
-### Response assertions
+```text
+createMetricsRegistry
+createMetricsResponse
+createRequestMetricsMiddleware
+createHealthRegistry
+```
 
-`expectResponse()` exposes lightweight runner-neutral assertions:
+Observability Platform v3 tracing APIs:
 
 ```text
-status()
-header()
-text()
-json()
-jsonMatches()
+createTracer
+createRequestTracingMiddleware
+createTraceCarrier
+runWithTraceCarrier
+runWithTraceContext
+currentTraceContext
+injectTraceHeaders
+extractTraceHeaders
+formatTraceparent
+parseTraceparent
+createMemoryTraceSpanExporter
+createCompositeTraceSpanExporter
+createTraceMetricsExporter
+getTraceLogFields
 ```
 
-BCP does not require Jest/Vitest assertion APIs.
+Important tracing contracts include `Tracer`, `TraceContext`, `TraceCarrier`, `TraceSpan`, `TraceSpanRecord`, `TraceSpanExporter`, `TraceSpanKind` and `TraceSpanStatus`.
 
-### Auth testing
+Active trace context uses Node `AsyncLocalStorage`. W3C `traceparent`, optional `tracestate` and `x-correlation-id` can cross HTTP boundaries, while trace carriers can be stored in application-owned job/workflow/event/realtime payload metadata.
 
-`createTestAuthSession()` uses the production `createSessionToken()` implementation, including HS256 signature, issuer/audience and expiration semantics. It can also register the matching server-side record in an `AuthSessionStore`.
+Prepared npm packages expose compiled `observability.mjs`.
 
-This allows route/auth tests to use a real BCP session cookie instead of introducing a test-only identity header.
+Related guides: [Observability Platform v2](observability.md), [Observability Platform v3](observability-v3.md).
 
-### Database rollback testing
+## `bcp/deployment`
 
-`withTestTransaction()` executes a callback in a real BCP database transaction and deliberately rejects the transaction with an internal rollback sentinel after the test callback succeeds. The callback result is returned to the test while the transaction is rolled back.
+Server-only Deployment Platform v2 lifecycle APIs introduced in `0.2.18`.
 
-Application callback errors remain unchanged and are not swallowed.
+Primary functions:
 
-### Middleware testing
-
-`runTestMiddleware()` invokes the actual Middleware System v2 onion pipeline through `executeMiddlewarePipeline()` and supports a custom downstream Request handler.
+```ts
+import {
+    createDeploymentDiagnosticsResponse,
+    createDeploymentReadinessResponse,
+    createDeploymentRuntime,
+} from "bcp/deployment";
+```
 
-### Deterministic utilities
+Important public types:
 
-`createFakeClock()` exposes `now()`, `set()`, `advance()` and `reset()` for time-sensitive queues/workflows/schedulers.
+```text
+DeploymentRuntime
+DeploymentRuntimeOptions
+DeploymentRuntimeState
+DeploymentResource
+DeploymentResourceContext
+DeploymentResourceStatus
+DeploymentReadinessResult
+DeploymentReadinessReport
+DeploymentReadinessItem
+DeploymentDiagnosticsReport
+DeploymentDiagnosticsResource
+DeploymentMetadata
+DeploymentSignalOptions
+DeploymentShutdownOptions
+```
 
-`createSequenceIdFactory()` creates deterministic IDs for stable assertions.
+Create a runtime:
 
-### Infrastructure harnesses
+```ts
+const deployment =
+    createDeploymentRuntime({
+        serviceName: "orders-api",
+        version: "1.0.0",
+    });
+```
 
-`createJobTestHarness()` drains currently eligible work through the real `BackgroundJobQueue.processNext()` API and exposes record/count assertions.
+Register resources:
 
-`createWorkflowTestHarness()` can start/run workflows until terminal or waiting state and optionally force persisted delays to resume.
+```ts
+deployment.addResource({
+    name: "database",
 
-`createOutboxTestHarness()` dispatches through the actual `OutboxDispatcher` and exposes event/state/statistics helpers.
+    async start() {
+        await db.connect();
+    },
 
-`createRealtimeTestSocket()` implements the `RealtimeSocket` adapter contract entirely in memory. `createRealtimeTestHarness()` connects that socket to a real `RealtimeHub` and can assert server-sent channel events.
+    ready() {
+        return true;
+    },
 
-`readSseEvents()` reads event-stream Responses, ignores comment/retry frames and JSON-decodes `data:` payloads when possible.
+    async stop() {
+        await db.close();
+    },
+});
+```
 
-### Runner neutrality and boundary
+Resources start in registration order and stop in reverse order. If startup fails, previously started resources are rolled back in reverse order.
 
-`bcp/testing` has no dependency on Jest or Vitest. BCP's own suite uses Node `node:test`, but the helpers can be called from another runner.
+Runtime states:
 
-The package is server-only; the client boundary validator rejects `bcp/testing` from pages/client islands.
+```text
+idle
+starting
+ready
+draining
+stopped
+failed
+```
 
-Related guides: [Testing Platform](testing-platform.md), [Authentication](authentication.md), [Database](database.md), [Durable Jobs](durable-jobs.md), [Workflow Orchestration](workflow-orchestration.md), [Transactional Outbox & Events](transactional-outbox-events.md), [Realtime Platform](realtime-platform.md).
+Readiness:
 
-## `bcp/plugins`
+```ts
+const report =
+    await deployment.readiness();
+```
 
-Server-only Plugin & Module Platform APIs added in `0.2.15`.
+or:
 
 ```ts
-import {
-    createPluginHookBus,
-    createPluginHost,
-    createPluginServiceRegistry,
-    defineModule,
-    definePlugin,
-    PluginDependencyError,
-    PluginLifecycleError,
-    type PluginConfigParser,
-    type PluginConfigSchema,
-    type PluginContext,
-    type PluginDefinition,
-    type PluginHookBus,
-    type PluginHookHandler,
-    type PluginHost,
-    type PluginHostOptions,
-    type PluginHostView,
-    type PluginModule,
-    type PluginRecord,
-    type PluginServiceKey,
-    type PluginServiceRegistry,
-    type PluginState,
-} from "bcp/plugins";
+return createDeploymentReadinessResponse(
+    deployment
+);
 ```
 
-`createPluginHost()` resolves required and optional plugin dependencies and starts plugins in topological order. `stop()` and `close()` shut them down/dispose them in reverse dependency order.
+The response is `200` when the runtime and all resource checks are ready, otherwise `503`.
 
-`defineModule()` groups reusable plugin definitions while preserving one global host dependency graph.
+Diagnostics:
 
-Plugin configuration can be parsed with a schema/parser during setup. Values from `PluginHostOptions.configs` override plugin-local defaults before parsing.
+```ts
+const report =
+    await deployment.diagnostics();
+```
 
-`PluginServiceRegistry` provides shared string/Symbol-keyed services. `PluginHookBus` provides awaited, in-process extension hooks in registration order.
+or:
 
-Missing dependencies and dependency cycles throw `PluginDependencyError`. Setup/start failures surface `PluginLifecycleError`; startup failures roll back plugins that already started in the current transition.
+```ts
+return createDeploymentDiagnosticsResponse(
+    deployment
+);
+```
 
-`host.plugin()` and `host.plugins()` expose inspectable lifecycle records.
+Metadata includes service/deployment identity, process ID, Node version, platform, architecture and startup time. Optional environment-backed identity fields use:
 
-`bcp/plugins` is server-only and is rejected from page/client bundles.
+```text
+BCP_DEPLOYMENT_ID
+BCP_INSTANCE_ID
+BCP_RELEASE
+NODE_ENV
+```
 
-Related guides: [Plugin & Module Platform](plugin-module-platform.md), [Configuration](configuration.md), [Testing Platform](testing-platform.md), [Observability Platform v2](observability.md).
+Install process signal handlers:
 
-## `bcp/observability`
+```ts
+const remove =
+    deployment.installSignalHandlers();
+```
+
+Defaults are `SIGTERM` and `SIGINT`.
+
+Integrate with the framework shutdown-hook registry:
 
-Server-only Observability Platform v2 APIs for process-local counters, gauges, histograms, Prometheus exposition, request metrics middleware and health/readiness checks.
+```ts
+const unregister =
+    deployment.registerShutdownHook();
+```
 
-`Cache Platform v2` can connect to this registry through `createCacheMetrics()` from `bcp/cache`.
+Prepared npm packages expose compiled `deployment.mjs`.
 
-Related guides: [Observability Platform v2](observability.md), [Logging](development-logging.md), [Cache Platform v2](cache-platform-v2.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).
 
 ## `bcp/server`
 
-Server request/runtime APIs including request context, cookies, CSRF and same-origin protection, logging, graceful shutdown hooks, multipart upload helpers, storage adapters, file delivery, response helpers and low-level session primitives.
+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.
 
-Related guides: [Server Request APIs](server-request-apis.md), [Authorization & Security v2](authorization-security.md), [File Upload](file-upload.md), [Storage](storage.md), [Storage Ecosystem](storage-ecosystem.md), [Production Hardening](production-hardening.md), [Testing Platform](testing-platform.md).
+Prepared npm packages resolve this runtime to compiled `server.mjs` in `0.2.18+`.
 
 ## `bcp/server-only`
 
@@ -433,16 +364,37 @@ Server-only module boundary marker.
 import "bcp/server-only";
 ```
 
-Related guide: [Application Modules](application-modules.md).
-
 ## `bcp/middleware`
 
-Middleware System v2 APIs and types.
+Middleware System v2 request/response pipeline types and helpers.
+
+Prepared npm packages resolve this runtime to compiled `middleware.mjs` in `0.2.18+`.
+
+## Prepared server runtime map
+
+For `0.2.18`, the prepared npm package uses compiled ESM runtime defaults for:
+
+```text
+bcp/cache          -> cache.mjs
+bcp/config         -> config.mjs
+bcp/database       -> database.mjs
+bcp/auth           -> auth.mjs
+bcp/jobs           -> jobs.mjs
+bcp/workflow       -> workflow.mjs
+bcp/events         -> events.mjs
+bcp/realtime       -> realtime.mjs
+bcp/testing        -> testing.mjs
+bcp/plugins        -> plugins.mjs
+bcp/observability  -> observability.mjs
+bcp/deployment     -> deployment.mjs
+bcp/server         -> server.mjs
+bcp/middleware     -> middleware.mjs
+```
 
-Related guides: [Middleware](middleware.md), [Testing Platform](testing-platform.md).
+Types remain sourced from the TypeScript public entrypoint files.
 
 ## Stability
 
-Only package entrypoints listed in both `docs/platform-manifest.json` and `docs/api-manifest.json` are part of the documented platform surface.
+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 framework implementation details unless re-exported through a documented public package entrypoint.
+Files under internal `packages/*` paths are implementation details unless re-exported through a documented public package entrypoint.