@chidchanun/bcp 0.2.15 → 0.2.17

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.15 — Plugin & Module Platform`
+> **Documentation target:** BCP Framework `0.2.17 — Observability Platform v3`
 >
 > **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
 
@@ -41,55 +41,66 @@ Framework source and tests remain authoritative for runtime behavior.
 | `0.2.13` | Realtime Platform |
 | `0.2.14` | Testing Platform |
 | `0.2.15` | Plugin & Module Platform |
+| `0.2.16` | Cache Platform v2 |
+| `0.2.17` | Observability Platform v3 |
 
-## 0.2.15 — Plugin & Module Platform
+## 0.2.17 — Observability Platform v3
 
-`0.2.15` adds the server-only `bcp/plugins` public entrypoint.
+`0.2.17` extends the existing server-only `bcp/observability` public entrypoint while preserving Observability Platform v2 metrics and health APIs.
 
-Primary APIs:
+Primary tracing APIs:
 
 ```ts
 import {
-    createPluginHookBus,
-    createPluginHost,
-    createPluginServiceRegistry,
-    defineModule,
-    definePlugin,
-} from "bcp/plugins";
+    createCompositeTraceSpanExporter,
+    createMemoryTraceSpanExporter,
+    createRequestTracingMiddleware,
+    createTraceCarrier,
+    createTraceMetricsExporter,
+    createTracer,
+    getTraceLogFields,
+    runWithTraceCarrier,
+} from "bcp/observability";
 ```
 
 Runtime model:
 
 ```text
-Plugin Host
-   |
-   +-- dependency graph
-   |      -> required / optional dependencies
-   |
-   +-- lifecycle
-   |      -> setup -> start -> stop -> dispose
-   |
-   +-- service registry
-   |      -> typed shared application services
-   |
-   +-- async hook bus
-          -> in-process extension points
+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
 ```
 
-Startup follows topological dependency order. Stop/dispose runs in reverse order. A failed startup rolls back plugins that already started.
+A root trace owns a stable `traceId` and `correlationId`. Nested spans inherit that identity and receive their own `spanId` / `parentSpanId` relationship.
 
-Modules are named bundles of plugins; they do not create a separate lifecycle graph.
+`createTraceCarrier()` and `runWithTraceCarrier()` provide explicit provider-neutral propagation through non-HTTP transports without changing persisted job/workflow/outbox schemas.
+
+Prepared npm packages compile `bcp/observability` to `observability.mjs` for standalone Node runtime use.
 
 New/updated sources:
 
 | Source | Purpose |
 | --- | --- |
-| `plugin-module-platform.md` | Plugin definitions, modules, dependency order, lifecycle, config, services and hooks |
-| `api-reference.md` | `bcp/plugins` public APIs |
-| `platform-manifest.json` | Plugin capability flags and public entrypoint |
-| `api-manifest.json` | `bcp/plugins` source/guide ownership |
-| `docs-web-manifest.json` | Plugin docs navigation and `0.2.15` release route |
-| `releases/0.2.15.md` | Plugin & Module Platform release notes |
+| `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 |
 
 ## Update rule
 
@@ -110,6 +121,7 @@ When framework behavior or public surface changes:
 | --- | --- |
 | `/docs/authentication` | `authentication.md` |
 | `/docs/observability` | `observability.md` |
+| `/docs/observability-v3` | `observability-v3.md` |
 | `/docs/background-jobs` | `background-jobs.md` |
 | `/docs/durable-jobs` | `durable-jobs.md` |
 | `/docs/workflow-orchestration` | `workflow-orchestration.md` |
@@ -117,8 +129,9 @@ When framework behavior or public surface changes:
 | `/docs/realtime-platform` | `realtime-platform.md` |
 | `/docs/testing-platform` | `testing-platform.md` |
 | `/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.15` | `releases/0.2.15.md` |
+| `/releases/0.2.17` | `releases/0.2.17.md` |
 
 Every route/source pair is validated by unit tests.
 
@@ -149,7 +162,7 @@ The API-manifest entrypoint set must match the platform public-entrypoint set ex
 
 ## Release validation
 
-Before publishing `0.2.15`:
+Before publishing `0.2.17`:
 
 ```bash
 npm run typecheck
@@ -160,6 +173,6 @@ npm run test:package
 npm run rc:check
 ```
 
-Plugin Platform validation covers dependency ordering, missing/cyclic dependencies, module composition, typed config parsing, service sharing, async hooks, reverse shutdown, startup rollback, server-only boundaries, compiled `plugins.mjs` package execution and docs/platform/API parity.
+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.
 
 The final release tag must point to the exact commit that passed the complete RC sequence.

package/docs/api-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [
@@ -26,8 +26,8 @@
       "source": "packages/client/src/cache.ts",
       "environment": "server-preferred",
       "route": "/docs/api-reference#bcp-cache",
-      "summary": "Cache, deduplication, statistics and path/tag revalidation primitives.",
-      "guides": ["/docs/caching"]
+      "summary": "Backward-compatible request/data caching plus Cache Platform v2 adapters, Redis-compatible distributed cache and locks, stampede protection, TTL/tag/path invalidation and metrics integration.",
+      "guides": ["/docs/caching", "/docs/cache-platform-v2", "/docs/observability-v3"]
     },
     {
       "package": "bcp/config",
@@ -59,7 +59,7 @@
       "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"]
+      "guides": ["/docs/database", "/docs/database-migrations", "/docs/transactional-outbox-events", "/docs/testing-platform", "/docs/observability-v3"]
     },
     {
       "package": "bcp/auth",
@@ -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"]
+      "guides": ["/docs/background-jobs", "/docs/job-scheduling", "/docs/durable-jobs", "/docs/transactional-outbox-events", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability-v3"]
     },
     {
       "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"]
+      "guides": ["/docs/workflow-orchestration", "/docs/durable-jobs", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability-v3"]
     },
     {
       "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"]
+      "guides": ["/docs/transactional-outbox-events", "/docs/database", "/docs/durable-jobs", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability-v3"]
     },
     {
       "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"]
+      "guides": ["/docs/realtime-platform", "/docs/authentication", "/docs/testing-platform", "/docs/observability-v3"]
     },
     {
       "package": "bcp/testing",
@@ -107,7 +107,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-testing",
       "summary": "Framework-native testing utilities for Request/Response handlers, signed auth sessions, rollback transactions, page/server execution, middleware, jobs, workflows, outbox delivery, realtime sockets and SSE.",
-      "guides": ["/docs/testing-platform", "/docs/authentication", "/docs/database", "/docs/durable-jobs", "/docs/workflow-orchestration", "/docs/transactional-outbox-events", "/docs/realtime-platform"]
+      "guides": ["/docs/testing-platform", "/docs/authentication", "/docs/database", "/docs/durable-jobs", "/docs/workflow-orchestration", "/docs/transactional-outbox-events", "/docs/realtime-platform", "/docs/observability-v3"]
     },
     {
       "package": "bcp/plugins",
@@ -115,15 +115,15 @@
       "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"]
+      "guides": ["/docs/plugin-module-platform", "/docs/configuration", "/docs/testing-platform", "/docs/observability-v3"]
     },
     {
       "package": "bcp/observability",
       "source": "packages/client/src/observability.ts",
       "environment": "server",
       "route": "/docs/api-reference#bcp-observability",
-      "summary": "In-process metrics, Prometheus exposition, request metrics middleware and health/readiness checks.",
-      "guides": ["/docs/observability", "/docs/development-logging"]
+      "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"]
     },
     {
       "package": "bcp/server",
@@ -131,7 +131,7 @@
       "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"]
+      "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"]
     },
     {
       "package": "bcp/server-only",
@@ -147,7 +147,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-middleware",
       "summary": "Middleware System v2 request/response pipeline types and helpers.",
-      "guides": ["/docs/middleware", "/docs/testing-platform"]
+      "guides": ["/docs/middleware", "/docs/testing-platform", "/docs/observability-v3"]
     }
   ]
 }