@chidchanun/bcp 0.2.16 → 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.16 — Cache Platform v2`
+> **Documentation target:** BCP Framework `0.2.17 — Observability Platform v3`
 >
 > **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
 
@@ -42,60 +42,65 @@ Framework source and tests remain authoritative for runtime behavior.
 | `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.16 — Cache Platform v2
+## 0.2.17 — Observability Platform v3
 
-`0.2.16` extends the existing `bcp/cache` public entrypoint while keeping its original process-local APIs backward compatible.
+`0.2.17` extends the existing server-only `bcp/observability` public entrypoint while preserving Observability Platform v2 metrics and health APIs.
 
-Primary Cache Store v2 APIs:
+Primary tracing APIs:
 
 ```ts
 import {
-    createCacheMetrics,
-    createCacheStore,
-    createMemoryCacheAdapter,
-    createMemoryCacheLockAdapter,
-    createRedisCacheAdapter,
-    createRedisCacheLockAdapter,
-} from "bcp/cache";
+    createCompositeTraceSpanExporter,
+    createMemoryTraceSpanExporter,
+    createRequestTracingMiddleware,
+    createTraceCarrier,
+    createTraceMetricsExporter,
+    createTracer,
+    getTraceLogFields,
+    runWithTraceCarrier,
+} from "bcp/observability";
 ```
 
 Runtime model:
 
 ```text
-Application
+Incoming HTTP
     |
     v
-CacheStore
+request tracing middleware
     |
-    +-- CacheAdapter
-    |      +-- memory
-    |      +-- Redis-compatible
+    +-- AsyncLocalStorage trace context
+    +-- W3C traceparent
+    +-- correlationId
     |
-    +-- CacheLockAdapter
-    |      +-- memory
-    |      +-- Redis-compatible
+    +-- database/cache child spans
+    +-- trace carrier -> jobs/workflows/events/realtime
     |
-    +-- local singleflight
-    +-- distributed cache-fill lease
-    +-- TTL / tags / paths
-    +-- metrics sink
+    v
+TraceSpanExporter
+    +-- memory exporter
+    +-- trace metrics exporter
+    +-- application/vendor exporter
 ```
 
-`getOrSet()` deduplicates cache fills inside one process. With a shared lock adapter, multiple processes coordinate cache misses through owner-scoped leases, optional lock renewal and wait/poll behavior.
+A root trace owns a stable `traceId` and `correlationId`. Nested spans inherit that identity and receive their own `spanId` / `parentSpanId` relationship.
+
+`createTraceCarrier()` and `runWithTraceCarrier()` provide explicit provider-neutral propagation through non-HTTP transports without changing persisted job/workflow/outbox schemas.
 
-The Redis reference adapter uses the default hash-tagged namespace `bcp:{cache}` and does not install or own a Redis client.
+Prepared npm packages compile `bcp/observability` to `observability.mjs` for standalone Node runtime use.
 
 New/updated sources:
 
 | Source | Purpose |
 | --- | --- |
-| `cache-platform-v2.md` | Adapter contracts, Redis cache/locks, stampede protection, TTL/invalidation and metrics |
-| `api-reference.md` | `bcp/cache` Cache Platform v2 APIs |
-| `platform-manifest.json` | Cache v2 capability flags |
-| `api-manifest.json` | Updated `bcp/cache` source/guide ownership |
-| `docs-web-manifest.json` | Cache v2 docs navigation and `0.2.16` release route |
-| `releases/0.2.16.md` | Cache Platform v2 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
 
@@ -116,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` |
@@ -125,7 +131,7 @@ When framework behavior or public surface changes:
 | `/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.16` | `releases/0.2.16.md` |
+| `/releases/0.2.17` | `releases/0.2.17.md` |
 
 Every route/source pair is validated by unit tests.
 
@@ -156,7 +162,7 @@ The API-manifest entrypoint set must match the platform public-entrypoint set ex
 
 ## Release validation
 
-Before publishing `0.2.16`:
+Before publishing `0.2.17`:
 
 ```bash
 npm run typecheck
@@ -167,6 +173,6 @@ npm run test:package
 npm run rc:check
 ```
 
-Cache Platform v2 validation covers TTL/tag/path invalidation, local singleflight, cross-store distributed locking, lock timeout behavior, Redis command contracts, metrics integration, compiled `cache.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.16",
+  "version": "0.2.17",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [
@@ -27,7 +27,7 @@
       "environment": "server-preferred",
       "route": "/docs/api-reference#bcp-cache",
       "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"]
+      "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", "/docs/cache-platform-v2"]
+      "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"]
     }
   ]
 }