@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/knowledge/search.mjs

@@ -0,0 +1,315 @@
+/**
+ * lib/knowledge/search.mjs — Self-knowledge search for Construct's own docs.
+ *
+ * Answers questions about what Construct is, how it works, and what it can do
+ * by reading Construct's own documentation tree. Designed for the
+ * `knowledge_search` MCP tool — no daemon, no network, no external deps.
+ *
+ * Sources searched (in priority order):
+ *   1. docs/concepts/*.md    — architecture, agents, gates, durable state
+ *   2. docs/start/*.mdx      — install + first task
+ *   3. docs/README.md        — docs index + contract
+ *   4. .cx/knowledge/        — operator-written internal docs
+ *   5. Any *.md in docs/cookbook/ — task-oriented recipes
+ *
+ * Retrieval strategy:
+ *   Token-based BM25-like scoring over 200-char chunks. Returns top-K chunks
+ *   with their source file and a relevance score. Pure text — no embeddings.
+ *
+ * @module lib/knowledge/search
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+import { homedir } from 'node:os';
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(MODULE_DIR, '..', '..');
+
+// ─── Source catalogue ────────────────────────────────────────────────────────
+
+/** Priority-ordered list of source files to search. */
+function buildSourceList(repoRoot = REPO_ROOT) {
+  const sources = [];
+
+  const priority = [
+    'docs/concepts/architecture.md',
+    'docs/concepts/agents-and-personas.mdx',
+    'docs/concepts/gates-and-enforcement.md',
+    'docs/concepts/beads-and-state.md',
+    'docs/concepts/prompt-surfaces.md',
+    'docs/concepts/knowledge-layout.md',
+    'docs/concepts/deployment-model.md',
+    'docs/concepts/embedding-boundary.md',
+    'docs/README.md',
+    'docs/start/install.mdx',
+    'docs/start/first-task.mdx',
+  ];
+
+  for (const rel of priority) {
+    const full = join(repoRoot, rel);
+    if (existsSync(full)) sources.push({ path: full, rel, priority: 1 });
+  }
+
+  // Cookbook recipes (task-oriented how-tos)
+  const cookbookDir = join(repoRoot, 'docs', 'cookbook');
+  if (existsSync(cookbookDir)) {
+    for (const file of readdirSync(cookbookDir)) {
+      if (file.endsWith('.md') || file.endsWith('.mdx')) {
+        const full = join(cookbookDir, file);
+        sources.push({ path: full, rel: `docs/cookbook/${file}`, priority: 2 });
+      }
+    }
+  }
+
+  // Operator internal knowledge
+  const knowledgeDirs = [
+    join(repoRoot, '.cx', 'knowledge', 'internal'),
+    join(repoRoot, '.cx', 'knowledge', 'reference'),
+    join(repoRoot, '.cx', 'knowledge', 'how-tos'),
+  ];
+  for (const dir of knowledgeDirs) {
+    if (!existsSync(dir)) continue;
+    for (const file of readdirSync(dir)) {
+      if (file.endsWith('.md')) {
+        const full = join(dir, file);
+        sources.push({ path: full, rel: relative(repoRoot, full), priority: 3 });
+      }
+    }
+  }
+
+  return sources;
+}
+
+// ─── Chunking ────────────────────────────────────────────────────────────────
+
+const CHUNK_CHARS = 400;
+const CHUNK_OVERLAP = 80;
+
+/**
+ * Split text into overlapping chunks, preserving markdown section boundaries
+ * where possible. Each chunk carries the nearest preceding heading as context.
+ */
+function chunkText(text, source) {
+  const chunks = [];
+  const lines = text.split('\n');
+  let heading = '';
+  let buffer = '';
+  let bufferStart = 0;
+
+  function flush(lineIdx) {
+    const trimmed = buffer.trim();
+    if (trimmed.length < 20) return;
+    chunks.push({ text: trimmed, heading, source, lineStart: bufferStart });
+    // Overlap: carry last CHUNK_OVERLAP chars into the next buffer
+    buffer = trimmed.length > CHUNK_OVERLAP ? trimmed.slice(-CHUNK_OVERLAP) : trimmed;
+    bufferStart = lineIdx;
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^#{1,3}\s/.test(line)) {
+      // Section boundary — flush current buffer, update heading
+      flush(i);
+      heading = line.replace(/^#+\s*/, '').trim();
+      buffer = line + '\n';
+      bufferStart = i;
+    } else {
+      buffer += line + '\n';
+      if (buffer.length >= CHUNK_CHARS) flush(i);
+    }
+  }
+  flush(lines.length);
+  return chunks;
+}
+
+// ─── Scoring ─────────────────────────────────────────────────────────────────
+
+/**
+ * Tokenise text into lowercase words, filtering stop words.
+ */
+const STOP = new Set(['the', 'a', 'an', 'and', 'or', 'is', 'are', 'it', 'in',
+  'of', 'to', 'for', 'with', 'on', 'at', 'by', 'from', 'that', 'this',
+  'be', 'as', 'was', 'will', 'can', 'its', 'not', 'you', 'your', 'how']);
+
+function tokenise(text) {
+  return text.toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, ' ')
+    .split(/\s+/)
+    .filter(t => t.length > 2 && !STOP.has(t));
+}
+
+/**
+ * BM25-inspired score: term frequency in chunk × inverse source frequency ×
+ * source priority bonus.
+ */
+function scoreChunk(chunk, queryTokens, idfMap) {
+  const chunkTokens = tokenise(chunk.text);
+  const tf = new Map();
+  for (const t of chunkTokens) tf.set(t, (tf.get(t) ?? 0) + 1);
+
+  let score = 0;
+  for (const qt of queryTokens) {
+    const freq = tf.get(qt) ?? 0;
+    if (freq > 0) {
+      const idf = idfMap.get(qt) ?? 1;
+      // BM25 k1=1.5, b=0 (no length normalisation — chunks are pre-sized)
+      score += idf * (freq * 2.5) / (freq + 1.5);
+    }
+    // Heading match bonus
+    if (chunk.heading.toLowerCase().includes(qt)) score += 2;
+    // File-name match bonus — rewards architecture.md for "architecture" queries
+    if (chunk.source.rel.toLowerCase().includes(qt)) score += 1.5;
+  }
+
+  // Priority bonus: priority-1 (architecture, README) wins decisively over how-tos.
+  // Multiplier is additive-style: add a flat boost so low-scoring priority-1 chunks
+  // aren't simply outscored by high-TF how-to chunks.
+  if (chunk.source.priority === 1) score += 3;
+  else if (chunk.source.priority === 2) score *= 1.05;
+
+  return score;
+}
+
+function buildIdf(queryTokens, chunks) {
+  const idf = new Map();
+  const N = chunks.length || 1;
+  for (const qt of queryTokens) {
+    const df = chunks.filter(c => tokenise(c.text).includes(qt)).length || 1;
+    idf.set(qt, Math.log((N - df + 0.5) / (df + 0.5) + 1));
+  }
+  return idf;
+}
+
+// ─── Observation store loader ────────────────────────────────────────────────
+
+/**
+ * Load distilled embed observations from `<rootDir>/.cx/observations/` and
+ * convert each one into a searchable text chunk. Returns [] if the directory
+ * doesn't exist or is empty.
+ */
+function buildObservationChunks(rootDir) {
+  const obsDir = join(rootDir, '.cx', 'observations');
+  if (!existsSync(obsDir)) return [];
+
+  const chunks = [];
+  let files;
+  try { files = readdirSync(obsDir).filter(f => f.endsWith('.json')); } catch { return []; }
+
+  for (const file of files) {
+    let obs;
+    try { obs = JSON.parse(readFileSync(join(obsDir, file), 'utf8')); } catch { continue; }
+    if (!obs || typeof obs !== 'object') continue;
+
+    const parts = [];
+    if (obs.summary) parts.push(obs.summary);
+    if (obs.content && obs.content !== obs.summary) parts.push(obs.content);
+    if (Array.isArray(obs.tags) && obs.tags.length) parts.push(`tags: ${obs.tags.join(', ')}`);
+
+    const text = parts.join('\n').trim();
+    if (!text) continue;
+
+    chunks.push({
+      text,
+      heading: obs.summary ?? '',
+      source: { path: join(obsDir, file), rel: `observations/${file}`, priority: 2 },
+      lineStart: 0,
+    });
+  }
+
+  return chunks;
+}
+
+
+/**
+ * @typedef {object} KnowledgeSearchResult
+ * @property {boolean} ok
+ * @property {string} query
+ * @property {number} totalChunks
+ * @property {SearchHit[]} hits
+ * @property {string[]} sources  — unique source files that contributed hits
+ * @property {string} [message]
+ */
+
+/**
+ * @typedef {object} SearchHit
+ * @property {string} text
+ * @property {string} heading
+ * @property {string} file    — repo-relative path
+ * @property {number} score
+ * @property {number} lineStart
+ */
+
+/**
+ * Search Construct's own documentation for content relevant to `query`.
+ *
+ * @param {object} opts
+ * @param {string} opts.query          — natural-language question or keyword
+ * @param {number} [opts.topK=5]       — max hits to return
+ * @param {number} [opts.minScore=0.1] — discard hits below this score
+ * @param {string} [opts.repoRoot]     — override repo root (for testing)
+ * @param {string} [opts.rootDir]      — data dir where .cx/observations/ lives (default: homedir())
+ * @returns {KnowledgeSearchResult}
+ */
+export function knowledgeSearch({ query, topK = 5, minScore = 0.1, repoRoot, rootDir } = {}) {
+  if (!query || typeof query !== 'string') {
+    return { ok: false, query: query ?? '', totalChunks: 0, hits: [], sources: [], message: 'query is required' };
+  }
+
+  const root = repoRoot ?? REPO_ROOT;
+  const dataDir = rootDir ?? (process.env.CX_DATA_DIR?.trim() || homedir());
+  const sources = buildSourceList(root);
+
+  // Build corpus from docs + operator knowledge
+  const allChunks = [];
+  for (const src of sources) {
+    let text = '';
+    try { text = readFileSync(src.path, 'utf8'); } catch { continue; }
+    const chunks = chunkText(text, src);
+    allChunks.push(...chunks);
+  }
+
+  // Add distilled embed observations from the data dir
+  const obsChunks = buildObservationChunks(dataDir);
+  allChunks.push(...obsChunks);
+
+  if (!allChunks.length) {
+    return { ok: false, query, totalChunks: 0, hits: [], sources: [], message: 'No documentation or observation sources found' };
+  }
+
+  const queryTokens = tokenise(query);
+  if (!queryTokens.length) {
+    return { ok: false, query, totalChunks: allChunks.length, hits: [], sources: [], message: 'Query contains no searchable terms after stop-word removal' };
+  }
+
+  const idf = buildIdf(queryTokens, allChunks);
+
+  const scored = allChunks
+    .map(chunk => ({ chunk, score: scoreChunk(chunk, queryTokens, idf) }))
+    .filter(({ score }) => score >= minScore)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, topK);
+
+  const hits = scored.map(({ chunk, score }) => ({
+    text: chunk.text,
+    heading: chunk.heading,
+    file: chunk.source.rel,
+    score: Math.round(score * 100) / 100,
+    lineStart: chunk.lineStart,
+  }));
+
+  const uniqueSources = [...new Set(hits.map(h => h.file))];
+
+  return {
+    ok: true,
+    query,
+    totalChunks: allChunks.length,
+    hits,
+    sources: uniqueSources,
+    message: hits.length
+      ? `Found ${hits.length} relevant excerpt${hits.length === 1 ? '' : 's'} across ${uniqueSources.length} source${uniqueSources.length === 1 ? '' : 's'}`
+      : 'No relevant content found — try broader terms',
+  };
+}

package/lib/knowledge/trends.mjs

@@ -0,0 +1,261 @@
+/**
+ * lib/knowledge/trends.mjs — Trend detection over the observation corpus.
+ *
+ * Surfaces:
+ *   - Recurring patterns: observations with similar embeddings that appear
+ *     multiple times across roles or sessions.
+ *   - Escalating risks: anti-pattern observations whose frequency is increasing
+ *     over time (more recent occurrences than older ones).
+ *   - Decision drift: decisions that have been re-opened or contradicted by
+ *     later observations.
+ *   - Hot topics: terms with the highest weighted TF across recent observations
+ *     (BM25-derived importance, recency-weighted).
+ *
+ * All detection is zero-dep and deterministic — no external API calls.
+ * Results are plain objects suitable for JSON serialisation and dashboard display.
+ */
+
+import { listObservations, getObservation } from '../observation-store.mjs';
+import { cosineSimilarity, tokenize } from '../storage/embeddings.mjs';
+import { embedSync as embedText } from '../storage/embeddings-legacy.mjs';
+
+const RECURRENCE_SIMILARITY_THRESHOLD = 0.40;
+const RECURRENCE_MIN_COUNT = 2;
+const ESCALATION_WINDOW_DAYS = 7;
+const HOT_TOPICS_LIMIT = 10;
+const TREND_LIMIT = 20;
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function daysSince(isoDate) {
+  if (!isoDate) return Infinity;
+  return (Date.now() - new Date(isoDate).getTime()) / 86_400_000;
+}
+
+function recencyWeight(isoDate, halfLifeDays = 14) {
+  const age = daysSince(isoDate);
+  return Math.pow(0.5, age / halfLifeDays);
+}
+
+// ── Recurring patterns ─────────────────────────────────────────────────────
+
+/**
+ * Cluster observations by embedding similarity. Returns groups of observations
+ * that are semantically similar (likely the same recurring pattern).
+ */
+function clusterBySimilarity(observations) {
+  const embedded = observations.map((obs) => ({
+    ...obs,
+    embedding: embedText(`${obs.summary || ''} ${obs.content || ''}`),
+  }));
+
+  const clusters = [];
+  const assigned = new Set();
+
+  for (let i = 0; i < embedded.length; i++) {
+    if (assigned.has(i)) continue;
+    const cluster = [embedded[i]];
+    assigned.add(i);
+    for (let j = i + 1; j < embedded.length; j++) {
+      if (assigned.has(j)) continue;
+      const sim = cosineSimilarity(embedded[i].embedding, embedded[j].embedding);
+      if (sim >= RECURRENCE_SIMILARITY_THRESHOLD) {
+        cluster.push(embedded[j]);
+        assigned.add(j);
+      }
+    }
+    if (cluster.length >= RECURRENCE_MIN_COUNT) {
+      clusters.push(cluster);
+    }
+  }
+
+  return clusters;
+}
+
+/**
+ * Detect recurring patterns: semantically similar observations seen across
+ * multiple sessions or roles.
+ *
+ * @returns {object[]} array of { summary, count, roles, categories, firstSeen, lastSeen, observations }
+ */
+export function detectRecurringPatterns(rootDir = process.cwd()) {
+  const all = listObservations(rootDir, {});
+  if (all.length === 0) return [];
+
+  const full = all.map((e) => ({ ...e, ...getObservation(rootDir, e.id) }));
+  const clusters = clusterBySimilarity(full);
+
+  return clusters
+    .map((cluster) => {
+      const roles = [...new Set(cluster.map((o) => o.role).filter(Boolean))];
+      const categories = [...new Set(cluster.map((o) => o.category).filter(Boolean))];
+      const dates = cluster.map((o) => o.createdAt).filter(Boolean).sort();
+      return {
+        type: 'recurring_pattern',
+        summary: cluster[0].summary || 'Recurring pattern',
+        count: cluster.length,
+        roles,
+        categories,
+        firstSeen: dates[0] || null,
+        lastSeen: dates[dates.length - 1] || null,
+        observations: cluster.map((o) => ({ id: o.id, summary: o.summary, role: o.role, createdAt: o.createdAt })),
+      };
+    })
+    .sort((a, b) => b.count - a.count)
+    .slice(0, TREND_LIMIT);
+}
+
+// ── Escalating risks ───────────────────────────────────────────────────────
+
+/**
+ * Detect escalating risks: anti-pattern observations where the frequency in
+ * the recent window is higher than the baseline rate.
+ *
+ * @returns {object[]} array of { summary, recentCount, olderCount, escalationScore, lastSeen }
+ */
+export function detectEscalatingRisks(rootDir = process.cwd()) {
+  const all = listObservations(rootDir, { category: 'anti-pattern' });
+  if (all.length === 0) return [];
+
+  const full = all.map((e) => ({ ...e, ...getObservation(rootDir, e.id) }));
+  const clusters = clusterBySimilarity(full);
+
+  return clusters
+    .map((cluster) => {
+      const recent = cluster.filter((o) => daysSince(o.createdAt) <= ESCALATION_WINDOW_DAYS);
+      const older = cluster.filter((o) => daysSince(o.createdAt) > ESCALATION_WINDOW_DAYS);
+      const recentRate = recent.length / Math.max(ESCALATION_WINDOW_DAYS, 1);
+      const olderSpan = Math.max(
+        cluster.reduce((span, o) => Math.max(span, daysSince(o.createdAt)), 0) - ESCALATION_WINDOW_DAYS,
+        1,
+      );
+      const olderRate = older.length / olderSpan;
+      const escalationScore = olderRate > 0 ? recentRate / olderRate : recentRate * 10;
+      const dates = cluster.map((o) => o.createdAt).filter(Boolean).sort();
+      return {
+        type: 'escalating_risk',
+        summary: cluster[0].summary || 'Escalating risk',
+        recentCount: recent.length,
+        olderCount: older.length,
+        escalationScore: Number(escalationScore.toFixed(2)),
+        lastSeen: dates[dates.length - 1] || null,
+        observations: cluster.map((o) => ({ id: o.id, summary: o.summary, createdAt: o.createdAt })),
+      };
+    })
+    .filter((r) => r.escalationScore > 1.5 && r.recentCount > 0)
+    .sort((a, b) => b.escalationScore - a.escalationScore)
+    .slice(0, TREND_LIMIT);
+}
+
+// ── Decision drift ─────────────────────────────────────────────────────────
+
+/**
+ * Detect decision drift: decision observations that are semantically similar
+ * to later anti-pattern or insight observations (suggesting the decision was
+ * questioned or reversed).
+ *
+ * @returns {object[]} array of { decision, conflictingObservations, driftScore }
+ */
+export function detectDecisionDrift(rootDir = process.cwd()) {
+  const decisions = listObservations(rootDir, { category: 'decision' })
+    .map((e) => ({ ...e, ...getObservation(rootDir, e.id) }));
+  const signals = listObservations(rootDir, {})
+    .filter((e) => ['anti-pattern', 'insight'].includes(e.category))
+    .map((e) => ({ ...e, ...getObservation(rootDir, e.id) }));
+
+  if (decisions.length === 0 || signals.length === 0) return [];
+
+  return decisions
+    .map((decision) => {
+      const decEmbed = embedText(`${decision.summary || ''} ${decision.content || ''}`);
+      const conflicting = signals
+        .filter((s) => new Date(s.createdAt || 0) > new Date(decision.createdAt || 0))
+        .map((s) => ({
+          ...s,
+          similarity: cosineSimilarity(decEmbed, embedText(`${s.summary || ''} ${s.content || ''}`)),
+        }))
+        .filter((s) => s.similarity >= 0.35)
+        .sort((a, b) => b.similarity - a.similarity)
+        .slice(0, 3);
+
+      if (conflicting.length === 0) return null;
+
+      const driftScore = conflicting.reduce((sum, s) => sum + s.similarity * recencyWeight(s.createdAt), 0);
+      return {
+        type: 'decision_drift',
+        decision: { id: decision.id, summary: decision.summary, createdAt: decision.createdAt },
+        conflictingObservations: conflicting.map((s) => ({
+          id: s.id,
+          summary: s.summary,
+          category: s.category,
+          similarity: Number(s.similarity.toFixed(3)),
+          createdAt: s.createdAt,
+        })),
+        driftScore: Number(driftScore.toFixed(3)),
+      };
+    })
+    .filter(Boolean)
+    .sort((a, b) => b.driftScore - a.driftScore)
+    .slice(0, TREND_LIMIT);
+}
+
+// ── Hot topics ─────────────────────────────────────────────────────────────
+
+/**
+ * Surface the most frequently discussed topics across recent observations,
+ * weighted by recency (recent = higher weight).
+ *
+ * @returns {object[]} array of { term, weightedFrequency, recentCount, totalCount }
+ */
+export function detectHotTopics(rootDir = process.cwd()) {
+  const all = listObservations(rootDir, {});
+  if (all.length === 0) return [];
+
+  const STOPWORDS = new Set([
+    'the', 'and', 'for', 'are', 'was', 'with', 'this', 'that', 'from',
+    'have', 'has', 'had', 'not', 'but', 'been', 'more', 'when', 'will',
+    'its', 'use', 'used', 'using', 'should', 'can', 'all', 'any', 'each',
+    'into', 'also', 'than', 'they', 'their', 'which', 'where', 'there',
+  ]);
+
+  const termStats = new Map();
+
+  for (const e of all) {
+    const full = getObservation(rootDir, e.id);
+    const text = `${full?.summary || ''} ${full?.content || ''}`;
+    const weight = recencyWeight(e.createdAt);
+    const isRecent = daysSince(e.createdAt) <= ESCALATION_WINDOW_DAYS;
+    const terms = [...new Set(tokenize(text).filter((t) => t.length >= 4 && !STOPWORDS.has(t)))];
+    for (const term of terms) {
+      const prev = termStats.get(term) || { weightedFrequency: 0, recentCount: 0, totalCount: 0 };
+      termStats.set(term, {
+        weightedFrequency: prev.weightedFrequency + weight,
+        recentCount: prev.recentCount + (isRecent ? 1 : 0),
+        totalCount: prev.totalCount + 1,
+      });
+    }
+  }
+
+  return [...termStats.entries()]
+    .map(([term, stats]) => ({ term, ...stats }))
+    .sort((a, b) => b.weightedFrequency - a.weightedFrequency)
+    .slice(0, HOT_TOPICS_LIMIT);
+}
+
+// ── Full trend report ──────────────────────────────────────────────────────
+
+/**
+ * Run all detectors and return a consolidated trend report.
+ *
+ * @param {string} rootDir
+ * @returns {{ recurringPatterns, escalatingRisks, decisionDrift, hotTopics, generatedAt }}
+ */
+export function buildTrendReport(rootDir = process.cwd()) {
+  return {
+    recurringPatterns: detectRecurringPatterns(rootDir),
+    escalatingRisks: detectEscalatingRisks(rootDir),
+    decisionDrift: detectDecisionDrift(rootDir),
+    hotTopics: detectHotTopics(rootDir),
+    generatedAt: new Date().toISOString(),
+  };
+}

package/lib/logger.mjs

@@ -0,0 +1,85 @@
+/**
+ * lib/logger.mjs — structured (JSON-line) logger for dashboard + server code.
+ *
+ * The CLI continues to use `println`/`errorln` for human-facing output. This
+ * logger is for non-interactive surfaces (HTTP server, embed daemon,
+ * supervised processes) where logs flow to a tail of stderr and a CloudWatch
+ * agent or `construct logs` reads them.
+ *
+ * Format: one JSON object per line, on stderr. Fields:
+ *
+ *   ts          ISO timestamp
+ *   level       'debug' | 'info' | 'warn' | 'error'
+ *   event       short stable identifier (e.g. 'http.request', 'auth.fail')
+ *   req_id      correlation id (defaults to a fresh hex string)
+ *   route       request path (when applicable)
+ *   actor       token label / user identity (when authenticated)
+ *   latency_ms  request duration (server only)
+ *   detail      arbitrary subobject for context
+ *
+ * Operators set `CONSTRUCT_LOG_LEVEL=debug` to see verbose lines; default
+ * level is `info`. `CONSTRUCT_LOG_PRETTY=1` switches to a human-readable
+ * format for local dev. Otherwise output is strictly JSONL.
+ */
+
+import { randomBytes } from 'node:crypto';
+
+const LEVELS = Object.freeze({ debug: 10, info: 20, warn: 30, error: 40 });
+
+function thresholdFromEnv(env) {
+  const v = (env.CONSTRUCT_LOG_LEVEL || 'info').toLowerCase();
+  return LEVELS[v] ?? LEVELS.info;
+}
+
+function isPretty(env) {
+  return env.CONSTRUCT_LOG_PRETTY === '1' || env.CONSTRUCT_LOG_PRETTY === 'true';
+}
+
+export function newRequestId() {
+  return randomBytes(8).toString('hex');
+}
+
+export function makeLogger({ env = process.env, stream = process.stderr } = {}) {
+  const threshold = thresholdFromEnv(env);
+  const pretty = isPretty(env);
+
+  function emit(level, event, fields = {}) {
+    if (LEVELS[level] < threshold) return;
+    const record = {
+      ts: new Date().toISOString(),
+      level,
+      event,
+      ...fields,
+    };
+    const line = pretty
+      ? `[${record.ts}] ${level.padEnd(5)} ${event}${
+          Object.keys(fields).length ? ' ' + JSON.stringify(fields) : ''
+        }\n`
+      : JSON.stringify(record) + '\n';
+    try { stream.write(line); } catch { /* logging is best-effort */ }
+  }
+
+  return {
+    debug: (event, fields) => emit('debug', event, fields),
+    info:  (event, fields) => emit('info',  event, fields),
+    warn:  (event, fields) => emit('warn',  event, fields),
+    error: (event, fields) => emit('error', event, fields),
+    child(extra = {}) {
+      return makeLogger.scoped(this, extra);
+    },
+  };
+}
+
+makeLogger.scoped = (parent, extra) => ({
+  debug: (event, fields = {}) => parent.debug(event, { ...extra, ...fields }),
+  info:  (event, fields = {}) => parent.info(event,  { ...extra, ...fields }),
+  warn:  (event, fields = {}) => parent.warn(event,  { ...extra, ...fields }),
+  error: (event, fields = {}) => parent.error(event, { ...extra, ...fields }),
+  child(more = {}) { return makeLogger.scoped(parent, { ...extra, ...more }); },
+});
+
+let defaultLogger = null;
+export function logger() {
+  if (!defaultLogger) defaultLogger = makeLogger();
+  return defaultLogger;
+}