@geraldmaron/construct 1.0.3 → 1.0.4

package/lib/strategy-store.mjs

@@ -0,0 +1,371 @@
+/**
+ * lib/strategy-store.mjs — Multi-scope product strategy store.
+ *
+ * Strategy is organised by scope: product, technical, gtm, platform.
+ * Each scope lives in its own file under .cx/knowledge/decisions/strategy/{scope}.md.
+ * Strategy documents are NEVER auto-updated from ingested documents — they require
+ * an explicit writeStrategy() call from a privileged caller.
+ *
+ * In team/enterprise mode Postgres is the secondary store (best-effort). Each scope
+ * is stored as a separate row whose content is prefixed with `scope:{name}\n` so we
+ * can store and retrieve scopes without adding a new column to the existing schema.
+ *
+ * getStrategyDigest() / getStrategyDigestSync() return a compact block (≤ 500 tokens)
+ * suitable for injection into agent prompts. getStrategyDigestSync() is the file-only
+ * synchronous path required where await is not available (e.g. prompt assembly).
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { cxDir } from './paths.mjs';
+import { hasSqlStore } from './storage/sql-store.mjs';
+import { createSqlClient } from './storage/backend.mjs';
+
+const VALID_SCOPES = ['product', 'technical', 'gtm', 'platform'];
+const SCOPE_PREFIX = 'scope:';
+
+// ── Path helpers ──────────────────────────────────────────────────────────────
+
+export function strategyDir(env = process.env) {
+  return join(cxDir(), 'knowledge', 'decisions', 'strategy');
+}
+
+export function strategyFilePath(scope = 'product', env = process.env) {
+  return join(strategyDir(env), `${scope}.md`);
+}
+
+// ── Scope discovery ───────────────────────────────────────────────────────────
+
+/**
+ * Return scope names that have corresponding files in the strategy directory.
+ *
+ * @param {object} [env]
+ * @returns {string[]}
+ */
+export function listStrategyScopes(env = process.env) {
+  const dir = strategyDir(env);
+  if (!existsSync(dir)) return [];
+  try {
+    return readdirSync(dir)
+      .filter((f) => f.endsWith('.md'))
+      .map((f) => basename(f, '.md'));
+  } catch {
+    return [];
+  }
+}
+
+// ── Read helpers ──────────────────────────────────────────────────────────────
+
+/**
+ * Read one strategy scope from Postgres (primary) or file (fallback).
+ *
+ * @param {string} [scope]
+ * @param {object} [env]
+ * @returns {Promise<{ content: string, version: number, updatedAt: string, source: 'postgres'|'file'|'none', scope: string }>}
+ */
+export async function readStrategy(scope = 'product', env = process.env) {
+  if (hasSqlStore(env)) {
+    const client = createSqlClient(env);
+    try {
+      const project = env.CX_PROJECT || 'default';
+      const prefix = `${SCOPE_PREFIX}${scope}\n`;
+
+      // Rows stored with the scope prefix — match on content prefix
+      const rows = await client`
+        select content, version, updated_at
+        from construct_strategy
+        where project = ${project}
+          and content like ${prefix + '%'}
+        order by version desc
+        limit 1
+      `;
+
+      if (rows.length > 0) {
+        const row = rows[0];
+        return {
+          content: row.content.startsWith(prefix) ? row.content.slice(prefix.length) : row.content,
+          version: row.version,
+          updatedAt: row.updated_at instanceof Date ? row.updated_at.toISOString() : String(row.updated_at),
+          source: 'postgres',
+          scope,
+        };
+      }
+    } catch {
+      // Postgres unavailable — fall through to file
+    } finally {
+      if (client) await client.end({ timeout: 5 }).catch(() => {});
+    }
+  }
+
+  const filePath = strategyFilePath(scope, env);
+  if (existsSync(filePath)) {
+    const content = readFileSync(filePath, 'utf8');
+    return { content, version: 1, updatedAt: new Date().toISOString(), source: 'file', scope };
+  }
+
+  return { content: '', version: 0, updatedAt: new Date().toISOString(), source: 'none', scope };
+}
+
+/**
+ * Read all present strategy scopes.
+ *
+ * When Postgres is available it reads all rows for the project and parses scope
+ * from the prefix. Files are used as the fallback or supplement for scopes that
+ * have no Postgres row.
+ *
+ * @param {object} [env]
+ * @returns {Promise<Map<string, { content: string, version: number, updatedAt: string, source: string }>>}
+ */
+export async function readAllStrategies(env = process.env) {
+  const result = new Map();
+
+  if (hasSqlStore(env)) {
+    const client = createSqlClient(env);
+    try {
+      const project = env.CX_PROJECT || 'default';
+
+      // Fetch all rows — latest version per scope
+      const rows = await client`
+        select distinct on (
+          substring(content from 1 for position(E'\n' in content))
+        ) content, version, updated_at
+        from construct_strategy
+        where project = ${project}
+          and content like ${SCOPE_PREFIX + '%'}
+        order by
+          substring(content from 1 for position(E'\n' in content)),
+          version desc
+      `;
+
+      for (const row of rows) {
+        const firstNewline = row.content.indexOf('\n');
+        if (firstNewline === -1) continue;
+        const header = row.content.slice(0, firstNewline);
+        if (!header.startsWith(SCOPE_PREFIX)) continue;
+        const rowScope = header.slice(SCOPE_PREFIX.length);
+        const content = row.content.slice(firstNewline + 1);
+        result.set(rowScope, {
+          content,
+          version: row.version,
+          updatedAt: row.updated_at instanceof Date ? row.updated_at.toISOString() : String(row.updated_at),
+          source: 'postgres',
+        });
+      }
+    } catch {
+      // Fall through to file-based reads
+    } finally {
+      if (client) await client.end({ timeout: 5 }).catch(() => {});
+    }
+  }
+
+  // Supplement / replace with file-based reads for any scope present on disk
+  const fileScopes = listStrategyScopes(env);
+  for (const fileScope of fileScopes) {
+    if (result.has(fileScope)) continue;
+    const filePath = strategyFilePath(fileScope, env);
+    try {
+      const content = readFileSync(filePath, 'utf8');
+      result.set(fileScope, {
+        content,
+        version: 1,
+        updatedAt: new Date().toISOString(),
+        source: 'file',
+      });
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  return result;
+}
+
+// ── Digest helpers ────────────────────────────────────────────────────────────
+
+/**
+ * Parse markdown into sections split on ## headers.
+ *
+ * @param {string} content
+ * @returns {Array<{ header: string, body: string }>}
+ */
+function parseSections(content) {
+  const lines = content.split('\n');
+  const sections = [];
+  let current = null;
+
+  for (const line of lines) {
+    if (line.startsWith('## ')) {
+      if (current) sections.push(current);
+      current = { header: line.slice(3).trim(), body: '' };
+    } else if (current) {
+      current.body += line + '\n';
+    }
+  }
+  if (current) sections.push(current);
+  return sections;
+}
+
+/**
+ * Truncate a body to the first N sentences.
+ *
+ * @param {string} body
+ * @param {number} maxSentences
+ * @returns {string}
+ */
+function firstSentences(body, maxSentences = 2) {
+  const trimmed = body.trim();
+  if (!trimmed) return '';
+  const sentences = trimmed.match(/[^.!?\n]+[.!?\n]+/g) || [trimmed];
+  return sentences.slice(0, maxSentences).join(' ').trim();
+}
+
+/**
+ * Build a compact markdown block from a single scope's content.
+ *
+ * @param {string} scopeName
+ * @param {string} content
+ * @param {number} charBudget — remaining character budget; mutated by reference via returned delta
+ * @returns {{ text: string, charsUsed: number }}
+ */
+function buildScopeBlock(scopeName, content, charBudget) {
+  const sections = parseSections(content);
+  if (!sections.length) return { text: '', charsUsed: 0 };
+
+  const lines = [`### ${scopeName}`];
+  let used = scopeName.length + 5;
+
+  for (const { header, body } of sections) {
+    if (used >= charBudget) break;
+    const excerpt = firstSentences(body, 2);
+    const line = excerpt ? `**${header}:** ${excerpt}` : `**${header}**`;
+    lines.push(line);
+    used += line.length + 1;
+  }
+
+  const text = lines.join('\n');
+  return { text, charsUsed: used };
+}
+
+/**
+ * Return a compact strategy digest (≤ 500 tokens) for agent prompt injection.
+ *
+ * Reads all present scopes asynchronously. Returns empty string when no scopes exist.
+ *
+ * @param {object} [env]
+ * @returns {Promise<string>}
+ */
+export async function getStrategyDigest(env = process.env) {
+  try {
+    const all = await readAllStrategies(env);
+    if (!all.size) return '';
+
+    const TOKEN_LIMIT = 500;
+    let charBudget = TOKEN_LIMIT * 4;
+    const parts = ['## Active strategy'];
+
+    for (const [scopeName, { content }] of all) {
+      if (!content) continue;
+      const { text, charsUsed } = buildScopeBlock(scopeName, content, charBudget);
+      if (text) {
+        parts.push(text);
+        charBudget -= charsUsed;
+      }
+      if (charBudget <= 0) break;
+    }
+
+    return parts.length > 1 ? parts.join('\n') : '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Synchronous file-only strategy digest for prompt-composer.js.
+ *
+ * Reads all .md files present in the strategy directory directly. Never reads
+ * Postgres. Returns empty string when the directory is absent or empty.
+ *
+ * @param {object} [env]
+ * @returns {string}
+ */
+export function getStrategyDigestSync(env = process.env) {
+  try {
+    const dir = strategyDir(env);
+    if (!existsSync(dir)) return '';
+
+    const files = readdirSync(dir).filter((f) => f.endsWith('.md'));
+    if (!files.length) return '';
+
+    const TOKEN_LIMIT = 500;
+    let charBudget = TOKEN_LIMIT * 4;
+    const parts = ['## Active strategy'];
+
+    for (const file of files) {
+      if (charBudget <= 0) break;
+      const scopeName = basename(file, '.md');
+      let content;
+      try {
+        content = readFileSync(join(dir, file), 'utf8');
+      } catch {
+        continue;
+      }
+      if (!content) continue;
+      const { text, charsUsed } = buildScopeBlock(scopeName, content, charBudget);
+      if (text) {
+        parts.push(text);
+        charBudget -= charsUsed;
+      }
+    }
+
+    return parts.length > 1 ? parts.join('\n') : '';
+  } catch {
+    return '';
+  }
+}
+
+// ── Write ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Write a strategy scope to file (always) and Postgres (best-effort if available).
+ *
+ * The scope parameter defaults to 'product'. When writing to Postgres the content
+ * is prefixed with `scope:{name}\n` to allow per-scope storage without a schema change.
+ *
+ * @param {string} content
+ * @param {string} [scope]
+ * @param {object} [opts]
+ * @param {string} [opts.updatedBy]
+ * @param {object} [opts.env]
+ */
+export async function writeStrategy(content, scope = 'product', { updatedBy, env = process.env } = {}) {
+  const filePath = strategyFilePath(scope, env);
+  const dir = strategyDir(env);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(filePath, content, 'utf8');
+
+  if (!hasSqlStore(env)) return;
+
+  const client = createSqlClient(env);
+  try {
+    const project = env.CX_PROJECT || 'default';
+    const scopedContent = `${SCOPE_PREFIX}${scope}\n${content}`;
+    const prefix = `${SCOPE_PREFIX}${scope}\n`;
+
+    const existing = await client`
+      select version from construct_strategy
+      where project = ${project}
+        and content like ${prefix + '%'}
+      order by version desc
+      limit 1
+    `;
+    const nextVersion = existing.length > 0 ? existing[0].version + 1 : 1;
+
+    await client`
+      insert into construct_strategy (project, content, version, updated_by)
+      values (${project}, ${scopedContent}, ${nextVersion}, ${updatedBy ?? null})
+    `;
+  } catch {
+    // Best-effort Postgres write — file write already succeeded
+  } finally {
+    if (client) await client.end({ timeout: 5 }).catch(() => {});
+  }
+}

package/lib/telemetry/backends/local.mjs

@@ -7,11 +7,12 @@
 
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
 
 export const name = 'local';
 
-const TRACES_DIR = join(homedir(), '.cx', 'traces');
+function tracesDir(env = process.env) {
+  return join(env.CX_TOOLKIT_DIR || process.cwd(), '.cx', 'traces');
+}
 
 export async function isAvailable() {
   return true;
@@ -25,7 +26,8 @@ export async function isAvailable() {
  * @returns {Promise<object[]>}
  */
 export async function listTraces(teamId, windowMs) {
-  if (!existsSync(TRACES_DIR)) return [];
+  const dir = tracesDir();
+  if (!existsSync(dir)) return [];
 
   const since = Date.now() - windowMs;
   const files = readdirSync(TRACES_DIR)
@@ -36,7 +38,7 @@ export async function listTraces(teamId, windowMs) {
 
   const traces = [];
   for (const file of files) {
-    const lines = readFileSync(join(TRACES_DIR, file), 'utf8')
+      const lines = readFileSync(join(dir, file), 'utf8')
       .split('\n')
       .filter(Boolean);
     for (const line of lines) {

package/lib/telemetry/client.mjs

@@ -0,0 +1,185 @@
+/**
+ * lib/telemetry/client.mjs — shared local-first telemetry adapter.
+ *
+ * Local JSONL trace capture is the default. Remote export is opt-in through
+ * CONSTRUCT_TRACE_BACKEND and never throws into callers.
+ */
+import { existsSync, mkdirSync, appendFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+import { createIngestClient } from './ingest.mjs';
+
+const DEFAULT_MAX_BATCH = 50;
+
+export const TRACE_BACKENDS = new Set(['local', 'langfuse', 'http', 'otel', 'none']);
+
+function cleanUrl(value = '') {
+  return String(value || '').replace(/\/$/, '');
+}
+
+function inferRemoteBackend(env) {
+  const url = cleanUrl(env.CONSTRUCT_TELEMETRY_URL);
+  const hasKeys = Boolean(env.CONSTRUCT_TELEMETRY_PUBLIC_KEY && env.CONSTRUCT_TELEMETRY_SECRET_KEY);
+  if (!url) return 'local';
+  return hasKeys ? 'langfuse' : 'http';
+}
+
+export function resolveTraceBackend(env = process.env) {
+  const raw = String(env.CONSTRUCT_TRACE_BACKEND || '').trim().toLowerCase();
+  if (!raw) return inferRemoteBackend(env);
+  if (raw === 'remote' || raw === 'telemetry') return inferRemoteBackend(env);
+  if (raw === 'off') return 'none';
+  return TRACE_BACKENDS.has(raw) ? raw : 'local';
+}
+
+export function telemetryProviderLabel(env = process.env) {
+  return env.CONSTRUCT_TELEMETRY_PROVIDER || resolveTraceBackend(env);
+}
+
+function resolveProjectRoot({ rootDir, env = process.env } = {}) {
+  return rootDir || env.CX_TOOLKIT_DIR || env.PWD || process.cwd();
+}
+
+function localTraceEnabled(env = process.env) {
+  return env.CONSTRUCT_TRACE_LOCAL_ENABLED !== '0';
+}
+
+function traceShard() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function appendLocalTelemetry(type, body, { rootDir, env = process.env, onError = () => {} } = {}) {
+  if (!localTraceEnabled(env)) return;
+  const projectRoot = resolveProjectRoot({ rootDir, env });
+  const dir = join(projectRoot, '.cx', 'traces');
+  try {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    appendFileSync(join(dir, `${traceShard()}.jsonl`), `${JSON.stringify({
+      traceId: body?.traceId || body?.id || randomUUID(),
+      spanId: body?.id || randomUUID(),
+      eventType: `telemetry.${type}`,
+      telemetryType: type,
+      project: body?.metadata?.project || body?.project || null,
+      role: body?.metadata?.agent || body?.metadata?.agentName || body?.name || null,
+      metadata: body?.metadata || {},
+      input: body?.input,
+      output: body?.output,
+      createdAt: body?.timestamp || body?.startTime || new Date().toISOString(),
+    })}\n`, 'utf8');
+  } catch (err) {
+    onError(err);
+  }
+}
+
+function buildOtlpPayload(batch) {
+  return {
+    resourceSpans: [{
+      resource: {
+        attributes: [
+          { key: 'service.name', value: { stringValue: 'construct' } },
+        ],
+      },
+      scopeSpans: [{
+        scope: { name: 'construct.telemetry' },
+        spans: batch.map((item) => {
+          const body = item.body || {};
+          const startedAt = Date.parse(body.startTime || body.timestamp || item.timestamp || new Date().toISOString());
+          const endedAt = Date.parse(body.endTime || body.startTime || body.timestamp || item.timestamp || new Date().toISOString());
+          return {
+            traceId: String(body.traceId || body.id || item.id).replace(/[^a-fA-F0-9]/g, '').padEnd(32, '0').slice(0, 32),
+            spanId: String(body.id || item.id).replace(/[^a-fA-F0-9]/g, '').padEnd(16, '0').slice(0, 16),
+            name: body.name || item.type,
+            kind: 1,
+            startTimeUnixNano: String(Math.max(0, startedAt) * 1_000_000),
+            endTimeUnixNano: String(Math.max(0, endedAt) * 1_000_000),
+            attributes: [
+              { key: 'construct.telemetry.type', value: { stringValue: item.type } },
+              ...(body.model ? [{ key: 'llm.model_name', value: { stringValue: String(body.model) } }] : []),
+            ],
+          };
+        }),
+      }],
+    }],
+  };
+}
+
+function createRemoteClient({ backend, env, fetchImpl, onError }) {
+  if (backend === 'local' || backend === 'none') return null;
+  if (backend === 'otel') {
+    const endpoint = cleanUrl(env.CONSTRUCT_OTEL_EXPORTER_OTLP_ENDPOINT);
+    return createIngestClient({
+      baseUrl: endpoint,
+      endpointPath: endpoint.endsWith('/v1/traces') ? '' : '/v1/traces',
+      authMode: 'none',
+      payloadBuilder: buildOtlpPayload,
+      fetchImpl,
+      onError,
+      maxBatch: DEFAULT_MAX_BATCH,
+    });
+  }
+  if (backend === 'http') {
+    return createIngestClient({
+      baseUrl: cleanUrl(env.CONSTRUCT_TELEMETRY_URL),
+      endpointPath: '/ingest',
+      authMode: 'none',
+      fetchImpl,
+      onError,
+      maxBatch: DEFAULT_MAX_BATCH,
+    });
+  }
+  return createIngestClient({
+    baseUrl: cleanUrl(env.CONSTRUCT_TELEMETRY_URL),
+    publicKey: env.CONSTRUCT_TELEMETRY_PUBLIC_KEY,
+    secretKey: env.CONSTRUCT_TELEMETRY_SECRET_KEY,
+    fetchImpl,
+    onError,
+    maxBatch: DEFAULT_MAX_BATCH,
+  });
+}
+
+export function createTelemetryClient({
+  env = process.env,
+  rootDir,
+  fetchImpl = globalThis.fetch,
+  onError = () => {},
+  localWrites = true,
+} = {}) {
+  const backend = resolveTraceBackend(env);
+  const remote = createRemoteClient({ backend, env, fetchImpl, onError });
+  const localAvailable = localWrites && localTraceEnabled(env);
+  const remoteAvailable = Boolean(remote?.available);
+
+  function emit(type, body) {
+    if (!body) return;
+    if (localWrites) appendLocalTelemetry(type, body, { rootDir, env, onError });
+    if (!remoteAvailable) return;
+    try {
+      remote[type]?.(body);
+    } catch (err) {
+      onError(err);
+    }
+  }
+
+  return {
+    backend,
+    provider: telemetryProviderLabel(env),
+    available: localAvailable || remoteAvailable,
+    localAvailable,
+    remoteAvailable,
+    remoteStatus: remoteAvailable ? 'configured' : backend === 'local' || backend === 'none' ? backend : 'unconfigured',
+    trace: (body) => emit('trace', body),
+    traceUpdate: (body) => emit('traceUpdate', body),
+    generation: (body) => emit('generation', body),
+    generationUpdate: (body) => emit('generationUpdate', body),
+    span: (body) => emit('span', body),
+    spanUpdate: (body) => emit('spanUpdate', body),
+    event: (body) => emit('event', body),
+    score: (body) => emit('score', body),
+    async flush() {
+      if (remote?.flush) await remote.flush();
+    },
+    queueSize: () => remote?.queueSize?.() ?? 0,
+  };
+}

package/lib/telemetry/ingest.mjs

@@ -35,17 +35,21 @@ export function createIngestClient({
   ).replace(/\/$/, ''),
   publicKey = process.env.CONSTRUCT_TELEMETRY_PUBLIC_KEY,
   secretKey = process.env.CONSTRUCT_TELEMETRY_SECRET_KEY,
+  endpointPath = '/api/public/ingestion',
+  authMode = 'basic',
+  payloadBuilder = (batch) => ({ batch }),
   flushIntervalMs = DEFAULT_FLUSH_INTERVAL_MS,
   maxBatch = DEFAULT_MAX_BATCH,
   onError = () => {},
   fetchImpl = globalThis.fetch,
 } = {}) {
-  const available = Boolean(publicKey && secretKey && fetchImpl);
+  const requiresBasicAuth = authMode === 'basic';
+  const available = Boolean(baseUrl && fetchImpl && (!requiresBasicAuth || (publicKey && secretKey)));
   const queue = [];
   let flushTimer = null;
   let inflight = Promise.resolve();
 
-  const authHeader = available
+  const authHeader = available && requiresBasicAuth
     ? `Basic ${Buffer.from(`${publicKey}:${secretKey}`).toString('base64')}`
     : '';
 
@@ -61,14 +65,17 @@ export function createIngestClient({
   async function flushBatch() {
     if (!available || queue.length === 0) return;
     const batch = queue.splice(0, maxBatch);
-    const payload = JSON.stringify({ batch });
+    const payload = JSON.stringify(payloadBuilder(batch));
     const prev = inflight;
     inflight = (async () => {
       try { await prev; } catch { /* ignore prior */ }
       try {
-        const res = await fetchImpl(`${baseUrl}/api/public/ingestion`, {
+        const res = await fetchImpl(`${baseUrl}${endpointPath}`, {
           method: 'POST',
-          headers: { Authorization: authHeader, 'Content-Type': 'application/json' },
+          headers: {
+            ...(authHeader ? { Authorization: authHeader } : {}),
+            'Content-Type': 'application/json',
+          },
           body: payload,
         });
         if (!res.ok && res.status !== 207) {
@@ -104,6 +111,7 @@ export function createIngestClient({
     span: (body) => push('span-create', body),
     spanUpdate: (body) => push('span-update', body),
     event: (body) => push('event-create', body),
+    score: (body) => push('score-create', body),
     async flush() {
       if (flushTimer) { clearTimeout(flushTimer); flushTimer = null; }
       while (queue.length > 0) await flushBatch();

package/lib/telemetry/team-rollup.mjs

@@ -3,22 +3,29 @@
  *
  * Groups agent traces by teamId (stamped by construct headhunt at overlay creation),
  * computes per-team success rates, latency, handoff counts, and common blockers.
- * Backend is selected via CONSTRUCT_TRACE_BACKEND env var (default: remote).
+ * Backend is selected via CONSTRUCT_TRACE_BACKEND env var (default: local).
  * Called by 'construct team review'.
  */
 
 import * as remoteBackend from './backends/remote.mjs';
+import * as localBackend from './backends/local.mjs';
 import * as noopBackend from './backends/noop.mjs';
+import { resolveTraceBackend } from './client.mjs';
 
 const BACKENDS = {
+  local: localBackend,
+  langfuse: remoteBackend,
+  http: remoteBackend,
+  otel: noopBackend,
   remote: remoteBackend,
+  none: noopBackend,
   noop: noopBackend,
 };
 
 const DEFAULT_WINDOW_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 
 function resolveBackend() {
-  const name = process.env.CONSTRUCT_TRACE_BACKEND ?? 'remote';
+  const name = resolveTraceBackend(process.env);
   const backend = BACKENDS[name];
   if (!backend) throw new Error(`Unknown trace backend: ${name}. Available: ${Object.keys(BACKENDS).join(', ')}`);
   return backend;