chore: import upstream snapshot with attribution

showcase/integrations/_shared/ts/cvdiag-emitter.test.ts

@@ -0,0 +1,205 @@
+/**
+ * cvdiag-emitter.test.ts — vitest suite for the shared TS integration emitter
+ * binding (plan unit L0-F). Asserts the four invariants the §6 PII/tier
+ * contract requires of EVERY language emitter:
+ *   - schema conformance (re-exported envelope keys + UUIDv7 minters),
+ *   - tier gating (default vs verbose vs debug boundary inclusion),
+ *   - PII scrub (Bearer / sk- secrets removed from captured values),
+ *   - forbidden-header rejection (cf-ipcountry never captured),
+ *   - DEBUG-in-production refusal (fail-closed startup guard).
+ *
+ * These re-exercise the L0-A invariants THROUGH the binding so a regression in
+ * the re-export wiring (wrong relative path, dropped symbol) fails here, not
+ * silently in a downstream TS integration.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import {
+  CvdiagEmitter,
+  ENVELOPE_KEYS,
+  EDGE_HEADER_DENYLIST,
+  SCHEMA_VERSION,
+  TEST_ID_REGEX,
+  filterEdgeHeaders,
+  isValidTestId,
+  mintSpanId,
+  mintTestId,
+  scrubSecrets,
+  validateEnvelope,
+} from "./cvdiag-emitter.js";
+import type { CvdiagEnvelope } from "./cvdiag-emitter.js";
+
+describe("L0-F binding: re-exports resolve from the canonical schema", () => {
+  it("re-exports SCHEMA_VERSION === 1", () => {
+    expect(SCHEMA_VERSION).toBe(1);
+  });
+
+  it("re-exports the closed envelope key set and validator", () => {
+    expect(ENVELOPE_KEYS).toContain("test_id");
+    expect(ENVELOPE_KEYS).toContain("edge_headers");
+    // A foreign top-level key is rejected (closed-world).
+    const bad = validateEnvelope({ test_id: "x", attacker_key: 1 });
+    expect(bad.ok).toBe(false);
+    expect(bad.unknownKeys).toContain("attacker_key");
+  });
+
+  it("re-exports the UUIDv7 minters + validator", () => {
+    const id = mintTestId();
+    expect(TEST_ID_REGEX.test(id)).toBe(true);
+    expect(isValidTestId(id)).toBe(true);
+    // A v4 UUID (version nibble 4) must be rejected.
+    expect(isValidTestId("00000000-0000-4000-8000-000000000000")).toBe(false);
+    // span_id is 16 lowercase hex chars.
+    expect(mintSpanId()).toMatch(/^[0-9a-f]{16}$/);
+  });
+});
+
+describe("L0-F binding: schema conformance of an emitted envelope", () => {
+  it("emits a closed-world envelope at the verbose tier", () => {
+    const emitter = new CvdiagEmitter({
+      verbose: true,
+      env: {},
+      layer: "backend",
+    });
+    const env = emitter.emit({
+      layer: "backend",
+      boundary: "backend.agent.enter",
+      slug: "langgraph-typescript",
+      demo: "agentic_chat",
+      outcome: "ok",
+      metadata: { agent_name: "main", model_id: "gpt-4o" },
+    }) as CvdiagEnvelope;
+    expect(env).not.toBeNull();
+    expect(env.schema_version).toBe(SCHEMA_VERSION);
+    expect(isValidTestId(env.test_id)).toBe(true);
+    expect(env.trace_id).toBe(env.test_id);
+    expect(env.boundary).toBe("backend.agent.enter");
+    // Every emitted key must be in the closed envelope key set.
+    expect(validateEnvelope(env as unknown as Record<string, unknown>).ok).toBe(
+      true,
+    );
+    // All 9 edge-header keys present (absent → null).
+    expect(Object.keys(env.edge_headers).sort()).toEqual(
+      [
+        "cf-cache-status",
+        "cf-mitigated",
+        "cf-ray",
+        "retry-after",
+        "server",
+        "via",
+        "x-hikari-trace",
+        "x-railway-edge",
+        "x-railway-request-id",
+      ].sort(),
+    );
+  });
+
+  it("drops unknown metadata keys and stamps _metadata_dropped", () => {
+    const emitter = new CvdiagEmitter({
+      verbose: true,
+      env: {},
+      layer: "backend",
+    });
+    const env = emitter.emit({
+      layer: "backend",
+      boundary: "backend.agent.enter",
+      slug: "mastra",
+      demo: "agentic_chat",
+      outcome: "ok",
+      metadata: { agent_name: "main", model_id: "gpt-4o", attacker: "x" },
+    }) as CvdiagEnvelope;
+    expect(env._metadata_dropped).toBe(true);
+    expect(env.metadata).not.toHaveProperty("attacker");
+  });
+});
+
+describe("L0-F binding: tier gating", () => {
+  it("default tier excludes a verbose-only boundary", () => {
+    const emitter = new CvdiagEmitter({ env: {}, layer: "backend" });
+    expect(emitter.tier).toBe("default");
+    // backend.request.ingress is verbose+debug only (default:false).
+    expect(emitter.shouldEmit("backend.request.ingress")).toBe(false);
+    // backend.agent.enter is default:true.
+    expect(emitter.shouldEmit("backend.agent.enter")).toBe(true);
+  });
+
+  it("verbose tier includes verbose-only boundaries", () => {
+    const emitter = new CvdiagEmitter({
+      verbose: true,
+      env: {},
+      layer: "backend",
+    });
+    expect(emitter.tier).toBe("verbose");
+    expect(emitter.shouldEmit("backend.request.ingress")).toBe(true);
+  });
+
+  it("accounting boundaries always emit regardless of tier", () => {
+    const emitter = new CvdiagEmitter({ env: {}, layer: "backend" });
+    expect(emitter.shouldEmit("cvdiag.queue_dropped")).toBe(true);
+  });
+});
+
+describe("L0-F binding: PII scrub (re-exported from edge-headers)", () => {
+  it("scrubs Bearer tokens", () => {
+    expect(scrubSecrets("auth: Bearer abc123def456")).toBe("auth: [REDACTED]");
+  });
+
+  it("scrubs sk- provider keys", () => {
+    expect(scrubSecrets("key sk-ABCDEFGHIJKLMNOP1234")).toBe("key [REDACTED]");
+  });
+});
+
+describe("L0-F binding: forbidden edge-header rejection", () => {
+  it("never captures cf-ipcountry even when present", () => {
+    const filtered = filterEdgeHeaders({
+      "cf-ray": "abc-iad",
+      "cf-ipcountry": "US",
+      "true-client-ip": "1.2.3.4",
+    });
+    expect(filtered["cf-ray"]).toBe("abc-iad");
+    expect(filtered).not.toHaveProperty("cf-ipcountry");
+    expect(filtered).not.toHaveProperty("true-client-ip");
+  });
+
+  it("the deny list contains the cf-ip* family by exact match", () => {
+    expect(EDGE_HEADER_DENYLIST).toContain("cf-ipcountry");
+    expect(EDGE_HEADER_DENYLIST).toContain("cf-connecting-ip");
+  });
+});
+
+describe("L0-F binding: DEBUG fail-closed in production", () => {
+  it("refuses DEBUG when env resolves to production", () => {
+    expect(
+      () =>
+        new CvdiagEmitter({
+          debug: true,
+          env: {
+            SHOWCASE_ENV: "production",
+            CVDIAG_DEBUG_ALLOW_LIST: "langgraph-typescript",
+          },
+        }),
+    ).toThrow(/production/);
+  });
+
+  it("refuses DEBUG when no env label resolves (unknown == prod)", () => {
+    expect(
+      () =>
+        new CvdiagEmitter({
+          debug: true,
+          env: { CVDIAG_DEBUG_ALLOW_LIST: "langgraph-typescript" },
+        }),
+    ).toThrow(/unresolved|production/);
+  });
+
+  it("allows DEBUG in a non-prod env with an allow-list", () => {
+    const emitter = new CvdiagEmitter({
+      debug: true,
+      env: {
+        SHOWCASE_ENV: "staging",
+        CVDIAG_DEBUG_ALLOW_LIST: "langgraph-typescript",
+      },
+    });
+    expect(emitter.tier).toBe("debug");
+  });
+});

showcase/integrations/_shared/ts/cvdiag-emitter.ts

@@ -0,0 +1,140 @@
+/**
+ * cvdiag-emitter.ts — the SHARED TypeScript CVDIAG emitter binding that the
+ * four TS-backed integrations import (langgraph-typescript, claude-sdk-typescript,
+ * mastra, built-in-agent). Plan unit: L0-F. Spec: 2026-06-18-flap-observability
+ * §5 (schema) + §6 (tiers / PII).
+ *
+ * ──────────────────────────────────────────────────────────────────────────
+ * SINGLE SOURCE OF TRUTH — this file RE-EXPORTS, it does NOT redefine.
+ *
+ * The canonical CVDIAG schema, edge-header allow/deny filter, PII scrub, and
+ * the `CvdiagEmitter` (tier resolution, fail-closed DEBUG guard, byte caps,
+ * bounded queue, UUIDv7 span/test minters) all live in L0-A under
+ * `showcase/harness/src/cvdiag/`. This binding is a thin barrel that pulls
+ * those symbols forward so the TS integrations have ONE import surface and so
+ * a schema change in L0-A propagates here automatically (no duplicate enum to
+ * drift). Re-exporting (not duplicating) is the whole point of the unit: the
+ * §5 "single source of truth" / "CI lint fails on drift" policy is only
+ * enforceable if every emitter shares the L0-A definitions.
+ *
+ * The relative path `../../../harness/src/cvdiag/` resolves as:
+ *   showcase/integrations/_shared/ts/  →  ../../../harness/src/cvdiag/
+ *   ( _shared/ts → _shared → integrations → showcase )/harness/src/cvdiag
+ * i.e. from this file up three levels to `showcase/`, then into `harness/`.
+ * The `.js` extensions match L0-A's ESM (`"type": "module"`, bundler module
+ * resolution) — at runtime under tsx / a bundler the `.js` specifier resolves
+ * to the `.ts` source, exactly as the harness's own `index.ts` barrel does.
+ *
+ * ──────────────────────────────────────────────────────────────────────────
+ * CROSS-CONTEXT RESOLUTION FOR L1-E (how a standalone TS integration's Docker
+ * build sees these files):
+ *
+ *   Each TS integration (langgraph-typescript, claude-sdk-typescript, mastra)
+ *   already vendors a sibling-directory `shared-tools/` into its build context
+ *   via a `COPY shared-tools/ ./shared-tools/` line in its Dockerfile (the
+ *   build context is the integration dir, so a sibling source tree is copied
+ *   in as a top-level dir, NOT imported across the repo). L1-E MUST use the
+ *   SAME mechanism for CVDIAG:
+ *
+ *     1. Stage `_shared/ts/cvdiag-emitter.ts` (this file, with the relative
+ *        re-exports flattened to point at a co-located copy of the L0-A
+ *        sources) AND the three L0-A sources it pulls from
+ *        (`schema.ts`, `edge-headers.ts`, `emit.ts`) into the integration's
+ *        build context — e.g. under `shared-tools/cvdiag/` or a dedicated
+ *        `_cvdiag/` dir — exactly as `shared-tools/` is copied today.
+ *     2. Add `COPY shared-tools/cvdiag/ ./shared-tools/cvdiag/` (or the chosen
+ *        path) to each integration Dockerfile, mirroring the existing
+ *        `COPY shared-tools/ ./shared-tools/` line.
+ *     3. The integration's CVDIAG wiring imports
+ *        `from "../../shared-tools/cvdiag/cvdiag-emitter"` (path per chosen
+ *        layout) rather than reaching across the monorepo — standalone npm
+ *        projects have no path alias back to `showcase/harness`.
+ *
+ *   This is the TS analogue of L0-C's Python `_shared/cvdiag_bootstrap`: a
+ *   COPY-into-context staging step, NOT a workspace/path-alias import. Within
+ *   THIS slot (the harness/worktree) the relative `../../../harness/...`
+ *   re-export resolves directly so the vitest suite runs against the real L0-A
+ *   sources; L1-E performs the COPY-staging flatten when packaging each
+ *   integration. A `bin/showcase cvdiag stage-ts` helper (or the existing
+ *   build wrapper) is the natural home for the copy, so the staging is a
+ *   build step and not hand-maintained per integration.
+ */
+
+// ── Schema (types, enums, validators, UUIDv7 regex) ─────────────────────────
+export {
+  SCHEMA_VERSION,
+  CVDIAG_LAYERS,
+  CVDIAG_OUTCOMES,
+  PROBE_BOUNDARIES,
+  BACKEND_BOUNDARIES,
+  AIMOCK_BOUNDARIES,
+  CVDIAG_DATA_PLANE_BOUNDARIES,
+  CVDIAG_ACCOUNTING_BOUNDARIES,
+  CVDIAG_BOUNDARIES,
+  EDGE_HEADER_KEYS,
+  TERMINATION_KINDS,
+  TEST_ID_REGEX,
+  ENVELOPE_KEYS,
+  BOUNDARY_METADATA_KEYS,
+  isValidTestId,
+  validateEnvelope,
+  validateMetadata,
+} from "../../../harness/src/cvdiag/schema.js";
+
+export type {
+  CvdiagLayer,
+  CvdiagOutcome,
+  CvdiagDataPlaneBoundary,
+  CvdiagAccountingBoundary,
+  CvdiagBoundary,
+  EdgeHeaders,
+  EdgeHeaderKey,
+  TerminationKind,
+  CvdiagEnvelope,
+  EnvelopeValidationResult,
+  MetadataValidationResult,
+} from "../../../harness/src/cvdiag/schema.js";
+
+// ── Edge-header allow/deny filter + PII scrub ───────────────────────────────
+export {
+  EDGE_HEADER_ALLOWLIST,
+  EDGE_HEADER_DENYLIST,
+  BEARER_TOKEN_REGEX,
+  SK_KEY_REGEX,
+  URL_USERINFO_REGEX,
+  SCRUB_REPLACEMENT,
+  scrubSecrets,
+  filterEdgeHeaders,
+} from "../../../harness/src/cvdiag/edge-headers.js";
+
+// ── Emitter (tier resolution, fail-closed DEBUG, byte caps, span/id minters) ─
+export {
+  CvdiagEmitter,
+  BYTE_CAP_BY_TIER,
+  QUEUE_CAP,
+  DEBUG_MAX_WALLCLOCK_MS,
+  DEBUG_MAX_EVENTS,
+  FLUSH_WINDOW_MS,
+  resolveEnvLabel,
+  mintTestId,
+  mintSpanId,
+} from "../../../harness/src/cvdiag/emit.js";
+
+export type {
+  CvdiagTier,
+  CvdiagPbWriter,
+  CvdiagEnv,
+  CvdiagEmitterOptions,
+  CvdiagEmitArgs,
+} from "../../../harness/src/cvdiag/emit.js";
+
+// ── Concrete writer-role PB writer (plain fetch; auth-with-password→Bearer) ──
+export {
+  CvdiagFetchPbWriter,
+  createCvdiagFetchPbWriterFromEnv,
+} from "../../../harness/src/cvdiag/pb-writer-fetch.js";
+
+export type {
+  FetchLike,
+  CvdiagFetchPbWriterOptions,
+} from "../../../harness/src/cvdiag/pb-writer-fetch.js";

showcase/integrations/_shared/ts/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["*.test.ts"],
+    environment: "node",
+    globals: false,
+  },
+});