@decocms/start 6.0.0 → 6.1.0

package/MIGRATION_TOOLING_PLAN.md

@@ -121,6 +121,15 @@ this plan.
 | 2026-05-07 | **D6.1 — Cloudflare credentials never leave `deco-start`** | Same-day refinement of D6 after the first central deploy on `baggagio-tanstack` failed with `Secret CLOUDFLARE_API_TOKEN is required, but not provided while calling`. The original D6 design used `secrets: inherit` from the storefront stub and required `CLOUDFLARE_*` to live in the `deco-sites` org, which broke the principle that *the only secrets a storefront repo holds are the secrets that go into wrangler secrets, not the ones used to deploy*. First-pass refinement: the central `deploy.yml` / `preview.yml` / `sync-secrets.yml` jobs declared `environment: production` to try to make `${{ secrets.CLOUDFLARE_* }}` resolve from `decocms/deco-start`'s `production` Environment. **Found broken empirically on 2026-05-07** — the deployment registers in the *caller* repo, not the called workflow's repo, so the environment lookup uses the caller's `production` env (auto-created with no secrets). Superseded by D6.2 the same evening. |
 | 2026-05-07 | **D6.2 — App-mediated dispatch + no per-site registry (supersedes D6 + D6.1)** | After D6.1's `environment:` mechanism was empirically shown not to work cross-repo, the architecture pivoted: a `decocms-deployer` GitHub App is installed on `decocms/deco-start` (`actions:write`) and on each storefront repo (`contents:read`, optionally `pull-requests:write`). The storefront caller stub mints a short-lived App-installation token and calls `gh workflow run deploy.yml --repo decocms/deco-start --ref v3 -f site_owner=… -f site_name=…`. The central workflow runs in `decocms/deco-start`'s context, so `CLOUDFLARE_API_TOKEN` / `CLOUDFLARE_ACCOUNT_ID` are ordinary repo secrets. For runtime `SECRET_*` values, each storefront has a `<site_name>-secrets` GitHub Environment in `decocms/deco-start` (S1 design); `sync-secrets.yml` binds to that environment and pushes to `wrangler secret put`. The per-site registry under `deploy/sites/<repo>.jsonc` was dropped entirely (Pure C): worker name = repo basename by convention; the App being installed on the storefront repo is the deploy authorization gate; rare per-worker derived fields (like AE dataset name) use `$WORKER_*` substitution tokens in the template. Force-rollback is impossible for production deploys because the central workflow ignores caller-supplied `site_sha` and resolves the storefront's current default-branch HEAD itself. See [`deploy/README.md`](./deploy/README.md) for the full trust model. **Operational migrations required by Pure C:** `miess-01-tanstack` repo's worker shifts from `miess-tanstack` to `miess-01-tanstack` (CF-side cutover); `lebiscuit-tanstack` AE dataset shifts from `deco_metrics_lebiscuit` to `deco_metrics_lebiscuit_tanstack` (orphans old data). |
 | 2026-05-07 | **D6.3 — Revert D6/D6.1/D6.2; deploys move to Cloudflare Workers Builds** | The whole D6 family (centralized GitHub Actions reusable workflows + `decocms-deployer` GitHub App + per-storefront GitHub Environments + central `deploy/wrangler-template.jsonc` + `deco-wrangler` CLI + per-site caller stubs) is being **reverted**. Trigger: GitHub Free orgs do not propagate org-level secrets to private repos, which forced the App private key to live as a per-storefront repo secret in every storefront — that key gives the holder the ability to mint installation tokens that can trigger workflows on `decocms/deco-start`, which in turn have the only Cloudflare credentials in the system. Per-repo distribution + rotation of that key across N customer storefronts didn't scale and concentrated blast radius on one credential. **Replacement (chosen, to be detailed in a follow-up D-record once shipped):** [Cloudflare Workers Builds](https://developers.cloudflare.com/workers/ci-cd/builds/) owns the deploy/preview pipelines per-worker. Verified empirically on `baggagio-tanstack` 2026-05-07: a malicious `wrangler.jsonc` `name` field pointing at a different worker (`americanas-tanstack`) is **ignored** by CF Builds — the deploy lands on the connected worker (`baggagio-tanstack`), CF surfaces a warning banner in the dashboard, and CF auto-opens a PR to fix the config (deco-sites/baggagio-tanstack#34). The dashboard repo<->worker connection is the source of truth; the in-repo config is treated as a secondary input. Per-storefront wiring (one CF dashboard click per worker) is acceptable at our scale; revisit when CF's [git-integration enable API](https://github.com/cloudflare/workers-sdk/issues/12058) lands. The `deco-build` CLI (regenerates `wrangler.jsonc` bindings from a central template) and runtime-secrets management remain to be designed in a separate PR. |
+| 2026-05-22 | **D-9 — Stable `request.id` propagation across all observability channels** | The fragmentation surfaced during the May 2026 error triage: tail-worker logs, direct-POST metrics, CF-Destinations spans, and structured `console.log` JSON all carry overlapping information but no shared join key. A single user-visible 5xx required hand-correlating timestamps across four ClickHouse tables. **Decision:** the framework generates a stable `request.id` once at request entry (precedence: inbound `x-request-id` → `cf-ray` → `crypto.randomUUID()`) inside `RequestContext.run`, then stamps it on (a) the root span as the `request.id` attribute, (b) every log line via the logger attribute floor, (c) the response as `X-Request-Id` (read by `deco-otel-tail`), and (d) the metric labels via `extra`. Symmetric for `trace.id` — read from the root span's spanContext, echoed as `X-Trace-Id`. This re-establishes a single join key across all channels: pick any row from any table, filter by `request.id`, and reconstruct the full request lifecycle. **Files:** `RequestContext.requestId` + logger floor + workerEntry response-header echo + tail-worker enrichment. **Captured in Phase 1 of [the observability refinement plan](../../.cursor/plans/observability_refinement_plan_4fa41548.plan.md)**. |
+| 2026-05-22 | **D-10 — Server-side log normalization at the ingest worker, cost-neutral** | CF Destinations wraps every `console.log(JSON.stringify(...))` line into an OTLP LogRecord with the JSON body in `body.stringValue`. Querying by structured fields requires `JSONExtract` everywhere — slow, query-fragile, and tied to whatever the producer happens to embed. **Two design choices considered:** (a) migrate all framework `logger.{info,warn,debug}` calls to direct-POST native OTLP, ditching the CF Destinations sampled path. Substantially more code volume in production direct-POST traffic; bypasses the head sampling that keeps fleet cost bounded. (b) lift the JSON-in-body into native OTLP `LogAttributes` server-side at the `deco-otel-ingest` worker. Same wire volume, same cost. **Decision: option (b).** The ingest worker's `logsToRows` now detects JSON-shaped `body.stringValue`, lifts `level`/`msg`/`trace_id`/`span_id` plus arbitrary keys into native OTLP attributes, reduces `Body` to the human-readable `msg`, and falls back unchanged for non-JSON strings (third-party `console.log`). Dashboards drop `JSONExtractString(Body, 'level') = 'error'` in favor of `SeverityText = 'ERROR'`. **Files:** `stats-lake/ingestion/otel-ingest/src/index.ts`. Phase 4 of the observability refinement plan. |
+| 2026-05-22 | **D-11 — Outcome metrics layer becomes the truth source for "did we serve users today?"** | Earlier metric labels (`method`, `path`, `status`) couldn't answer "5xx rate per route per site" without joining metrics to tail-worker logs. The path label was raw-URL (unbounded cardinality risk); status was opaque (no class bucketing); no cache decision / cache layer; no commerce histogram in the framework (only apps-start sites that bumped to a recent version had it). **Decision:** expand the canonical label set for `http_requests_total` / `http_request_duration_ms` / `http_request_errors_total` to `{ method, route_pattern, status, status_class, outcome?, cache_decision?, cache_layer?, region?, …extra }`. `route_pattern` is the TanStack closed-set pattern (`/_products/$slug/p`); fallback is the normalized path. `status_class` is `2xx`/.../`5xx`/`unknown`. Cache labels lift the existing `X-Cache` / `X-Cache-Profile` headers up to the metric so dashboards answer cache-hit rate per route from the counter alone. Move `commerce_request_duration_ms` declaration into `@decocms/start` so every site emits it as soon as the framework is bumped, regardless of apps-start version (apps register operation strings only). Labels: `{ provider, operation, status_class?, cached? }`. **Files:** `src/middleware/observability.ts` (`statusClassFor`, `RequestMetricLabels`, `CacheLayer`, `recordCommerceMetric`, expanded `recordCacheMetric` signature). Phase 2 of the observability refinement plan. |
+| 2026-05-22 | **D-12 — Direct-POST OTLP trace exporter for framework `deco.*` spans** | Empirical verification (May 2026) confirmed the framework's 10+ `withTracing` calls produced zero rows in `otel_traces`. Root cause: the bridge tracer in `instrumentWorker` delegates to `trace.getTracer(...)` on the `@opentelemetry/api` global. With no `TracerProvider` registered (the common case — CF Workers only auto-installs a provider when `observability.traces.destinations` is set), every framework span is silently discarded. **Decision:** introduce `otelHttpTracer.ts` — a direct-POST OTLP/HTTP trace exporter that mirrors the existing meter + error-log adapters. Same transport: per-isolate buffer, ctx.waitUntil flush, FNV-1a hash sampling at `headSamplingRate` (default 0.01 matches CF Destinations recommendation). Consistent per-trace decision so child spans are kept iff their root is kept. Honors inbound W3C `traceparent` — if the remote parent arrived sampled, every span in that trace is exported regardless of the rate. Wired alongside the existing `@opentelemetry/api` bridge via `configureTracerStack` — CF auto-spans still flow to the CF dashboard, framework spans direct-POST to ClickHouse. Default-on `injectTraceContext` inside `createInstrumentedFetch` was already in place. **Files:** `src/sdk/otelHttpTracer.ts`, `src/sdk/otel.ts` (`configureTracerStack`), `src/sdk/workerEntry.ts` (traceparent parsing). Phase 3 of the observability refinement plan. |
+| 2026-05-22 | **D-13 — Per-site Grafana dashboards + alert rules are auto-provisioned from `dim_sites`** | Hand-built dashboards drift the moment a new site lands: a fleet of 100 sites can't be maintained by a human curator. **Decision:** the canonical observability provisioning lives in [`stats-lake/observability/`](../../../stats-lake/observability/) — a single dashboard template + a single alert-rule template, parameterized by `{{site}}`/`{{team}}`/`{{datasource_uid}}` and rendered once per site by `scripts/provision-dashboards.ts` (reads `dim_sites` joined to `dim_teams`, writes to `dashboards/dist/<team>/<site>.json` + `alerts/dist/<team>/<site>.yaml`). Alerts use **anomaly bands, not thresholds** — current 5-min mean vs 24h rolling mean ± 3σ, fires after 10 minutes outside the band. Same rule set runs on every site, but the baseline is per-site so a noisy storefront doesn't false-positive against a quiet one. Every alert carries a `runbook_url` annotation pointing at [`deco-start/docs/runbooks/`](../docs/runbooks/) — the runbook is part of the alert, not a separate artifact. **Decision points open** (Phase 5 of the refinement plan): alerting venue (Grafana → email, Linear MCP tickets, both, or none for v1). **Files:** `stats-lake/observability/{dashboards,alerts,scripts,README.md}` + `deco-start/docs/runbooks/`. |
+| 2026-05-22 | **D-17 — Alerting venue: none for v1; ship dashboards-only** | The action layer (Phase 5) generates anomaly-band alert rule templates per site, but every alert needs a pager and we don't have an on-call rotation. **Decision:** ship dashboards-only for v1. The alert templates in `stats-lake/observability/alerts/templates/site-rules.yaml` stay versioned so they evolve with the dashboards, but `provision-dashboards.ts` only templates them into `alerts/dist/` when `--with-alerts` is passed, and no Grafana → email / Linear MCP / PagerDuty receiver is wired up. Rejected alternatives: (a) Grafana → email — emails get muted within a week without a triage owner; (b) Linear MCP ticket-per-fire — creates noise during active incidents and you can't triage a ticket while firefighting; (c) both — overkill before we know which storefronts will be noisiest. **Revisit when:** an on-call rotation exists, OR a specific incident class earns dedicated paging (e.g., billing-critical sites that need 24/7 coverage). **Files:** `stats-lake/observability/scripts/provision-dashboards.ts` (`--with-alerts` flag), `stats-lake/observability/README.md`. Phase 5 of the observability refinement plan. |
+| 2026-05-22 | **D-16 — `deco-audit-observability` is warn-by-default; promote to block once the fleet is clean** | The audit (D-14) detects drift in `tail_consumers`, `version_metadata`, `DECO_METRICS`, and `DECO_OTEL_*_ENDPOINT` vars across every storefront wrangler.jsonc. Pre-merge blocking on day one would fail PRs that have nothing to do with observability — storefronts are upgraded over weeks, not all at once. Advisory comments alone get ignored. **Decision:** `--mode warn` (default) annotates findings via `::warning::` GitHub Actions lines but always exits 0, so observability drift surfaces in CI without blocking ship. `--mode block` exits 1 on any `error`-severity finding for use once the fleet has been pulled current. Storefronts opt into `block` per-repo by wiring `--mode block` in their workflow when they've cleared their findings. Includes `--github` flag to emit native annotations. **Files:** `scripts/audit-observability-config.ts` (parseArgs `--mode` / `--github`, main exit policy), test coverage in the matching `.test.ts` (6 new CLI smoke tests via tsx subprocess). Phase 6 of the observability refinement plan. |
+| 2026-05-22 | **D-15 — OTel Collector swap is a documented target state, not a committed milestone** | The current `deco-otel-ingest` Worker is a hand-rolled OTLP/HTTP parser + ClickHouse inserter. It works at ~14M POSTs/month, but each new OTLP protocol revision, each new receiver (gRPC OTLP, Prometheus remote-write), and each new sink would cost us code to write and maintain — code the upstream OTel Collector + `clickhouseexporter` ship as a maintained product. **Decision:** mark the Collector swap as the eventual target state, **with no committed timeline**, and capture the explicit revisit-triggers so we know when to act rather than relying on "we should think about this sometime." The decision is cheap because the ClickHouse schema is **already** the canonical `clickhouseexporter` shape — that was a deliberate design choice in `clickhouse/schema/otel/` so the ingest path stays swappable. Migration when triggered is config-only at the data layer: stand up a Collector in the same CF account, configure `otlphttp`/`otlpgrpc` receivers + `clickhouse/v1` exporter + `transform` processors for the existing PII redaction and JSON-body lift (1:1 from current Worker logic), DNS-cutover the `DECO_OTEL_*_ENDPOINT` vars. **Revisit triggers:** OTLP 2.0 ships, we need gRPC OTLP, we need a non-ClickHouse sink, ingest volume exceeds 100M POSTs/mo, or a hand-rolled parser develops a defect we can't fix quickly. **Files:** [`stats-lake/ingestion/otel-ingest/COLLECTOR_TARGET.md`](../../../stats-lake/ingestion/otel-ingest/COLLECTOR_TARGET.md) holds the full migration runbook + rollback story. Phase 7 of the observability refinement plan; explicitly **optional**. |
+| 2026-05-22 | **D-14 — `deco-audit-observability` covers fleet bindings, not just the `observability` block** | The existing audit only checked the `observability` block (sampling rates, persist, destinations). Phase 1+2+3 made several other wrangler keys load-bearing: `tail_consumers` must list `deco-otel-tail` (Phase 1 enrichment is a no-op without it), `version_metadata` must bind `CF_VERSION_METADATA` (no `service.version` without it = no deploy correlation), `analytics_engine_datasets` must bind `DECO_METRICS` (no AE meter), `vars.DECO_OTEL_{METRICS,TRACES,LOGS}_ENDPOINT` must resolve (direct-POST channels silently no-op otherwise). **Decision:** expand the audit with six new rules under a sibling function `auditFleetBindings` and a composing `auditWranglerConfig`. Severity tuned to the impact: tail consumer + version_metadata are `error` (operational coverage gap); the rest are `warn` (degraded mode, not total failure). Drift is detected today; the matching `--fix` codemod and CI gate hardness (block / warn / advisory) are Phase 6 decision points still open. **Files:** `scripts/audit-observability-config.ts` (`auditFleetBindings`, `auditWranglerConfig`). |
 | 2026-05-19 | **D-8 — Cloudflare Tail Worker (Strategy B) is the canonical 100% error capture mechanism** | At fleet scale (100 sites, 2.5B req/month) head sampling forces a tradeoff: 1% sampling makes the `head_sampling_rate * 5B-event-cap` math work, but 99% of error traces and 99% of error-correlated logs get dropped at the CF Destinations head. The framework already covers framework-emitted errors via the in-Worker direct-POST channel (`DECO_OTEL_LOGS_ENDPOINT`) — that's 100% of `logger.error(...)` regardless of `head_sampling_rate`. But three structural gaps remain that *no* in-Worker code can close from inside its own request handler: (a) uncaught throws (the worker isolate is already unwinding when the throw bubbles out of `instrumentWorker`), (b) `exceededCpu` / `exceededMemory` outcomes (the runtime kills the producer before any in-Worker code can run), (c) raw `console.error(...)` from third-party SDKs that bypass the framework logger. **Decision:** introduce [`deco-otel-tail`](https://github.com/decocms/stats-lake/tree/main/ingestion/otel-tail) — a Cloudflare Tail Worker in `stats-lake/ingestion/otel-tail/`. CF invokes it on every execution of any producer worker that lists it under `tail_consumers` (`wrangler.jsonc`). The handler filters TraceItems down to the interesting subset (`outcome !== "ok" \|\| exceptions.length > 0 \|\| logs.some(l => l.level === "error")`), translates each to OTLP LogRecords (one per exception, one per `error`-level log line, plus a synthetic LogRecord for non-ok outcomes that didn't surface either), and forwards them to `deco-otel-ingest` via an in-account service binding (no public hop). Rows land in `otel_logs` with `Attributes['_source'] = 'tail-worker'` so dashboards can split tail-captured errors from direct-POST + CF-Destinations errors. **Rejected alternatives:** (1) **Codemod + lint to enforce `logger.error` calls** — structural coverage gap; can't catch uncaught throws or 1101s by definition, and a lint can't enforce calls inside third-party code. (2) **Logpush + ingest pipeline** — bypassed because Logpush isn't OTLP-shaped and the pricing curve loses to tail-worker at our scale. (3) **CF dashboard log retention only** — no fan-out to ClickHouse, no fleet-wide query surface. (4) **DO-buffered tail-on-error** — ~$8K/mo at fleet scale per the cost model in `docs/observability.md`. **Coverage matrix lives in [`docs/observability.md`](./docs/observability.md) → "Error capture — three-channel model".** Producer-side wiring is one line per `wrangler.jsonc`: `tail_consumers: [{ service: "deco-otel-tail" }]`. **Operational dependency:** the tail worker MUST be deployed to the same Cloudflare account as `deco-otel-ingest` (currently `c95fc4cec7fc52453228d9db170c372c`) so the `[[services]]` binding resolves. If `deco-otel-ingest` ever moves accounts, the service binding collapses to a public HTTPS POST and the model needs revisiting. **Agent behaviour:** when designing error capture for new Worker-deployed code, default to Strategy B for the long tail; don't reach for codemod/lint enforcement unless there's a specific code-quality concern beyond capture. |
 
 The full text of the constitutional rule (loaded into every agent

package/docs/observability.md

@@ -71,17 +71,24 @@ This makes it possible to filter traces by cache decision directly in ClickStack
 
 ## What's measured
 
-| Metric                         | Type      | Source                              | Labels                          |
-| ------------------------------ | --------- | ----------------------------------- | ------------------------------- |
-| `http_requests_total`          | counter   | `workerEntry`                       | `method`, `path`, `status`      |
-| `http_request_duration_ms`     | histogram | `workerEntry`                       | `method`, `path`, `status`      |
-| `http_request_errors_total`    | counter   | `workerEntry` (status >= 500)       | `method`, `path`, `status`      |
-| `cache_hit_total`              | counter   | edge cache decision                 | `profile`, `decision`           |
-| `cache_miss_total`             | counter   | edge cache decision                 | `profile`, `decision`           |
-| `resolve_duration_ms`          | histogram | `resolveDecoPage`                   | —                               |
+| Metric                          | Type      | Source                              | Labels (canonical, Phase 2 / D-11)                                                              |
+| ------------------------------- | --------- | ----------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `http_requests_total`           | counter   | `workerEntry`                       | `method`, `route_pattern`, `status`, `status_class`, `outcome?`, `cache_decision?`, `cache_layer?`, `region?` |
+| `http_request_duration_ms`      | histogram | `workerEntry`                       | same as `http_requests_total`                                                                  |
+| `http_request_errors_total`     | counter   | `workerEntry` (status >= 500)       | same as `http_requests_total`                                                                  |
+| `cache_hit_total`               | counter   | edge cache decision                 | `profile`, `decision`, `layer` (`edge` \| `cachedLoader` \| `vtex-swr`)                         |
+| `cache_miss_total`              | counter   | edge cache decision                 | `profile`, `decision`, `layer`                                                                  |
+| `commerce_request_duration_ms`  | histogram | commerce clients (vtex/shopify/…)   | `provider`, `operation`, `status_class?`, `cached?`                                             |
+| `resolve_duration_ms`           | histogram | `resolveDecoPage`                   | —                                                                                              |
 
 `decision` values mirror the `X-Cache` response header: `HIT`, `STALE-HIT`, `STALE-ERROR`, `MISS`, `BYPASS`.
 
+`route_pattern` is the TanStack route pattern (e.g. `/_products/$slug/p`) rather than the raw URL path — bounded cardinality, joinable to the route table. Callers that don't supply one get a normalized path with dynamic segments collapsed (`/products/:slug/p`).
+
+`status_class` is the canonical `2xx`/.../`5xx`/`unknown` bucket. Dashboards aggregate by `status_class` for SLO panels and by `status` for incident drill-down.
+
+`commerce_request_duration_ms` owned by the framework (Phase 2 / D-11) so every site emits it as soon as `@decocms/start` is bumped, regardless of `@decocms/apps` version. Apps register operation strings via `recordCommerceMetric`; the framework owns the cardinality contract.
+
 ### Metrics: AE vs OTLP (the two-meter split)
 
 `instrumentWorker` plugs **up to two meters in parallel**, composed via `createCompositeMeter`:
@@ -181,8 +188,9 @@ The direct-POST channels are wired automatically when the relevant env vars reso
 | ---------------------------------- | -------------------- | ---------------------- | ---------------------------------------------------- |
 | `DECO_OTEL_METRICS_ENDPOINT`       | OTLP metrics POST    | `""` (unset)           | OTLP meter is not created; AE-only metrics           |
 | `DECO_OTEL_LOGS_ENDPOINT`          | OTLP error-log POST  | `""` (unset)           | Error logs ride CF Destinations only (head-sampled)  |
+| `DECO_OTEL_TRACES_ENDPOINT`        | OTLP traces POST     | `""` (unset)           | Framework `deco.*` spans drop unless CF Traces is on |
 
-Both are opt-out via `OtelOptions.otlpMetricsEnabled: false` / `otlpErrorLogsEnabled: false` if you need to disable them at boot for a specific environment without changing the env vars.
+All three are opt-out via `OtelOptions.otlpMetricsEnabled: false` / `otlpErrorLogsEnabled: false` / `otlpTracesEnabled: false` if you need to disable them at boot for a specific environment without changing the env vars. Traces honor `OtelOptions.otlpTracesSamplingRate` (default `0.01` to match CF Destinations) — sampling decisions are consistent per trace (`FNV-1a` hash of `trace_id`), so child spans are kept iff their root is kept. Remote parents that arrive sampled (`traceparent` flags `01`) override the rate and are always exported.
 
 ## Log shape (and how to query it)
 
@@ -213,7 +221,9 @@ In the ClickStack UI you can also filter logs panel by `trace_id` directly — p
 
 ## Outbound trace propagation
 
-For any outbound `fetch` issued during a request (VTEX, Shopify, internal APIs), inject a W3C `traceparent` header so upstream services that participate in OTel can join your trace:
+For commerce clients (VTEX, Shopify), `createInstrumentedFetch` injects the W3C `traceparent` header by default. To opt out for a specific endpoint that rejects unknown headers, pass `injectTraceparent: false`.
+
+For any other outbound `fetch` issued during a request, inject a `traceparent` header manually so upstream services that participate in OTel can join your trace:
 
 ```ts
 import { injectTraceContext } from "@decocms/start/sdk/observability";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/scripts/generate-invoke.test.ts

@@ -21,18 +21,20 @@ import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
 
 const GENERATOR = path.resolve(__dirname, "generate-invoke.ts");
 
 const FIXTURE_INVOKE_TS = `\
 import { createInvokeFn } from "@decocms/start/sdk/createInvoke";
 import { getOrCreateCart, simulateCart } from "./actions/checkout";
+import { createSession } from "./actions/session";
 import type { OrderForm } from "./types";
 
 export const invoke = {
 	vtex: {
 		actions: {
+			// Direct pass-through wrapper — most common shape.
 			getOrCreateCart: createInvokeFn(
 				(data: { orderFormId?: string }) => getOrCreateCart(data),
 			) as unknown as (ctx: { data: { orderFormId?: string } }) => Promise<OrderForm>,
@@ -40,6 +42,13 @@ export const invoke = {
 			simulateCart: createInvokeFn(
 				(data: { postalCode: string }) => simulateCart(data),
 			),
+
+			// Adapting wrapper — payload gets wrapped into the action's
+			// props shape. The generator MUST preserve this wrap or the
+			// action call typechecks against the wrong props type.
+			createSession: createInvokeFn(
+				(data: Record<string, any>) => createSession({ data }),
+			),
 		},
 	},
 } as const;
@@ -52,14 +61,25 @@ const FIXTURE_ACTIONS_CHECKOUT_TS = `\
 export async function getOrCreateCart(_data: any): Promise<any> { return null; }
 export async function simulateCart(_data: any): Promise<any> { return null; }
 `;
+const FIXTURE_ACTIONS_SESSION_TS = `\
+export interface CreateSessionProps { data: Record<string, any>; }
+export async function createSession(_props: CreateSessionProps): Promise<any> { return null; }
+`;
 const FIXTURE_TYPES_TS = `export type OrderForm = unknown;\n`;
 
 describe("generate-invoke.ts — output shape", () => {
+  // The fixture is read-only across tests: every assertion runs against
+  // the same generated `invoke.gen.ts`. Running the generator once in
+  // `beforeAll` keeps the test fast (each `npx tsx` spawn is ~3-5s) and
+  // sidesteps the vitest 5s default per-test timeout that this suite was
+  // tipping over once we grew the fixture.
   let appsDir: string;
   let siteDir: string;
   let outFile: string;
+  let generatedOutput: string;
+  let generatorStatus: number | null;
 
-  beforeEach(() => {
+  beforeAll(() => {
     const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "gen-invoke-"));
     appsDir = path.join(tmp, "apps");
     siteDir = path.join(tmp, "site");
@@ -70,11 +90,23 @@ describe("generate-invoke.ts — output shape", () => {
       path.join(appsDir, "vtex", "actions", "checkout.ts"),
       FIXTURE_ACTIONS_CHECKOUT_TS,
     );
+    fs.writeFileSync(
+      path.join(appsDir, "vtex", "actions", "session.ts"),
+      FIXTURE_ACTIONS_SESSION_TS,
+    );
     fs.writeFileSync(path.join(appsDir, "vtex", "types.ts"), FIXTURE_TYPES_TS);
     outFile = path.join(siteDir, "src", "server", "invoke.gen.ts");
-  });
 
-  afterEach(() => {
+    const result = spawnSync(
+      "npx",
+      ["tsx", GENERATOR, "--apps-dir", appsDir, "--out-file", outFile],
+      { cwd: siteDir, encoding: "utf8" },
+    );
+    generatorStatus = result.status;
+    generatedOutput = fs.readFileSync(outFile, "utf8");
+  }, 30_000);
+
+  afterAll(() => {
     // Best-effort cleanup; tmp dirs leak otherwise.
     try {
       fs.rmSync(path.dirname(appsDir), { recursive: true, force: true });
@@ -83,86 +115,81 @@ describe("generate-invoke.ts — output shape", () => {
     }
   });
 
-  function runGenerator(): { stdout: string; stderr: string; status: number | null } {
-    const result = spawnSync(
-      "npx",
-      [
-        "tsx",
-        GENERATOR,
-        "--apps-dir",
-        appsDir,
-        "--out-file",
-        outFile,
-      ],
-      {
-        cwd: siteDir,
-        encoding: "utf8",
-      },
-    );
-    return {
-      stdout: result.stdout ?? "",
-      stderr: result.stderr ?? "",
-      status: result.status,
-    };
-  }
+  it("runs to completion against a minimal fixture", () => {
+    // Sanity check — every subsequent assertion is wasted if the
+    // generator process bombed.
+    expect(generatorStatus).toBe(0);
+  });
 
   it("imports the framework helpers needed for Set-Cookie propagation", () => {
-    const { status } = runGenerator();
-    expect(status).toBe(0);
-
-    const out = fs.readFileSync(outFile, "utf8");
     // Both imports must be present — without them, forwardResponseCookies
     // doesn't compile in the site, and the regression we're fixing
     // resurfaces silently when someone deletes one of them.
-    expect(out).toContain('from "@tanstack/react-start/server"');
-    expect(out).toMatch(/getResponseHeaders\s*,?\s*\n?\s*setResponseHeader/);
-    expect(out).toContain('import { RequestContext } from "@decocms/start/sdk/requestContext"');
+    expect(generatedOutput).toContain('from "@tanstack/react-start/server"');
+    expect(generatedOutput).toMatch(/getResponseHeaders\s*,?\s*\n?\s*setResponseHeader/);
+    expect(generatedOutput).toContain(
+      'import { RequestContext } from "@decocms/start/sdk/requestContext"',
+    );
   });
 
   it("emits the forwardResponseCookies helper exactly once", () => {
-    runGenerator();
-    const out = fs.readFileSync(outFile, "utf8");
-    // Match the declaration, not call sites. There's only one helper.
-    const declMatches = out.match(/function forwardResponseCookies\(\)/g);
+    const declMatches = generatedOutput.match(/function forwardResponseCookies\(\)/g);
     expect(declMatches).toHaveLength(1);
 
     // The helper must read from RequestContext.responseHeaders and call
     // setResponseHeader. Locking the bridge ends-to-ends.
-    expect(out).toContain("RequestContext.current");
-    expect(out).toContain("ctx.responseHeaders.getSetCookie");
-    expect(out).toContain('setResponseHeader("set-cookie"');
+    expect(generatedOutput).toContain("RequestContext.current");
+    expect(generatedOutput).toContain("ctx.responseHeaders.getSetCookie");
+    expect(generatedOutput).toContain('setResponseHeader("set-cookie"');
   });
 
   it("calls forwardResponseCookies() inside every generated handler", () => {
-    runGenerator();
-    const out = fs.readFileSync(outFile, "utf8");
-
     // Each .handler(async ({ data }) ...) block produced by the
     // generator must contain a `forwardResponseCookies()` call. We
     // count handlers vs. call sites — excluding the declaration site
     // (`function forwardResponseCookies()`), which also matches the
     // bare `forwardResponseCookies()` token.
-    const handlerCount = (out.match(/\.handler\(async \(\{ data \}\)/g) ?? []).length;
-    const allOccurrences = (out.match(/\bforwardResponseCookies\(\)/g) ?? []).length;
-    const declSites = (out.match(/function\s+forwardResponseCookies\(\)/g) ?? []).length;
+    const handlerCount = (generatedOutput.match(/\.handler\(async \(\{ data \}\)/g) ?? []).length;
+    const allOccurrences = (generatedOutput.match(/\bforwardResponseCookies\(\)/g) ?? []).length;
+    const declSites = (generatedOutput.match(/function\s+forwardResponseCookies\(\)/g) ?? [])
+      .length;
     const callSites = allOccurrences - declSites;
 
-    expect(handlerCount).toBe(2);
+    expect(handlerCount).toBe(3);
     expect(declSites).toBe(1);
-    expect(callSites).toBe(2);
+    expect(callSites).toBe(3);
   });
 
   it("calls forwardResponseCookies AFTER the action awaits (so RequestContext is populated)", () => {
-    runGenerator();
-    const out = fs.readFileSync(outFile, "utf8");
-
     // The action must complete (await result) before we read the
     // captured Set-Cookies — otherwise we'd forward an empty set
-    // every time. Verifying ordering via regex is brittle but the
-    // surface is small enough.
+    // every time. The expression body after `await` can be any call
+    // shape the wrapper produces (`fn(data)` or `fn({ data })`),
+    // so we match across the whole expression up to the semicolon.
     const pattern =
-      /const result = await \w+\(data\);\s+forwardResponseCookies\(\);\s+return (?:unwrapResult\(result\)|result);/g;
-    const orderedCalls = out.match(pattern) ?? [];
-    expect(orderedCalls.length).toBe(2);
+      /const result = await [^;]+;\s+forwardResponseCookies\(\);\s+return (?:unwrapResult\(result\)|result);/g;
+    const orderedCalls = generatedOutput.match(pattern) ?? [];
+    expect(orderedCalls.length).toBe(3);
+  });
+
+  it("preserves adapting wrappers verbatim (does not collapse to actionFn(data))", () => {
+    // Regression for the createSession-shape wrapper: the generator
+    // previously hard-coded `${importedFn}(data)` in every handler,
+    // silently dropping the wrap that wrappers like
+    //   createSession: createInvokeFn((data) => createSession({ data }))
+    // perform to bridge the external invoke shape to the internal
+    // action shape. Sites that regenerated against this hit
+    // `TS2345: Property 'data' is missing in type '{ [x: string]: any; }'`
+    // at the regenerated call site of every adapting wrapper.
+    expect(generatedOutput).toContain("const result = await createSession({ data });");
+    // And the broken shortcut must NOT appear for this action.
+    expect(generatedOutput).not.toMatch(/const result = await createSession\(data\);/);
+
+    // Direct pass-through wrappers are unaffected: their body is
+    // already `actionFn(data)`, so emitting verbatim produces the same
+    // output that the previous shortcut produced. Lock that too — a
+    // future refactor that breaks pass-throughs would be just as bad.
+    expect(generatedOutput).toContain("const result = await getOrCreateCart(data);");
+    expect(generatedOutput).toContain("const result = await simulateCart(data);");
   });
 });

package/scripts/generate-invoke.ts

@@ -375,23 +375,39 @@ for (const action of actions) {
   const varName = `$${action.name}`;
 
   if (action.importedFn) {
-    // All @decocms/apps action functions take a single props object.
-    // Pass the validated `data` object directly — never destructure into
-    // positional arguments, which breaks when function signatures change.
+    // Emit the wrapper body verbatim. The arrow function in
+    // @decocms/apps/vtex/invoke.ts is the contract that maps the external
+    // invoke shape (what storefront callers send) to the internal action
+    // shape (what vtex/actions/* expects). Most wrappers are direct
+    // pass-throughs (`actionFn(data)`) but some adapt the payload
+    // (e.g. `createSession({ data })` wraps a flat session payload into
+    // CreateSessionProps). Hard-coding `${importedFn}(data)` silently
+    // dropped the wrap, producing typecheck errors at the call site of
+    // every adapting wrapper.
+    //
+    // Invariant: when action.importedFn is set, action.callBody was
+    // non-empty and contained `${importedFn}(` (that's how importedFn was
+    // discovered in the first place — see the importMap scan above).
+    // Block bodies clear callBody to "", which forces importedFn to ""
+    // and routes to the stub branch below.
+    //
+    // The arrow's parameter is `data` by convention across every wrapper
+    // in vtex/invoke.ts, and the generated handler destructures `{ data }`
+    // from the validator output, so callBody's `data` references resolve
+    // to the handler's local `data` without any rename.
     //
     // forwardResponseCookies() runs AFTER the action awaits, so any
     // Set-Cookie that vtexFetchWithCookies captured onto
     // RequestContext.responseHeaders gets promoted to the actual HTTP
-    // response. Safe no-op when the action didn't touch
-    // responseHeaders (e.g. masterData reads), so it's applied
-    // unconditionally — the alternative (a static allow-list of
-    // cookie-bearing actions) silently misses any new actions that
-    // start propagating cookies.
+    // response. Safe no-op when the action didn't touch responseHeaders
+    // (e.g. masterData reads), so it's applied unconditionally — the
+    // alternative (a static allow-list of cookie-bearing actions)
+    // silently misses any new actions that start propagating cookies.
     if (action.unwrap) {
       out += `\nconst ${varName} = createServerFn({ method: "POST" })
   .inputValidator((data: ${action.inputType}) => data)
   .handler(async ({ data }): Promise<any> => {
-    const result = await ${action.importedFn}(data);
+    const result = await ${action.callBody};
     forwardResponseCookies();
     return unwrapResult(result);
   });\n`;
@@ -399,7 +415,7 @@ for (const action of actions) {
       out += `\nconst ${varName} = createServerFn({ method: "POST" })
   .inputValidator((data: ${action.inputType}) => data)
   .handler(async ({ data }): Promise<any> => {
-    const result = await ${action.importedFn}(data);
+    const result = await ${action.callBody};
     forwardResponseCookies();
     return result;
   });\n`;

package/src/middleware/observability.test.ts

@@ -0,0 +1,237 @@
+/**
+ * Phase 2 (D-11) coverage for the metric surface — canonical label set,
+ * cache_layer, commerce_request_duration_ms. The Phase 1 logger/trace
+ * tests live under `src/sdk/logger.test.ts` and `src/sdk/otel.test.ts`;
+ * this file focuses on the middleware-level helpers.
+ */
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  configureMeter,
+  type MeterAdapter,
+  MetricNames,
+  recordCacheMetric,
+  recordCommerceMetric,
+  recordRequestMetric,
+  statusClassFor,
+} from "./observability";
+
+interface Counter {
+  name: string;
+  value: number;
+  labels?: Record<string, unknown>;
+}
+interface Histogram {
+  name: string;
+  value: number;
+  labels?: Record<string, unknown>;
+}
+
+function captureMeter(): {
+  adapter: MeterAdapter;
+  counters: Counter[];
+  histograms: Histogram[];
+} {
+  const counters: Counter[] = [];
+  const histograms: Histogram[] = [];
+  const adapter: MeterAdapter = {
+    counterInc(name, value, labels) {
+      counters.push({ name, value: value ?? 1, labels });
+    },
+    histogramRecord(name, value, labels) {
+      histograms.push({ name, value, labels });
+    },
+  };
+  return { adapter, counters, histograms };
+}
+
+describe("statusClassFor", () => {
+  it("maps 2xx / 3xx / 4xx / 5xx to canonical class labels", () => {
+    expect(statusClassFor(200)).toBe("2xx");
+    expect(statusClassFor(204)).toBe("2xx");
+    expect(statusClassFor(301)).toBe("3xx");
+    expect(statusClassFor(404)).toBe("4xx");
+    expect(statusClassFor(500)).toBe("5xx");
+    expect(statusClassFor(503)).toBe("5xx");
+  });
+
+  it("returns 'unknown' for out-of-range / NaN / non-numeric inputs", () => {
+    expect(statusClassFor(-1)).toBe("unknown");
+    expect(statusClassFor(99)).toBe("unknown");
+    expect(statusClassFor(600)).toBe("unknown");
+    expect(statusClassFor(Number.NaN)).toBe("unknown");
+    expect(statusClassFor(Infinity)).toBe("unknown");
+  });
+});
+
+describe("recordRequestMetric — canonical labels (D-11)", () => {
+  afterEach(() => {
+    // Reset meter so other tests start clean.
+    configureMeter({ counterInc: () => {} });
+  });
+
+  it("stamps method + route_pattern + status + status_class by default", () => {
+    const { adapter, counters, histograms } = captureMeter();
+    configureMeter(adapter);
+
+    recordRequestMetric("GET", "/products/abc123/p", 200, 42);
+
+    expect(counters).toHaveLength(1);
+    expect(counters[0]?.name).toBe(MetricNames.HTTP_REQUESTS_TOTAL);
+    expect(counters[0]?.labels).toMatchObject({
+      method: "GET",
+      // Default normalization: dynamic segments collapsed.
+      route_pattern: "/products/:slug/p",
+      status: 200,
+      status_class: "2xx",
+    });
+    expect(histograms).toHaveLength(1);
+    expect(histograms[0]?.name).toBe(MetricNames.HTTP_REQUEST_DURATION_MS);
+    expect(histograms[0]?.value).toBe(42);
+  });
+
+  it("prefers caller-supplied route_pattern over normalized path", () => {
+    const { adapter, counters } = captureMeter();
+    configureMeter(adapter);
+
+    recordRequestMetric("GET", "/anything/random/123", 200, 5, {
+      route_pattern: "/_products/$slug/p",
+    });
+
+    expect(counters[0]?.labels?.route_pattern).toBe("/_products/$slug/p");
+  });
+
+  it("emits http_request_errors_total on 5xx", () => {
+    const { adapter, counters } = captureMeter();
+    configureMeter(adapter);
+
+    recordRequestMetric("POST", "/checkout", 503, 120);
+
+    const errCounter = counters.find((c) => c.name === MetricNames.HTTP_REQUEST_ERRORS);
+    expect(errCounter).toBeDefined();
+    expect(errCounter?.labels?.status_class).toBe("5xx");
+  });
+
+  it("propagates optional labels (outcome, cache_decision, cache_layer, region, extra)", () => {
+    const { adapter, counters } = captureMeter();
+    configureMeter(adapter);
+
+    recordRequestMetric("GET", "/", 200, 10, {
+      outcome: "ok",
+      cache_decision: "STALE-HIT",
+      cache_layer: "edge",
+      region: "GRU",
+      extra: { ab_variant: "B" },
+    });
+
+    expect(counters[0]?.labels).toMatchObject({
+      outcome: "ok",
+      cache_decision: "STALE-HIT",
+      cache_layer: "edge",
+      region: "GRU",
+      ab_variant: "B",
+    });
+  });
+
+  it("is a no-op when no meter is configured", () => {
+    // We can't easily prove a no-op other than verifying no throw —
+    // safer than calling configureMeter(null), which would mask real
+    // bugs. The previous test's `afterEach` reset already gives us a
+    // bare meter; this test confirms the call is benign.
+    expect(() => recordRequestMetric("GET", "/", 200, 1)).not.toThrow();
+  });
+});
+
+describe("recordCacheMetric — cache_layer label", () => {
+  beforeEach(() => {
+    configureMeter({ counterInc: () => {} });
+  });
+
+  it("stamps profile + decision + layer when all are provided", () => {
+    const { adapter, counters } = captureMeter();
+    configureMeter(adapter);
+
+    recordCacheMetric(true, "product", "HIT", "edge");
+
+    expect(counters).toHaveLength(1);
+    expect(counters[0]?.name).toBe(MetricNames.CACHE_HIT);
+    expect(counters[0]?.labels).toMatchObject({
+      profile: "product",
+      decision: "HIT",
+      layer: "edge",
+    });
+  });
+
+  it("emits cache_miss_total when hit=false", () => {
+    const { adapter, counters } = captureMeter();
+    configureMeter(adapter);
+
+    recordCacheMetric(false, "search", "MISS", "edge");
+
+    expect(counters[0]?.name).toBe(MetricNames.CACHE_MISS);
+  });
+
+  it("supports the legacy 3-arg signature for backward compat", () => {
+    const { adapter, counters } = captureMeter();
+    configureMeter(adapter);
+
+    recordCacheMetric(true, "static");
+
+    expect(counters[0]?.labels).toEqual({ profile: "static" });
+  });
+
+  it("distinguishes cachedLoader vs edge vs vtex-swr layers", () => {
+    const { adapter, counters } = captureMeter();
+    configureMeter(adapter);
+
+    recordCacheMetric(true, "loader-x", "HIT", "cachedLoader");
+    recordCacheMetric(true, "vtex-product", "HIT", "vtex-swr");
+
+    expect(counters[0]?.labels?.layer).toBe("cachedLoader");
+    expect(counters[1]?.labels?.layer).toBe("vtex-swr");
+  });
+});
+
+describe("recordCommerceMetric (D-11)", () => {
+  beforeEach(() => {
+    configureMeter({ counterInc: () => {} });
+  });
+
+  it("emits commerce_request_duration_ms with provider + operation labels", () => {
+    const { adapter, histograms } = captureMeter();
+    configureMeter(adapter);
+
+    recordCommerceMetric(123, {
+      provider: "vtex",
+      operation: "intelligent-search.product_search",
+      status_class: "2xx",
+    });
+
+    expect(histograms).toHaveLength(1);
+    expect(histograms[0]?.name).toBe(MetricNames.COMMERCE_REQUEST_DURATION_MS);
+    expect(histograms[0]?.value).toBe(123);
+    expect(histograms[0]?.labels).toMatchObject({
+      provider: "vtex",
+      operation: "intelligent-search.product_search",
+      status_class: "2xx",
+    });
+  });
+
+  it("includes the cached boolean when provided", () => {
+    const { adapter, histograms } = captureMeter();
+    configureMeter(adapter);
+
+    recordCommerceMetric(5, {
+      provider: "shopify",
+      operation: "graphql.cart_query",
+      cached: true,
+    });
+
+    expect(histograms[0]?.labels?.cached).toBe(true);
+  });
+
+  it("is a no-op when no meter is configured", () => {
+    expect(() =>
+      recordCommerceMetric(1, { provider: "vtex", operation: "test" }),
+    ).not.toThrow();
+  });
+});