@chidchanun/bcp 0.2.16 → 0.2.17

package/docs/api-reference.md

@@ -1,14 +1,14 @@
 # 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.
+Common exports include `Form`, `Link`, `createIsland`, `navigate`, `notFound` and loader/action/guard hooks.
 
 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).
 
@@ -26,70 +26,37 @@ Related guide: [Hydration](hydration.md).
 
 ## `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:
+Legacy APIs:
 
-```ts
-import {
-    cache,
-    clearCache,
-    dedupe,
-    getCacheStats,
-    revalidatePath,
-    revalidateTag,
-} from "bcp/cache";
+```text
+cache
+dedupe
+clearCache
+getCacheStats
+revalidateTag
+revalidatePath
 ```
 
-Cache Platform v2 adds:
+Cache Platform v2 APIs:
 
-```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
+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.
+Public contracts include `CacheAdapter`, `CacheLockAdapter`, `CacheStore`, cache statistics/options and Redis command-client adapter types.
 
-`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`.
-
-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), [Observability Platform v3](observability-v3.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).
 
@@ -107,323 +74,300 @@ 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, migration stores and migration execution.
 
-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), [Testing Platform](testing-platform.md), [Observability Platform v3](observability-v3.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).
+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).
 
 ## `bcp/jobs`
 
-Server-only Background Jobs, Job Scheduling and Durable Jobs 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.
+Server-only background jobs, scheduling and durable job APIs.
 
-Scheduling APIs include `createJobScheduler()`, `createMemoryJobScheduleStore()`, `nextCronTime()` and `nextScheduleTime()`.
+Core queue APIs include:
 
-Durable Redis-compatible APIs added in `0.2.10` include `createRedisJobQueueAdapter()` and `createRedisJobScheduleStore()`.
+```text
+createJobQueue
+createMemoryJobQueueAdapter
+createRedisJobQueueAdapter
+createJobScheduler
+createMemoryJobScheduleStore
+createRedisJobScheduleStore
+nextCronTime
+nextScheduleTime
+```
 
-BCP does not install a Redis library and does not create the connection. Applications own authentication, TLS, Cluster/Sentinel configuration and connection shutdown.
+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.
 
-The processing model is at-least-once. Handlers that perform non-idempotent external side effects should use application-level idempotency protection.
+Processing remains at-least-once; non-repeatable external side effects should use application-level idempotency.
 
-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).
+Related guides: [Background Jobs](background-jobs.md), [Job Scheduling](job-scheduling.md), [Durable Jobs](durable-jobs.md), [Observability Platform v3](observability-v3.md).
 
 ## `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`.
+Workflow controls include `start`, `run`, `get`, `list`, `resume`, `retry`, `cancel`, `compensate` and `close`.
 
-`WorkflowStore.claim()` / `release()` form the run-level lease boundary for multi-instance stores.
+Capabilities include sequential/parallel steps, per-step retry, persisted delays, compensation, run leases and optional execution through `bcp/jobs`.
 
-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).
+Related guides: [Workflow Orchestration](workflow-orchestration.md), [Durable Jobs](durable-jobs.md), [Observability Platform v3](observability-v3.md).
 
 ## `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.
+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.
 
-`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).
+Related guides: [Transactional Outbox & Events](transactional-outbox-events.md), [Database](database.md), [Durable Jobs](durable-jobs.md), [Observability Platform v3](observability-v3.md).
 
 ## `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 intentionally does not install a WebSocket server library. Applications adapt the selected provider through `RealtimeSocket`.
 
-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).
+Related guides: [Realtime Platform](realtime-platform.md), [Testing Platform](testing-platform.md), [Observability Platform v3](observability-v3.md).
 
 ## `bcp/testing`
 
-Server-only Testing Platform APIs added in `0.2.14`.
-
-```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";
-```
+Server-only framework-native testing utilities. BCP does not require Jest or Vitest.
 
-### 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.
+```text
+createTestApp
+createRouteTestHandler
+expectResponse
+createTestAuthSession
+withTestTransaction
+runTestMiddleware
+runTestPageLoader
+runTestPageGuards
+runTestPageAction
+createFakeClock
+createSequenceIdFactory
+createJobTestHarness
+createWorkflowTestHarness
+createOutboxTestHarness
+createRealtimeTestSocket
+createRealtimeTestHarness
+readSseEvents
+```
 
-### API route module testing
+Related guide: [Testing Platform](testing-platform.md).
 
-`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.
+Related guides: [Plugin & Module Platform](plugin-module-platform.md), [Configuration](configuration.md), [Observability Platform v3](observability-v3.md).
 
-`runTestPageAction()` invokes the production `executePageActionFunction()` path, including action-name/method validation, guard data, FormData and Response/data handling.
+## `bcp/observability`
 
-`createTestFormData()` creates a FormData object from string/Blob fields and supports repeated values.
+Server-only metrics, health and tracing APIs.
 
-### Response assertions
+### Observability Platform v2
 
-`expectResponse()` exposes lightweight runner-neutral assertions:
+Existing APIs remain supported:
 
 ```text
-status()
-header()
-text()
-json()
-jsonMatches()
+createMetricsRegistry
+createMetricsResponse
+createRequestMetricsMiddleware
+createHealthRegistry
 ```
 
-BCP does not require Jest/Vitest assertion APIs.
+The metrics registry provides counters, gauges, histograms and Prometheus exposition. Health checks provide readiness/liveness-style reports with timeout support.
 
-### Auth testing
+### Observability Platform v3 — 0.2.17
 
-`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`.
+Tracing APIs:
 
-This allows route/auth tests to use a real BCP session cookie instead of introducing a test-only identity header.
-
-### Database rollback testing
-
-`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.
+```ts
+import {
+    createCompositeTraceSpanExporter,
+    createMemoryTraceSpanExporter,
+    createRequestTracingMiddleware,
+    createTraceCarrier,
+    createTraceMetricsExporter,
+    createTracer,
+    currentTraceContext,
+    extractTraceCarrier,
+    extractTraceHeaders,
+    formatTraceparent,
+    getTraceLogFields,
+    injectTraceHeaders,
+    parseTraceparent,
+    runWithTraceCarrier,
+    runWithTraceContext,
+} from "bcp/observability";
+```
 
-Application callback errors remain unchanged and are not swallowed.
+Important public types:
 
-### Middleware testing
+```text
+Tracer
+TracerOptions
+TraceContext
+TraceCarrier
+TraceSpan
+TraceSpanRecord
+TraceSpanEvent
+TraceSpanExporter
+TraceSpanKind
+TraceSpanStatus
+TraceAttributes
+TraceIdFactory
+StartTraceSpanOptions
+RequestTracingOptions
+TraceMetricsOptions
+```
 
-`runTestMiddleware()` invokes the actual Middleware System v2 onion pipeline through `executeMiddlewarePipeline()` and supports a custom downstream Request handler.
+`createTracer()` creates root/child spans. Active context is stored with Node `AsyncLocalStorage`, allowing nested awaited operations to inherit the current `traceId`, `correlationId` and parent span.
 
-### Deterministic utilities
+```ts
+await tracer.withSpan(
+    "order.checkout",
+    async () => {
+        await tracer.withSpan(
+            "database.insert",
+            createOrder,
+            {
+                kind: "client",
+            }
+        );
+    }
+);
+```
 
-`createFakeClock()` exposes `now()`, `set()`, `advance()` and `reset()` for time-sensitive queues/workflows/schedulers.
+Supported span kinds:
 
-`createSequenceIdFactory()` creates deterministic IDs for stable assertions.
+```text
+internal
+server
+client
+producer
+consumer
+```
 
-### Infrastructure harnesses
+Failed `withSpan()` callbacks are marked `error`, receive an `exception` event and rethrow the original application error.
 
-`createJobTestHarness()` drains currently eligible work through the real `BackgroundJobQueue.processNext()` API and exposes record/count assertions.
+### W3C propagation
 
-`createWorkflowTestHarness()` can start/run workflows until terminal or waiting state and optionally force persisted delays to resume.
+`formatTraceparent()` / `parseTraceparent()` support W3C version `00` trace headers.
 
-`createOutboxTestHarness()` dispatches through the actual `OutboxDispatcher` and exposes event/state/statistics helpers.
+```ts
+const headers =
+    new Headers();
 
-`createRealtimeTestSocket()` implements the `RealtimeSocket` adapter contract entirely in memory. `createRealtimeTestHarness()` connects that socket to a real `RealtimeHub` and can assert server-sent channel events.
+injectTraceHeaders(
+    headers
+);
+```
 
-`readSseEvents()` reads event-stream Responses, ignores comment/retry frames and JSON-decodes `data:` payloads when possible.
+`extractTraceHeaders()` reads `traceparent`, optional `tracestate` and `x-correlation-id`.
 
-### Runner neutrality and boundary
+### Middleware tracing
 
-`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.
+```ts
+export const middleware =
+    createRequestTracingMiddleware(
+        tracer
+    );
+```
 
-The package is server-only; the client boundary validator rejects `bcp/testing` from pages/client islands.
+The middleware continues a valid incoming trace and adds active trace/correlation headers to the response.
 
-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).
+### Non-HTTP propagation
 
-## `bcp/plugins`
+```ts
+const trace =
+    createTraceCarrier();
+```
 
-Server-only Plugin & Module Platform APIs added in `0.2.15`.
+Transport that carrier through job payloads, workflow input, event metadata or realtime payloads, then restore it with:
 
 ```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";
+runWithTraceCarrier(
+    payload.trace,
+    handler
+);
 ```
 
-`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.
-
-`defineModule()` groups reusable plugin definitions while preserving one global host dependency graph.
+BCP does not automatically mutate persisted job/workflow/event schemas in `0.2.17`.
 
-Plugin configuration can be parsed with a schema/parser during setup. Values from `PluginHostOptions.configs` override plugin-local defaults before parsing.
+### Exporters and metrics
 
-`PluginServiceRegistry` provides shared string/Symbol-keyed services. `PluginHookBus` provides awaited, in-process extension hooks in registration order.
+`TraceSpanExporter` is provider-neutral. BCP supplies an in-memory exporter and a composite exporter.
 
-Missing dependencies and dependency cycles throw `PluginDependencyError`. Setup/start failures surface `PluginLifecycleError`; startup failures roll back plugins that already started in the current transition.
+`createTraceMetricsExporter()` converts completed spans into the existing metrics registry:
 
-`host.plugin()` and `host.plugins()` expose inspectable lifecycle records.
+```text
+bcp_trace_spans_total
+bcp_trace_span_duration_seconds
+```
 
-`bcp/plugins` is server-only and is rejected from page/client bundles.
+Default labels are `kind` and `status`. Span names are opt-in to reduce accidental high cardinality.
 
-Related guides: [Plugin & Module Platform](plugin-module-platform.md), [Configuration](configuration.md), [Testing Platform](testing-platform.md), [Observability Platform v2](observability.md).
+`getTraceLogFields()` returns:
 
-## `bcp/observability`
+```text
+traceId
+spanId
+correlationId
+```
 
-Server-only Observability Platform v2 APIs for process-local counters, gauges, histograms, Prometheus exposition, request metrics middleware and health/readiness checks.
+for structured log enrichment.
 
-`Cache Platform v2` can connect to this registry through `createCacheMetrics()` from `bcp/cache`.
+Prepared npm packages expose compiled `observability.mjs` as the runtime default for `bcp/observability`.
 
-Related guides: [Observability Platform v2](observability.md), [Logging](development-logging.md), [Cache Platform v2](cache-platform-v2.md).
+Related guides: [Observability Platform v2](observability.md), [Observability Platform v3](observability-v3.md), [Logging](development-logging.md), [Cache Platform v2](cache-platform-v2.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).
+Related guides: [Server Request APIs](server-request-apis.md), [Authorization & Security v2](authorization-security.md), [File Upload](file-upload.md), [Storage](storage.md), [Production Hardening](production-hardening.md), [Observability Platform v3](observability-v3.md).
 
 ## `bcp/server-only`
 
@@ -433,16 +377,14 @@ 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.
 
-Related guides: [Middleware](middleware.md), [Testing Platform](testing-platform.md).
+Related guides: [Middleware](middleware.md), [Testing Platform](testing-platform.md), [Observability Platform v3](observability-v3.md).
 
 ## 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.