@geraldmaron/construct 1.0.0 → 1.0.2

package/lib/cost.mjs

@@ -1,7 +1,10 @@
 /**
- * lib/cost.mjs — <one-line purpose>
+ * lib/cost.mjs — LLM token usage cost estimation and session budget tracking.
  *
- * <2–6 line summary: what it does, who calls it, key side effects.>
+ * Maps model IDs to per-token pricing from a static table (with OpenRouter
+ * and LiteLLM fallbacks), estimates call cost from usage objects, and
+ * accumulates session spend in ~/.cx/session-cost.json. Called by the
+ * telemetry pipeline and the MCP session_usage tool.
  */
 import { readFileSync, existsSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -47,17 +50,33 @@ export function normalizeCostEntry(entry = {}) {
     entry.completion_tokens,
     entry.completionTokens,
   );
+  const reasoningTokens = numberFrom(
+    entry.reasoning_tokens,
+    entry.reasoningTokens,
+    entry.completion_tokens_details?.reasoning_tokens,
+  );
+  const providerTotalTokens = numberFrom(
+    entry.total_tokens,
+    entry.totalTokens,
+    inputTokens + outputTokens + reasoningTokens,
+  );
+  const billedOutputTokens = outputTokens + reasoningTokens;
+  const billedTotalTokens = inputTokens + cacheReadInputTokens + cacheCreationInputTokens + billedOutputTokens;
 
   return {
     ...entry,
     inputTokens,
     outputTokens,
+    reasoningTokens,
     cacheReadInputTokens,
     cacheCreationInputTokens,
     cacheCreation5mInputTokens,
     cacheCreation1hInputTokens,
     processedInputTokens: inputTokens + cacheReadInputTokens + cacheCreationInputTokens,
-    totalTokens: inputTokens + outputTokens,
+    providerTotalTokens,
+    billedOutputTokens,
+    billedTotalTokens,
+    totalTokens: providerTotalTokens,
     costUsd: Number(entry.cost_usd ?? entry.costUsd ?? 0),
   };
 }
@@ -92,17 +111,23 @@ export function aggregateCostByAgent(entries) {
       interactions: 0,
       inputTokens: 0,
       outputTokens: 0,
+      reasoningTokens: 0,
       cacheReadInputTokens: 0,
       cacheCreationInputTokens: 0,
       processedInputTokens: 0,
+      providerTotalTokens: 0,
+      billedTotalTokens: 0,
       costUsd: 0,
     };
     acc.interactions += 1;
     acc.inputTokens += entry.inputTokens;
     acc.outputTokens += entry.outputTokens;
+    acc.reasoningTokens += entry.reasoningTokens;
     acc.cacheReadInputTokens += entry.cacheReadInputTokens;
     acc.cacheCreationInputTokens += entry.cacheCreationInputTokens;
     acc.processedInputTokens += entry.processedInputTokens;
+    acc.providerTotalTokens += entry.providerTotalTokens;
+    acc.billedTotalTokens += entry.billedTotalTokens;
     acc.costUsd += entry.costUsd;
     acc.cacheReadRate = acc.processedInputTokens > 0
       ? Number((acc.cacheReadInputTokens / acc.processedInputTokens).toFixed(3))
@@ -132,7 +157,47 @@ export function computeCacheStats(entries) {
   };
 }
 
-export function summarizeCostData(entries, { days, agent } = {}) {
+/**
+ * Map a model id to its provider id. Reads the model string the same way the
+ * model router does — prefix matches win, otherwise infer from naming family.
+ * Callers use this to look up per-provider billing-mode overrides so that
+ * subscription providers (Claude Pro, e.g.) contribute $0 to the headline
+ * "actual spend" while still reporting metered-equivalent for context.
+ */
+export function providerForModel(modelId) {
+  const id = String(modelId ?? '').toLowerCase();
+  if (!id) return 'unknown';
+  if (id.startsWith('openrouter/')) return 'openrouter';
+  if (id.startsWith('github-copilot/')) return 'github-copilot';
+  if (id.startsWith('ollama/')) return 'ollama';
+  if (id.startsWith('local/')) return 'local';
+  if (id.startsWith('anthropic/') || id.startsWith('claude-') || id.includes('/claude-')) return 'anthropic';
+  if (id.startsWith('openai/') || id.startsWith('gpt-') || /^o[3-9](-|$)/.test(id)) return 'openai';
+  if (id.startsWith('google/') || id.startsWith('gemini-')) return 'gemini';
+  if (id.startsWith('mistral/') || id.startsWith('mistralai/')) return 'mistral';
+  if (id.startsWith('groq/')) return 'groq';
+  return 'unknown';
+}
+
+/**
+ * Resolve billing mode for a given provider id. Per-provider override in
+ * `costs.providers.<id>.billingMode` wins; otherwise fall back to the global
+ * `costs.billingMode`. Default is 'metered' (treat $ figures as real spend)
+ * which is the safe assumption when nothing is declared.
+ */
+export function billingModeForProvider(providerId, costsConfig = {}) {
+  const perProvider = costsConfig?.providers?.[providerId]?.billingMode;
+  if (perProvider === 'subscription' || perProvider === 'metered' || perProvider === 'mixed') {
+    return perProvider;
+  }
+  const globalMode = costsConfig?.billingMode;
+  if (globalMode === 'subscription' || globalMode === 'metered' || globalMode === 'mixed') {
+    return globalMode;
+  }
+  return 'metered';
+}
+
+export function summarizeCostData(entries, { days, agent, costsConfig } = {}) {
   const cutoff = days ? new Date(Date.now() - days * 86_400_000).toISOString() : null;
   let filtered = cutoff ? entries.filter((e) => e.ts && e.ts >= cutoff) : entries;
   if (agent) filtered = filtered.filter((e) => (e.agent || 'orchestrator') === agent);
@@ -140,16 +205,53 @@ export function summarizeCostData(entries, { days, agent } = {}) {
   const normalized = filtered.map((entry) => normalizeCostEntry(entry));
   const totalInputTokens = normalized.reduce((s, e) => s + e.inputTokens, 0);
   const totalOutputTokens = normalized.reduce((s, e) => s + e.outputTokens, 0);
-  const totalTokens = totalInputTokens + totalOutputTokens;
+  const totalReasoningTokens = normalized.reduce((s, e) => s + e.reasoningTokens, 0);
+  const providerTotalTokens = normalized.reduce((s, e) => s + e.providerTotalTokens, 0);
+  const billedTotalTokens = normalized.reduce((s, e) => s + e.billedTotalTokens, 0);
   const totalCostUsd = normalized.reduce((s, e) => s + e.costUsd, 0);
   const cacheStats = computeCacheStats(normalized);
 
+  // Per-provider rollup. byProvider[id] = { providerId, billingMode, costUsd, ... }.
+  // meteredActualUsd sums only metered/mixed providers; meteredEquivalentUsd is
+  // the unconditional total (what the bill would be if everything were metered).
+  const byProvider = new Map();
+  for (const e of normalized) {
+    const providerId = providerForModel(e.model);
+    const bucket = byProvider.get(providerId) || {
+      providerId,
+      billingMode: billingModeForProvider(providerId, costsConfig),
+      interactions: 0,
+      costUsd: 0,
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheReadInputTokens: 0,
+      cacheCreationInputTokens: 0,
+    };
+    bucket.interactions += 1;
+    bucket.costUsd += e.costUsd;
+    bucket.inputTokens += e.inputTokens;
+    bucket.outputTokens += e.outputTokens;
+    bucket.cacheReadInputTokens += e.cacheReadInputTokens;
+    bucket.cacheCreationInputTokens += e.cacheCreationInputTokens;
+    byProvider.set(providerId, bucket);
+  }
+  const providerRollup = [...byProvider.values()]
+    .map((b) => ({ ...b, costUsd: Number(b.costUsd.toFixed(4)) }))
+    .sort((a, b) => b.costUsd - a.costUsd);
+  const meteredActualUsd = providerRollup
+    .filter((p) => p.billingMode !== 'subscription')
+    .reduce((s, p) => s + p.costUsd, 0);
+
   return {
     interactions: normalized.length,
     totalInputTokens,
     totalOutputTokens,
-    totalTokens,
+    totalReasoningTokens,
+    providerTotalTokens,
+    billedTotalTokens,
     totalCostUsd: Number(totalCostUsd.toFixed(4)),
+    meteredActualUsd: Number(meteredActualUsd.toFixed(4)),
+    meteredEquivalentUsd: Number(totalCostUsd.toFixed(4)),
     processedInputTokens: cacheStats.totalProcessedInputTokens,
     cacheReadInputTokens: cacheStats.totalCacheReadInputTokens,
     cacheCreationInputTokens: cacheStats.totalCacheCreationInputTokens,
@@ -159,11 +261,58 @@ export function summarizeCostData(entries, { days, agent } = {}) {
     cacheReadRate: cacheStats.cacheReadRate,
     cacheHitRate: cacheStats.cacheReadRate,
     byAgent: aggregateCostByAgent(normalized),
+    byProvider: providerRollup,
     days: days ?? null,
     agentFilter: agent ?? null,
   };
 }
 
+/**
+ * Estimate cache efficiency: compare expected vs actual cache usage.
+ *
+ * @param {object} data - normalized cost entry
+ * @param {number} expectedCacheableTokens - tokens we expected to cache
+ * @returns {{ efficiency: number, waste: number, hitRate: number }}
+ */
+export function computeCacheEfficiency(data, expectedCacheableTokens = 0) {
+  if (!data) return { efficiency: 0, waste: 0, hitRate: 0 };
+
+  const actualCacheRead = data.cacheReadInputTokens || 0;
+  const actualCacheWrite = data.cacheCreationInputTokens || 0;
+  const processedInput = data.processedInputTokens || data.inputTokens || 0;
+
+  const hitRate = processedInput > 0 ? actualCacheRead / processedInput : 0;
+  const writeRatio = expectedCacheableTokens > 0 ? actualCacheWrite / expectedCacheableTokens : 0;
+
+  // Efficiency: how close are we to expected cache usage?
+  const efficiency = expectedCacheableTokens > 0
+    ? Math.min(1, actualCacheRead / expectedCacheableTokens)
+    : 0;
+
+  // Waste: expected writes minus actual reads (over-cacheing)
+  const waste = Math.max(0, actualCacheWrite - actualCacheRead);
+
+  return {
+    efficiency: Math.round(efficiency * 100) / 100,
+    waste,
+    hitRate: Math.round(hitRate * 100) / 100,
+    expectedCacheableTokens,
+    actualCacheRead,
+    actualCacheWrite,
+  };
+}
+
+/**
+ * Batch compute cache efficiency for multiple entries.
+ *
+ * @param {Array} entries - normalized cost entries
+ * @param {number} expectedCacheableTokens
+ * @returns {Array}
+ */
+export function computeBatchCacheEfficiency(entries, expectedCacheableTokens = 0) {
+  return (entries || []).map(e => computeCacheEfficiency(e, expectedCacheableTokens));
+}
+
 export function formatCostReport(data, colors = {}) {
   const C = { bold: '', dim: '', reset: '', green: '', yellow: '', cyan: '', red: '', ...colors };
   const lines = [];
@@ -175,7 +324,8 @@ export function formatCostReport(data, colors = {}) {
   if (data.agentFilter) lines.push(`${C.dim}Agent filter: ${data.agentFilter}${C.reset}`);
 
   lines.push(`Interactions:    ${data.interactions}`);
-  lines.push(`Total tokens:    ${data.totalTokens.toLocaleString()} (${data.totalInputTokens.toLocaleString()} uncached in / ${data.totalOutputTokens.toLocaleString()} out)`);
+  lines.push(`Provider total:  ${Number(data.providerTotalTokens || 0).toLocaleString()} (${data.totalInputTokens.toLocaleString()} uncached in / ${data.totalOutputTokens.toLocaleString()} out / ${Number(data.totalReasoningTokens || 0).toLocaleString()} reasoning)`);
+  lines.push(`Billed total:    ${Number(data.billedTotalTokens || 0).toLocaleString()}`);
   lines.push(`Processed input: ${Number(data.processedInputTokens || data.totalInputTokens || 0).toLocaleString()}`);
 
   const readPct = ((data.cacheReadRate ?? data.cacheHitRate ?? 0) * 100).toFixed(1);
@@ -187,15 +337,16 @@ export function formatCostReport(data, colors = {}) {
   if (data.byAgent.length > 0) {
     lines.push('');
     lines.push('By Agent:');
-    lines.push(`  ${'Agent'.padEnd(28)} ${'Turns'.padStart(5)}  ${'Input tok'.padStart(10)}  ${'Cost'.padStart(8)}  ${'Share'.padStart(5)}  Cache`);
-    lines.push(`  ${'-'.repeat(28)} ${'-'.repeat(5)}  ${'-'.repeat(10)}  ${'-'.repeat(8)}  ${'-'.repeat(5)}  -----`);
+    lines.push(`  ${'Agent'.padEnd(28)} ${'Turns'.padStart(5)}  ${'Provider'.padStart(10)}  ${'Billed'.padStart(10)}  ${'Cost'.padStart(8)}  ${'Share'.padStart(5)}  Cache`);
+    lines.push(`  ${'-'.repeat(28)} ${'-'.repeat(5)}  ${'-'.repeat(10)}  ${'-'.repeat(10)}  ${'-'.repeat(8)}  ${'-'.repeat(5)}  -----`);
     for (const a of data.byAgent) {
       const sharePct = data.totalCostUsd > 0 ? Math.round((a.costUsd / data.totalCostUsd) * 100) : 0;
       const hitRate = Math.round((a.cacheReadRate || 0) * 100);
       const shareColor = sharePct >= 50 ? C.red : sharePct >= 25 ? C.yellow : '';
       lines.push(
         `  ${a.agent.padEnd(28)} ${String(a.interactions).padStart(5)}` +
-        `  ${a.inputTokens.toLocaleString().padStart(10)}` +
+        `  ${a.providerTotalTokens.toLocaleString().padStart(10)}` +
+        `  ${a.billedTotalTokens.toLocaleString().padStart(10)}` +
         `  ${'$' + a.costUsd.toFixed(4).padStart(7)}` +
         `  ${shareColor}${String(sharePct + '%').padStart(5)}${C.reset}` +
         `  ${hitRate}%`,
@@ -208,6 +359,16 @@ export function formatCostReport(data, colors = {}) {
     lines.push(`${C.dim}No cost data recorded yet. Token usage is logged at session end.${C.reset}`);
   }
 
+  // Cache efficiency metrics
+  if (data.expectedCacheableTokens && data.expectedCacheableTokens > 0) {
+    const efficiency = computeCacheEfficiency(data, data.expectedCacheableTokens);
+    lines.push('');
+    lines.push('Cache Efficiency:');
+    lines.push(`  Expected cacheable: ${Number(data.expectedCacheableTokens || 0).toLocaleString()} tokens`);
+    lines.push(`  Actual cache reads: ${Number(data.cacheReadInputTokens || 0).toLocaleString()}`);
+    lines.push(`  Efficiency: ${efficiency.efficiency * 100}% (${efficiency.waste > 0 ? `${efficiency.waste} over-cached` : 'optimal'})`);
+  }
+
   lines.push('');
   return lines.join('\n');
 }

package/lib/dashboard-static.mjs

@@ -0,0 +1,158 @@
+/**
+ * lib/dashboard-static.mjs — build and sync the dashboard static bundle.
+ *
+ * Keeps `dashboard/dist/` and `lib/server/static/` aligned so the HTTP server
+ * serves the current dashboard build from repo-owned assets.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+function walkFiles(rootDir, currentDir = rootDir) {
+  if (!fs.existsSync(currentDir)) return [];
+  const entries = [];
+  for (const name of fs.readdirSync(currentDir)) {
+    const fullPath = path.join(currentDir, name);
+    const stat = fs.statSync(fullPath);
+    if (stat.isDirectory()) {
+      entries.push(...walkFiles(rootDir, fullPath));
+    } else {
+      entries.push(path.relative(rootDir, fullPath));
+    }
+  }
+  return entries.sort();
+}
+
+function readBufferIfExists(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  return fs.readFileSync(filePath);
+}
+
+function compareTrees(sourceDir, targetDir) {
+  const sourceFiles = walkFiles(sourceDir);
+  const targetFiles = walkFiles(targetDir);
+  const sourceSet = new Set(sourceFiles);
+  const targetSet = new Set(targetFiles);
+  const copied = [];
+  const removed = [];
+
+  for (const relPath of sourceFiles) {
+    const source = readBufferIfExists(path.join(sourceDir, relPath));
+    const target = readBufferIfExists(path.join(targetDir, relPath));
+    if (!target || !source.equals(target)) copied.push(relPath);
+  }
+
+  for (const relPath of targetFiles) {
+    if (!sourceSet.has(relPath)) removed.push(relPath);
+  }
+
+  return {
+    copied,
+    removed,
+    sourceFiles,
+    targetFiles,
+    changed: copied.length > 0 || removed.length > 0,
+    inSync: copied.length === 0 && removed.length === 0,
+    sourceExists: fs.existsSync(sourceDir),
+  };
+}
+
+function ensureParentDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function removeEmptyDirs(dirPath, stopAt) {
+  let current = dirPath;
+  while (current.startsWith(stopAt) && current !== stopAt) {
+    if (!fs.existsSync(current)) {
+      current = path.dirname(current);
+      continue;
+    }
+    if (fs.readdirSync(current).length > 0) break;
+    fs.rmdirSync(current);
+    current = path.dirname(current);
+  }
+}
+
+export function getDashboardPaths({ rootDir = process.cwd() } = {}) {
+  return {
+    rootDir,
+    dashboardDir: path.join(rootDir, 'dashboard'),
+    sourceDir: path.join(rootDir, 'dashboard', 'dist'),
+    targetDir: path.join(rootDir, 'lib', 'server', 'static'),
+  };
+}
+
+export function getDashboardStaticStatus({ rootDir = process.cwd() } = {}) {
+  const { sourceDir, targetDir } = getDashboardPaths({ rootDir });
+  return compareTrees(sourceDir, targetDir);
+}
+
+export function syncDashboardStatic({ rootDir = process.cwd(), check = false } = {}) {
+  const { sourceDir, targetDir } = getDashboardPaths({ rootDir });
+  if (!fs.existsSync(sourceDir)) {
+    throw new Error(`Dashboard build output missing: ${sourceDir}`);
+  }
+
+  const status = compareTrees(sourceDir, targetDir);
+  if (check || !status.changed) return status;
+
+  for (const relPath of status.copied) {
+    const sourcePath = path.join(sourceDir, relPath);
+    const targetPath = path.join(targetDir, relPath);
+    ensureParentDir(targetPath);
+    fs.copyFileSync(sourcePath, targetPath);
+  }
+
+  for (const relPath of status.removed) {
+    const targetPath = path.join(targetDir, relPath);
+    fs.rmSync(targetPath, { force: true });
+    removeEmptyDirs(path.dirname(targetPath), targetDir);
+  }
+
+  return {
+    ...status,
+    inSync: true,
+  };
+}
+
+export function buildDashboardStatic({
+  rootDir = process.cwd(),
+  spawnSyncFn = spawnSync,
+} = {}) {
+  const { dashboardDir } = getDashboardPaths({ rootDir });
+  const result = spawnSyncFn('npm', ['run', 'build'], {
+    cwd: dashboardDir,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.status !== 0) {
+    throw new Error((result.stderr || result.stdout || 'dashboard build failed').trim());
+  }
+  return result;
+}
+
+export async function runDashboardStaticCli(args = [], { rootDir = process.cwd() } = {}) {
+  const build = args.includes('--build');
+  const check = args.includes('--check');
+
+  if (build) buildDashboardStatic({ rootDir });
+  const status = syncDashboardStatic({ rootDir, check });
+
+  if (check) {
+    if (status.changed) {
+      console.error('Dashboard static assets are out of date. Run `construct dashboard:sync --build`.');
+      return 1;
+    }
+    console.log('Dashboard static assets are up to date.');
+    return 0;
+  }
+
+  if (status.changed) {
+    console.log(`Dashboard static synced: ${status.copied.length} updated, ${status.removed.length} removed.`);
+  } else {
+    console.log('Dashboard static already up to date.');
+  }
+  return 0;
+}

package/lib/deployment-mode.mjs

@@ -0,0 +1,86 @@
+/**
+ * lib/deployment-mode.mjs — Construct deployment mode (solo | team | enterprise).
+ *
+ * Encodes the deployment posture the rest of the system reads to choose
+ * backends for the intake queue, memory, telemetry, and workers. The
+ * mode resolves with env > construct.config.json > default precedence
+ * (`getDeploymentMode(env, {cwd})`); the resource topology for each mode
+ * is derived here, not stored.
+ */
+import { loadProjectConfig } from './config/project-config.mjs';
+
+export const DEPLOYMENT_MODES = ['solo', 'team', 'enterprise'];
+export const DEFAULT_DEPLOYMENT_MODE = 'solo';
+
+export const DEPLOYMENT_MODE_ENV_KEY = 'CONSTRUCT_DEPLOYMENT_MODE';
+
+const RESOURCE_TOPOLOGY = {
+  solo: {
+    queue: 'filesystem',
+    memory: 'local',
+    database: 'optional',
+    telemetry: 'optional',
+    workers: 'local',
+    policy: 'lightweight',
+    mcp: 'direct',
+  },
+  team: {
+    queue: 'postgres',
+    memory: 'shared',
+    database: 'postgres',
+    telemetry: 'central',
+    workers: 'docker',
+    policy: 'server-side',
+    mcp: 'brokered',
+  },
+  enterprise: {
+    queue: 'postgres',
+    memory: 'shared',
+    database: 'postgres',
+    telemetry: 'central',
+    workers: 'isolated',
+    policy: 'enforceable',
+    mcp: 'brokered-signed',
+  },
+};
+
+const MODE_DESCRIPTIONS = {
+  solo: 'Individual usage. Filesystem queue, local repo state, optional Postgres/Docker/telemetry.',
+  team: 'Shared usage. Postgres queue, shared memory, Docker worker pool, central telemetry, brokered MCP.',
+  enterprise: 'Hardened usage. Adds tenant isolation, RBAC/ABAC scaffolding, isolated worker containers, signed MCP allowlists, mandatory audit on top of team.',
+};
+
+export function isValidDeploymentMode(value) {
+  return typeof value === 'string' && DEPLOYMENT_MODES.includes(value);
+}
+
+export function describeDeploymentMode(mode) {
+  return MODE_DESCRIPTIONS[mode] || '';
+}
+
+export function getDeploymentMode(env = process.env, { cwd } = {}) {
+  const raw = env?.[DEPLOYMENT_MODE_ENV_KEY];
+  if (raw) {
+    const trimmed = String(raw).trim().toLowerCase();
+    return isValidDeploymentMode(trimmed) ? trimmed : DEFAULT_DEPLOYMENT_MODE;
+  }
+  try {
+    const { config } = loadProjectConfig(cwd, env);
+    const fromConfig = config?.deployment?.mode;
+    if (typeof fromConfig === 'string' && isValidDeploymentMode(fromConfig)) return fromConfig;
+  } catch { /* loader is best-effort — fall through to default */ }
+  return DEFAULT_DEPLOYMENT_MODE;
+}
+
+export function resolveResourceMode(mode = DEFAULT_DEPLOYMENT_MODE) {
+  const topology = RESOURCE_TOPOLOGY[mode];
+  if (!topology) {
+    throw new Error(`Unknown deployment mode: ${mode}. Valid modes: ${DEPLOYMENT_MODES.join(', ')}`);
+  }
+  return { ...topology };
+}
+
+export function describeResourceLine(mode = DEFAULT_DEPLOYMENT_MODE) {
+  const r = resolveResourceMode(mode);
+  return `queue:${r.queue} · memory:${r.memory} · workers:${r.workers} · telemetry:${r.telemetry}`;
+}

package/lib/deprecate.mjs

@@ -0,0 +1,49 @@
+/**
+ * lib/deprecate.mjs — single-warning-per-process deprecation infrastructure.
+ *
+ * Usage:
+ *
+ *   import { deprecate } from './deprecate.mjs';
+ *
+ *   export function oldThing() {
+ *     deprecate('oldThing()', { since: '1.2.0', removeIn: '2.0.0', use: 'newThing()' });
+ *     return newThing();
+ *   }
+ *
+ * Each unique key (defaults to the symbol name) emits at most one stderr
+ * warning per process. Operators that want a strict signal can run with
+ * `CONSTRUCT_DEPRECATIONS=error` to make every deprecation fail-fast,
+ * which is useful in CI to flush out unintended deprecation usage before
+ * the next major release.
+ *
+ * The format is stable so it can be grepped from logs:
+ *
+ *   [construct] deprecated: <symbol> will be removed in v<X.0.0> — use <replacement>
+ */
+
+const SEEN = new Set();
+
+function shouldThrow(env) {
+  return env.CONSTRUCT_DEPRECATIONS === 'error';
+}
+
+export function deprecate(symbol, opts = {}) {
+  const env = opts.env || process.env;
+  const key = opts.key || symbol;
+  if (SEEN.has(key)) return;
+  SEEN.add(key);
+
+  const since = opts.since ? ` since v${opts.since}` : '';
+  const removeIn = opts.removeIn ? ` will be removed in v${opts.removeIn}` : '';
+  const use = opts.use ? ` — use ${opts.use}` : '';
+  const message = `[construct] deprecated: ${symbol}${since}${removeIn}${use}`;
+
+  if (shouldThrow(env)) {
+    throw new Error(message);
+  }
+  process.stderr.write(message + '\n');
+}
+
+export function _resetDeprecationsForTests() {
+  SEEN.clear();
+}