sonorance 0.1.0-beta.4.1

package/src/sources.mjs

@@ -0,0 +1,80 @@
+/**
+ * sources.mjs — parse/serialize the project's categorized grounding sources.
+ *
+ * `.sonorance/sources.md` is a user-editable Markdown source of truth. Stable starter
+ * sections teach the evidence model; custom `##` sections also survive CLI rewrites.
+ * Each source remains one list item:
+ *
+ *     - <location> — <description>
+ */
+
+export const SOURCE_SECTIONS = [
+  { id: 'product-strategy', title: 'Product & strategy', note: 'Product briefs, roadmaps, objectives, research plans, and decision context.' },
+  { id: 'code-delivery', title: 'Code & delivery', note: 'Codebases, release notes, issue trackers, experiments, incidents, and delivery history.' },
+  { id: 'metrics-data', title: 'Metrics & data', note: 'Analytics, warehouse queries, dashboards, billing data, and operational metrics.' },
+  { id: 'customer-voice', title: 'Customer voice', note: 'Support, interviews, surveys, reviews, research, and sales conversations.' },
+  { id: 'go-to-market', title: 'Go-to-market & public presence', note: 'Websites, documentation, pricing, CRM, campaigns, blogs, and status pages.' },
+  { id: 'other', title: 'Other', note: 'Relevant grounding that does not fit the sections above.' },
+];
+
+const slug = (value) => String(value || '').toLowerCase().replace(/&/g, ' and ').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+const knownById = new Map(SOURCE_SECTIONS.map(s => [s.id, s]));
+const knownByTitle = new Map(SOURCE_SECTIONS.map(s => [slug(s.title), s]));
+
+export function normalizeSourceSection(value) {
+  const key = slug(value);
+  const known = knownById.get(key) || knownByTitle.get(key);
+  return known
+    ? { section: known.id, sectionTitle: known.title }
+    : { section: key || 'other', sectionTitle: String(value || '').trim() || 'Other' };
+}
+
+const HEADER = `# Sources
+
+Grounding for this project. Add one source per line as \`- <location> — <what it is and why it matters>\`.
+Locations may be URLs, local paths, or git URLs. Edit freely; section headings and list items are picked up on the next run.
+`;
+
+function parseItem(item) {
+  let location = item, description = '';
+  const sep = item.match(/\s+(?:—|–|-{1,2})\s+/);
+  if (sep) { location = item.slice(0, sep.index); description = item.slice(sep.index + sep[0].length).trim(); }
+  location = location.trim().replace(/^<(.*)>$/, '$1').trim();
+  return { location, description };
+}
+
+export function parseSources(text) {
+  const out = [];
+  let current = normalizeSourceSection('other');
+  for (const raw of String(text || '').split(/\r?\n/)) {
+    const heading = /^\s*##\s+(.+?)\s*$/.exec(raw);
+    if (heading) { current = normalizeSourceSection(heading[1]); continue; }
+    const item = /^\s*[-*]\s+(.+?)\s*$/.exec(raw);
+    if (!item) continue;
+    const { location, description } = parseItem(item[1]);
+    if (location) out.push({ location, description, ...current });
+  }
+  return out;
+}
+
+export function serializeSources(list) {
+  const grouped = new Map(SOURCE_SECTIONS.map(s => [s.id, []]));
+  const customTitles = new Map();
+  for (const source of list || []) {
+    if (!source?.location) continue;
+    const normalized = normalizeSourceSection(source.sectionTitle || source.section || 'other');
+    const section = knownById.has(normalized.section) ? normalized.section : normalized.section || 'other';
+    if (!grouped.has(section)) grouped.set(section, []);
+    if (!knownById.has(section)) customTitles.set(section, normalized.sectionTitle);
+    grouped.get(section).push(source);
+  }
+  const blocks = SOURCE_SECTIONS.map(section => {
+    const lines = grouped.get(section.id).map(s => `- ${s.location}${s.description ? ` — ${s.description}` : ''}`);
+    return `## ${section.title}\n\n_${section.note}_` + (lines.length ? `\n\n${lines.join('\n')}` : '');
+  });
+  for (const [section, title] of customTitles) {
+    const lines = grouped.get(section).map(s => `- ${s.location}${s.description ? ` — ${s.description}` : ''}`);
+    blocks.push(`## ${title}\n\n${lines.join('\n')}`);
+  }
+  return `${HEADER}\n${blocks.join('\n\n')}\n`;
+}

package/src/telemetry-schema.mjs

@@ -0,0 +1,187 @@
+/**
+ * telemetry-schema.mjs — the SINGLE SOURCE OF TRUTH for Sonorance's telemetry contract.
+ *
+ * Everything the product may ever send is described here, once:
+ *   - TELEMETRY_EVENTS   — the fixed, content-free event allow-list (discrete occurrences).
+ *   - TELEMETRY_METRICS  — the aggregate instruments (high-frequency signals rolled up).
+ *   - TELEMETRY_RESOURCE — the identity/context attributes that ride EVERY signal.
+ *   - the allow-listed `props` keys + a value guard that keeps content off the wire.
+ *
+ * The telemetry client (`telemetry.mjs`) enforces the allow-list + value guard at emit time;
+ * schema breaches are dropped rather than sent, and tests keep the contract synchronized.
+ *
+ * On the wire this maps to OpenTelemetry (OTLP): events → log records, metrics → OTel metrics,
+ * a session → a trace, each command/stage → a span (see `otlp.mjs`, implementation spec §2.1).
+ * There is NO free-text field: the schema itself is the privacy guarantee (never a prompt,
+ * completion, file name, path, title, or body — only enums, numbers, and booleans).
+ */
+
+// Bumped when the shape changes so a backend/collector can tolerate old clients.
+export const TELEMETRY_SCHEMA_VERSION = 3;
+
+// ---- events: the fixed vocabulary (discrete, low-frequency occurrences) --------------------
+// Each entry: [name, description]. Kept sorted by category, then name.
+export const TELEMETRY_EVENTS = [
+  // lifecycle
+  ['install.created', 'First run on this install — a fresh anonymous install_id was minted.'],
+  ['session.start', 'A process/serve session began (the active-user + retention backbone).'],
+  ['telemetry.enabled', 'The user turned telemetry on (consent granted).'],
+  ['telemetry.disabled', 'The user turned telemetry off (consent withdrawn).'],
+  // project
+  ['project.init', 'A folder was initialised as a project (sonorance/deliberate init).'],
+  ['context.ready', 'The project context was filled in (deliberate init prompt fulfilled).'],
+  ['source.added', 'A grounding source was added.'],
+  ['source.removed', 'A grounding source was removed.'],
+  // case funnel
+  ['case.created', 'A case was created.'],
+  ['case.stage.completed', 'A case analysis stage advanced {stage}.'],
+  ['case.completed', 'A case reached its final analysis stage.'],
+  ['case.scored', 'A case was scored by the evaluator {verdict, refreshed, independent}; the first score is the case value moment and independence is a quality guardrail.'],
+  ['prototype.gate.shown', 'The prototype gate was shown for a completed case.'],
+  ['prototype.built', 'A prototype was produced for a case {surface}.'],
+  ['prototype.viewed', 'A prototype was opened/viewed.'],
+  ['prototype.approved', 'A prototype was approved.'],
+  // other value moments
+  ['brief.completed', 'A landscape brief was produced.'],
+  ['matchup.completed', 'A competitive matchup was produced {refreshed}.'],
+  ['readout.completed', 'A product readout was produced.'],
+  // comment bridge
+  ['comment.created', 'An in-record comment was created.'],
+  ['comment.resolved', 'An in-record comment was resolved {revised}.'],
+  ['address.drained', 'A batch of open comments was drained by the agent {count}.'],
+  // app / editor
+  ['record.opened', 'A semantic record (case/brief/readout/matchup) was opened {kind} — never a raw file read.'],
+  ['vault.switched', 'The active vault/project was switched.'],
+  ['serve.started', 'The local editor server started.'],
+  ['ui.action', 'A named UI affordance was used {area, action, value?} — enums only, never a file name.'],
+  ['ui.page.viewed', 'A utility page was viewed {page} — inbox, settings, or feedback.'],
+  // generic + errors + feedback
+  ['command.run', 'A CLI/skill command ran {name, ok, duration_ms} — the universal seam event.'],
+  ['error', 'An error occurred {class, command, stage} — never message content or a stack trace.'],
+  ['feedback', 'One user-authored, explicitly-submitted feedback record — the only event that may carry user-consented text.'],
+];
+
+// ---- metrics: aggregate instruments (high-frequency signals; only totals/distribution matter) --
+// Each entry: [name, description]. Flushed as one sparse rollup, not one event per occurrence.
+export const TELEMETRY_METRICS = [
+  ['files_opened', 'Counter — raw file opens/reads in the editor (navigation volume; no names/paths).'],
+  ['autosaves', 'Counter — autosave/file-write occurrences (no content, no path).'],
+  ['searches', 'Counter — in-vault searches run (never the query text).'],
+  ['inp_ms', 'Histogram — interaction-to-next-paint / latency distribution (p50/p75/p95).'],
+  ['open_tabs', 'Gauge — current open tab count.'],
+  ['explorer_files', 'Gauge — current Markdown file count in the Explorer; never names or paths.'],
+  ['explorer_folders', 'Gauge — current visible folder count in the Markdown-only Explorer.'],
+  ['project_cases', 'Gauge — current Deliberate case count in the anonymous project.'],
+  ['project_briefs', 'Gauge — current Deliberate brief count in the anonymous project.'],
+  ['project_readouts', 'Gauge — current Deliberate product readout count in the anonymous project.'],
+  ['project_matchups', 'Gauge — current Deliberate matchup count in the anonymous project.'],
+  ['project_open_comments', 'Gauge — current unresolved comment count in the anonymous project.'],
+];
+
+// ---- resource attributes: identity + coarse context that rides EVERY signal ------------------
+// Each entry: [key, description]. These become OTel resource attributes (feedback carries them too).
+export const TELEMETRY_RESOURCE = [
+  ['telemetry_schema', 'Numeric telemetry contract version, so collectors and dashboards can separate incompatible clients.'],
+  ['install_id', 'Anonymous, rotatable per-install id (the correlation key ↔ feedback). Pure random, no PII.'],
+  ['project_key', 'Anonymous, random per-vault key (committed → team-shared). NOT the folder-name slug.'],
+  ['session_id', 'Ephemeral per-process/serve id (maps to the OTLP trace id). Never persisted.'],
+  ['product', 'deliberate | sonorance — which product experience emitted the signal.'],
+  ['version', 'The product version — rides every signal so version adoption/regressions are queryable.'],
+  ['surface', 'cli | ui — the choke point the signal came from (skill usage rides the cli seam).'],
+  ['os', 'Coarse OS platform (darwin | linux | win32).'],
+  ['os_major', 'Coarse OS major version (a number).'],
+  ['node_major', 'Coarse Node.js major version (a number).'],
+  ['harness', 'Coarse agent-harness hint (e.g. copilot-cli) | null.'],
+];
+
+// The combined, tagged rows the grammar doc embeds (one flat list; category in the description).
+export const TELEMETRY_ROWS = [
+  ...TELEMETRY_EVENTS.map(([n, d]) => [n, `event · ${d}`]),
+  ...TELEMETRY_METRICS.map(([n, d]) => [n, `metric · ${d}`]),
+  ...TELEMETRY_RESOURCE.map(([n, d]) => [n, `attribute · ${d}`]),
+];
+
+// ---- derived registries + enforcement --------------------------------------------------------
+export const EVENT_NAMES = new Set(TELEMETRY_EVENTS.map(([n]) => n));
+export const METRIC_NAMES = new Set(TELEMETRY_METRICS.map(([n]) => n));
+export const COUNTER_METRIC_NAMES = new Set(['files_opened', 'autosaves', 'searches']);
+export const HISTOGRAM_METRIC_NAMES = new Set(['inp_ms']);
+export const GAUGE_METRIC_NAMES = new Set([
+  'open_tabs', 'explorer_files', 'explorer_folders',
+  'project_cases', 'project_briefs', 'project_readouts', 'project_matchups', 'project_open_comments',
+]);
+export const RESOURCE_KEYS = new Set(TELEMETRY_RESOURCE.map(([n]) => n));
+
+export const isEvent = (name) => EVENT_NAMES.has(name);
+export const isMetric = (name) => METRIC_NAMES.has(name);
+export const isCounterMetric = (name) => COUNTER_METRIC_NAMES.has(name);
+export const isHistogramMetric = (name) => HISTOGRAM_METRIC_NAMES.has(name);
+export const isGaugeMetric = (name) => GAUGE_METRIC_NAMES.has(name);
+
+// The ONLY property keys any event may carry — all low-cardinality enums / numbers / bools.
+// Anything not on this list is dropped before the event is buffered (content can never ride a
+// stray key). Kept deliberately small; extend it (and the doc) when a new typed event needs a key.
+export const ALLOWED_PROP_KEYS = new Set([
+  'name',        // a command name from the fixed CLI/skill grammar
+  'stage',       // a pipeline stage enum (frame | shape | launch | …)
+  'verdict',     // go | no-go | … enum
+  'refreshed',   // bool (matchup refreshed in place or case re-scored)
+  'independent', // bool (score came from an isolated evaluator, not a same-session fallback)
+  'revised',     // bool (comment resolved with an edit)
+  'count',       // number
+  'kind',        // a record kind (case | brief | readout | matchup) — low cardinality
+  'surface',     // a primary-surface slug (cli | api | mcp | …) for prototypes
+  'area',        // ui.action area enum
+  'action',      // ui.action action enum
+  'value',       // ui.action value enum (e.g. theme name)
+  'page',        // ui.page.viewed page enum
+  'class',       // an error CLASS (constructor name), never the message
+  'command',     // the command an error/telemetry occurred under (fixed grammar token)
+  'category',    // feedback category enum
+  'rating',      // feedback sentiment/rating (number | up | down | excited | null)
+  'ok',          // bool
+  'duration_ms', // number
+]);
+
+// Low-cardinality enums for the one named UI-interaction event (`ui.action`). Kept tight so the
+// UI can never smuggle a label/path/free-text through `area`/`action`/`value`.
+export const UI_ACTION_AREAS = new Set(['explorer', 'toc', 'toolbar', 'settings', 'editor']);
+export const UI_ACTION_ACTIONS = new Set([
+  'collapse-all', 'comments', 'create-file', 'create-folder', 'delete-file', 'delete-folder',
+  'diff', 'expand-all', 'feedback-open', 'mode-change', 'move', 'new-record', 'proto-open',
+  'rename', 'search-open', 'theme-change', 'toc-nav', 'vault-switch',
+]);
+export const UI_ACTION_VALUES = new Set(['system', 'light', 'dark', 'doc', 'diff']);
+export const UI_PAGE_NAMES = new Set(['inbox', 'settings', 'feedback']);
+
+// Feedback categories + ratings (also the UI panel's fixed choices).
+export const FEEDBACK_CATEGORIES = new Set(['bug', 'idea', 'praise', 'question', 'other']);
+
+// A value is safe to send only if it is a boolean, a finite number, null, or a SHORT enum-like
+// string (no spaces beyond a single word/slug, no quotes/paths/newlines). This is the second
+// guard after the key allow-list: it stops a content-y string riding an allow-listed key.
+const ENUMISH = /^[A-Za-z0-9][A-Za-z0-9._\-]{0,39}$/;   // ≤40 chars, slug/enum shape, no spaces
+export function isSafeValue(v) {
+  if (v == null) return true;
+  if (typeof v === 'boolean') return true;
+  if (typeof v === 'number') return Number.isFinite(v);
+  if (typeof v === 'string') return ENUMISH.test(v);
+  return false;
+}
+
+// Keep only allow-listed keys whose values pass the guard. Returns a fresh, content-free object.
+// Unknown keys and unsafe values are dropped silently (defence in depth, not an error path).
+export function sanitizeProps(props) {
+  const out = {};
+  if (!props || typeof props !== 'object') return out;
+  for (const [k, v] of Object.entries(props)) {
+    if (!ALLOWED_PROP_KEYS.has(k)) continue;
+    if (!isSafeValue(v)) continue;
+    if (k === 'area' && !UI_ACTION_AREAS.has(v)) continue;
+    if (k === 'action' && !UI_ACTION_ACTIONS.has(v)) continue;
+    if (k === 'value' && !UI_ACTION_VALUES.has(v)) continue;
+    if (k === 'page' && !UI_PAGE_NAMES.has(v)) continue;
+    out[k] = v;
+  }
+  return out;
+}

package/src/telemetry.mjs

@@ -0,0 +1,390 @@
+/**
+ * telemetry.mjs — the platform telemetry CLIENT: the client IS the collector.
+ *
+ * On the user's machine it buffers, enforces the content-free allow-list, batches, and exports
+ * over OTLP — never blocking a command or a render (INP/snappiness is a hard priority). Shared by
+ * every surface: the `sonorance` CLI and server (and, via the CLI seam, the skills). Design
+ * (implementation spec §2):
+ *
+ *   1. Kill switches at the SOURCE — consent off, DO_NOT_TRACK, CI, SONORANCE_TELEMETRY=off, or a
+ *      committed `.sonorance/config.json` telemetry:false → emit nothing.
+ *   2. Local JSONL FIRST — every event is appended to `~/.sonorance/telemetry.jsonl` (the audit
+ *      trail + `telemetry show` source) before any network. Files-first: you can read what we send.
+ *   3. Allow-list + value guard (telemetry-schema.mjs) — unknown event names and content-y values
+ *      are dropped, so nothing off-schema can ever reach the wire.
+ *   4. Batch-flush, fire-and-forget — flush on a threshold / timer / clean exit with a short
+ *      timeout; failure is silent (the JSONL keeps the record). High-frequency signals are
+ *      aggregated into metrics (counters/gauges/histograms), never one event each.
+ *   5. Local-test switch — SONORANCE_TELEMETRY=console|debug prints the exact OTLP payloads
+ *      instead of sending, so the founder can verify the pipeline on a dev machine.
+ *
+ * On the wire it is OTLP (see otlp.mjs): a session → a trace, events → logs, rollups → metrics.
+ */
+import { appendFile, readFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import {
+  EVENT_NAMES, isCounterMetric, isHistogramMetric, isGaugeMetric,
+  sanitizeProps, TELEMETRY_SCHEMA_VERSION,
+} from './telemetry-schema.mjs';
+import { ensureInstallId, projectKey, ensureProjectKey, sessionId, coarseEnv, getConsent, sonoranceHome } from './identity.mjs';
+import { encodeLogs, encodeMetrics, encodeTraces, traceIdOf, sendOtlp } from './otlp.mjs';
+import { azureConnectionString, azureTrackUrl, encodeEnvelopes, sendAzure, DEFAULT_CONNECTION_STRING } from './azure-monitor.mjs';
+
+// Default posture when the user has not yet chosen (transparent opt-out — implementation spec §6,
+// the recommended model). Flip to false here for opt-in; it is the single switch for that policy.
+const DEFAULT_CONSENT_ON = true;
+
+// Fixed histogram bounds (ms) for the latency/INP distribution.
+const INP_BOUNDS = [50, 100, 200, 300, 500, 1000, 2000, 5000];
+
+const auditPath = () => join(sonoranceHome(), 'telemetry.jsonl');
+
+// ---- consent / mode resolution ----------------------------------------------
+// Returns 'off' | 'console' | 'otlp'. Env overrides win (dev/CI + the local-test switch), then the
+// committed team policy, then the user's home-config consent, then the default posture.
+export function resolveMode(vaultDir) {
+  const env = String(process.env.SONORANCE_TELEMETRY || '').toLowerCase();
+  if (['off', '0', 'false', 'no', 'none'].includes(env)) return 'off';
+  if (['console', 'debug', 'print', 'stdout'].includes(env)) return 'console';
+  const forcedOn = ['on', '1', 'true', 'otlp'].includes(env);
+  if (!forcedOn) {
+    if (/^(1|true)$/i.test(String(process.env.DO_NOT_TRACK || ''))) return 'off';
+    if (process.env.CI && String(process.env.CI).toLowerCase() !== 'false') return 'off';
+    if (vaultDir && committedPolicyOff(vaultDir)) return 'off';
+    const consent = getConsent();
+    if (consent === false) return 'off';
+    if (consent === undefined && !DEFAULT_CONSENT_ON) return 'off';
+  }
+  return 'otlp';
+}
+// A committed `.sonorance/config.json` `telemetry:false` is a team/enterprise kill switch that
+// overrides an individual's consent (but env `on` can still force it for the founder's own tests).
+function committedPolicyOff(vaultDir) {
+  try { return JSON.parse(readFileSync(join(vaultDir, '.sonorance', 'config.json'), 'utf8')).telemetry === false; }
+  catch { return false; }
+}
+
+// ---- transport resolution ----------------------------------------------------
+// WHERE a live signal goes (mode decides WHETHER; this decides WHERE). Precedence:
+//   1. an explicit Azure connection string (env) → export straight to that App Insights ("Breeze");
+//   2. an explicit OTLP endpoint (env) → OTLP/HTTP to it (a self-hosted collector / any OTLP
+//      backend);
+//   3. the official package's release-configured connection string → zero-config Azure export;
+//   4. nothing configured → local-only: the JSONL audit keeps everything, nothing is sent
+//      (fail-closed; the app never blindly POSTs to a probably-dead localhost).
+export function resolveTransport() {
+  const envCs = process.env.APPLICATIONINSIGHTS_CONNECTION_STRING || process.env.SONORANCE_AZURE_CONNECTION_STRING;
+  if (envCs) { const endpoint = azureTrackUrl(envCs); if (endpoint) return { kind: 'azure', endpoint, label: 'Azure Monitor (Application Insights)' }; }
+  const otlp = process.env.SONORANCE_OTLP_ENDPOINT || process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+  if (otlp) return { kind: 'otlp', endpoint: otlp.replace(/\/+$/, ''), label: `OTLP → ${otlp}` };
+  if (DEFAULT_CONNECTION_STRING) {
+    const endpoint = azureTrackUrl(DEFAULT_CONNECTION_STRING);
+    if (endpoint) return { kind: 'azure', endpoint, label: 'Azure Monitor (Application Insights, release default)' };
+  }
+  return { kind: 'none', endpoint: null, label: 'local only (no destination configured)' };
+}
+
+// Build the OTLP [signal, payload] jobs from the neutral drained buffers (the vendor-agnostic wire).
+function otlpJobs({ events, spans, counters, gauges, histograms, window, resource }) {
+  const jobs = [];
+  if (events.length) jobs.push(['logs', encodeLogs(events.map(e => ({ name: e.name, ts: e.ts, attributes: e.props, traceId: traceIdOf(resource.session_id) })), resource)]);
+  if (spans.length) jobs.push(['traces', encodeTraces(spans, resource)]);
+  if (counters.length || gauges.length || histograms.length) jobs.push(['metrics', encodeMetrics({
+    counters: counters.map(c => ({ ...c, attributes: {} })),
+    gauges: gauges.map(g => ({ ...g, attributes: {} })),
+    histograms,
+  }, resource, window)]);
+  return jobs;
+}
+
+// ---- the client -------------------------------------------------------------
+function createClient() {
+  const state = {
+    ctx: { surface: 'cli', product: 'sonorance', version: '0', vaultDir: null },
+    resource: null,
+    mode: 'off',
+    events: [],                                          // pending log records: { name, ts, props }
+    spans: [],                                           // pending trace spans
+    counters: new Map(),                                 // metricName → integer count
+    gauges: new Map(),                                   // metricName → latest current value
+    histos: new Map(),                                   // metricName → number[]
+    windowStart: Date.now(),
+    session: null,                                       // the root session span
+    flushTimer: null,
+    configured: false,
+    generation: 0,                                      // increments when the vault context changes
+  };
+
+  const buildResource = () => {
+    const { surface, product, version, vaultDir } = state.ctx;
+    const { id: install_id } = ensureInstallId();
+    // Mint the project_key lazily (only for a real vault) so a random-but-committed key exists.
+    const project_key = vaultDir ? (projectKey(vaultDir) || ensureProjectKey(vaultDir)) : null;
+    return {
+      telemetry_schema: TELEMETRY_SCHEMA_VERSION,
+      install_id, project_key, session_id: sessionId(),
+      product, version: String(version || '0'), surface,
+      ...coarseEnv(),
+    };
+  };
+
+  const on = () => state.mode !== 'off';
+
+  const scheduleFlush = () => {
+    if (state.mode === 'off' || state.flushTimer) return;
+    state.flushTimer = setTimeout(() => { state.flushTimer = null; flush().catch(() => {}); }, 5000);
+    state.flushTimer.unref?.();
+  };
+
+  // Append to the local JSONL audit trail — the offline record you can read. Never awaited on the
+  // hot path; failure is ignored (a home-dir write problem must never break a command).
+  const audit = (line) => { appendFile(auditPath(), JSON.stringify(line) + '\n').catch(() => {}); };
+
+  function configure({ surface, product, version, vaultDir } = {}) {
+    if (vaultDir !== undefined && vaultDir !== state.ctx.vaultDir) state.generation++;
+    if (surface) state.ctx.surface = surface;
+    if (product) state.ctx.product = product;
+    if (version != null) state.ctx.version = version;
+    if (vaultDir !== undefined) state.ctx.vaultDir = vaultDir;
+    state.mode = resolveMode(state.ctx.vaultDir);
+    state.resource = on() ? buildResource() : null;
+    // Open the session trace span once, when first enabled.
+    if (on() && !state.session) {
+      const traceId = traceIdOf(state.resource.session_id) || randomBytes(16).toString('hex');
+      state.session = { name: 'session', traceId, spanId: randomBytes(8).toString('hex'), start: Date.now(), attributes: {} };
+    }
+    state.configured = true;
+    return state.mode;
+  }
+
+  // Re-resolve consent/mode at runtime (after a `telemetry on/off` toggle) without a restart.
+  function refresh() {
+    const was = on();
+    state.mode = resolveMode(state.ctx.vaultDir);
+    if (on() && !state.resource) state.resource = buildResource();
+    if (!was && on() && !state.session) {
+      const traceId = traceIdOf(state.resource.session_id) || randomBytes(16).toString('hex');
+      state.session = { name: 'session', traceId, spanId: randomBytes(8).toString('hex'), start: Date.now(), attributes: {} };
+    }
+    return state.mode;
+  }
+
+  // Emit one discrete event. Off-schema names and content-y props are dropped (never sent).
+  function emit(name, props = {}) {
+    if (!state.configured) configure();
+    if (!on()) return null;
+    if (!EVENT_NAMES.has(name)) return null;             // not on the allow-list → drop
+    const clean = sanitizeProps(props);
+    if (name === 'ui.action' && (!clean.area || !clean.action)) return null;
+    if (name === 'ui.page.viewed' && !clean.page) return null;
+    const event_id = `ev_${randomBytes(8).toString('hex')}`;
+    const eventProps = { ...clean, event_id };
+    const rec = { type: name, ts: Date.now(), schema: TELEMETRY_SCHEMA_VERSION, event_id, ...state.resource, props: clean };
+    audit(rec);
+    state.events.push({ name, ts: rec.ts, props: eventProps });
+    if (state.events.length >= 50) flush().catch(() => {}); else scheduleFlush();
+    return rec;
+  }
+
+  // Aggregate content-free signals: interval counters, current-value gauges, or histogram samples.
+  function count(metric, n = 1) {
+    if (!state.configured) configure();
+    if (!on() || !isCounterMetric(metric)) return;
+    state.counters.set(metric, (state.counters.get(metric) || 0) + (Number(n) || 0));
+    scheduleFlush();
+  }
+  function gauge(metric, value) {
+    if (!state.configured) configure();
+    const v = Number(value);
+    if (!on() || !isGaugeMetric(metric) || !Number.isFinite(v) || v < 0) return;
+    state.gauges.set(metric, v);
+    scheduleFlush();
+  }
+  function observe(metric, value) {
+    if (!state.configured) configure();
+    if (!on() || !isHistogramMetric(metric)) return;
+    const v = Number(value); if (!Number.isFinite(v)) return;
+    if (!state.histos.has(metric)) state.histos.set(metric, []);
+    state.histos.get(metric).push(v);
+    scheduleFlush();
+  }
+
+  // A command/stage span (a child of the session trace) — the "user journey" tree. Returns a
+  // handle whose .end() closes it; a no-op object when telemetry is off.
+  function startSpan(name, attributes = {}) {
+    if (!state.configured) configure();
+    if (!on() || !state.session) return { end() {} };
+    const span = {
+      name, traceId: state.session.traceId, spanId: randomBytes(8).toString('hex'),
+      parentSpanId: state.session.spanId, start: Date.now(), attributes: sanitizeProps(attributes), ok: true,
+    };
+    return {
+      end(extra = {}) {
+        span.end = Date.now();
+        span.attributes = { ...span.attributes, ...sanitizeProps(extra) };
+        if (extra && extra.ok === false) span.ok = false;
+        state.spans.push(span);
+        scheduleFlush();
+      },
+    };
+  }
+
+  // Drain the accumulators into the NEUTRAL rollup shape (transport-agnostic), reset the window.
+  function drainRaw() {
+    const events = state.events.splice(0);
+    const spans = state.spans.splice(0);
+    const counters = [...state.counters].map(([name, value]) => ({ name, value }));
+    const gauges = [...state.gauges].map(([name, value]) => ({ name, value }));
+    const histograms = [...state.histos].map(([name, values]) => histogram(name, values));
+    const window = { start: state.windowStart, end: Date.now() };
+    state.counters.clear(); state.gauges.clear(); state.histos.clear(); state.windowStart = Date.now();
+    return { events, spans, counters, gauges, histograms, window };
+  }
+
+  // Flush every non-empty signal over the ACTIVE transport (Azure Monitor by default; OTLP if an
+  // OTLP endpoint is set; local-only otherwise). Fire-and-forget: awaited only so callers CAN block
+  // on shutdown, but it never throws and a send failure keeps the audit JSONL as the durable record.
+  // Returns a small result summary ({ sent, transport, ok?, status?, error? }) for `telemetry test`.
+  async function flush({ requeue = true } = {}) {
+    if (state.flushTimer) { clearTimeout(state.flushTimer); state.flushTimer = null; }
+    const generation = state.generation;
+    if (!on()) { state.events = []; state.spans = []; state.counters.clear(); state.gauges.clear(); state.histos.clear(); return { sent: false, transport: 'off' }; }
+    const resource = state.resource || buildResource();
+    const { events, spans, counters, gauges, histograms, window } = drainRaw();
+    if (!events.length && !spans.length && !counters.length && !gauges.length && !histograms.length) return { sent: false, transport: 'idle' };
+    const transport = resolveTransport();
+
+    // The local-test switch: print exactly what WOULD leave over the active transport, send nothing.
+    if (state.mode === 'console') {
+      if (transport.kind === 'azure') printPayload('azure', encodeEnvelopes({ events, spans, counters, gauges, histograms, window }, resource));
+      else for (const [signal, payload] of otlpJobs({ events, spans, counters, gauges, histograms, window, resource })) printPayload(signal, payload);
+      return { sent: false, transport: 'console' };
+    }
+
+    if (transport.kind === 'azure') {
+      const r = await sendAzure(encodeEnvelopes({ events, spans, counters, gauges, histograms, window }, resource), { endpoint: transport.endpoint });
+      if (r.ok === false && requeue && state.generation === generation) {
+        if (events.length) state.events = [...events.slice(-500), ...state.events];
+        for (const g of gauges) if (!state.gauges.has(g.name)) state.gauges.set(g.name, g.value);
+      }
+      return { sent: true, transport: 'azure', ...r };
+    }
+    if (transport.kind === 'otlp') {
+      const jobs = otlpJobs({ events, spans, counters, gauges, histograms, window, resource });
+      const results = await Promise.all(jobs.map(([signal, payload]) => sendOtlp(signal, payload, { endpoint: transport.endpoint })));
+      const logResult = results[jobs.findIndex(([signal]) => signal === 'logs')];
+      const metricResult = results[jobs.findIndex(([signal]) => signal === 'metrics')];
+      if (requeue && state.generation === generation && logResult?.ok === false && events.length) state.events = [...events.slice(-500), ...state.events];
+      if (requeue && state.generation === generation && metricResult?.ok === false) {
+        for (const g of gauges) if (!state.gauges.has(g.name)) state.gauges.set(g.name, g.value);
+      }
+      const ok = results.every(r => r && r.ok);
+      return { sent: true, transport: 'otlp', ok, status: results[0]?.status };
+    }
+    // transport 'none' → nothing sent; the JSONL audit already holds everything (local-only).
+    return { sent: false, transport: 'none' };
+  }
+
+  // Close the session span + do a final, time-boxed flush. Called by CLIs before exit and by the
+  // server on shutdown. Never blocks longer than `timeoutMs`.
+  async function shutdown({ timeoutMs = 800 } = {}) {
+    if (state.flushTimer) { clearTimeout(state.flushTimer); state.flushTimer = null; }
+    if (on() && state.session) { state.session.end = Date.now(); state.spans.push(state.session); state.session = null; }
+    await Promise.race([flush(), new Promise(r => setTimeout(r, timeoutMs))]).catch(() => {});
+  }
+
+  // Introspection for `telemetry show/status/test` + tests: the resolved mode, the active transport,
+  // the resource, a record count, and the exact payloads that WOULD be sent now (buffers untouched).
+  function preview() {
+    const resource = state.resource || buildResource();
+    const transport = resolveTransport();
+    const events = state.events.slice();
+    const spans = state.spans.slice();
+    const counters = [...state.counters].map(([name, value]) => ({ name, value }));
+    const gauges = [...state.gauges].map(([name, value]) => ({ name, value }));
+    const histograms = [...state.histos].map(([name, values]) => histogram(name, values));
+    const window = { start: state.windowStart, end: Date.now() };
+    const count = events.length + spans.length + counters.length + gauges.length + histograms.length;
+    const bufs = { events, spans, counters, gauges, histograms, window, resource };
+    const payloads = transport.kind === 'azure'
+      ? { azure: encodeEnvelopes({ events, spans, counters, gauges, histograms, window }, resource) }
+      : Object.fromEntries(otlpJobs(bufs));
+    return { mode: state.mode, transport, resource, count, payloads };
+  }
+
+  return {
+    configure, refresh, emit, count, gauge, observe, startSpan, flush, shutdown, preview,
+    mode: () => state.mode, resource: () => state.resource, ctx: () => state.ctx,
+    _state: state,
+  };
+}
+
+// ---- helpers ----------------------------------------------------------------
+function histogram(name, values) {
+  const bounds = INP_BOUNDS;
+  const buckets = new Array(bounds.length + 1).fill(0);
+  let sum = 0, min = null, max = null;
+  for (const v of values) {
+    sum += v;
+    if (min === null || v < min) min = v;
+    if (max === null || v > max) max = v;
+    let i = bounds.findIndex(b => v <= b);
+    if (i < 0) i = bounds.length;
+    buckets[i]++;
+  }
+  return { name, count: values.length, sum, min, max, bounds, buckets, attributes: {} };
+}
+
+function printPayload(signal, payload) {
+  // The local-test switch: print exactly what would go over the wire, tagged, to stderr (so it
+  // never pollutes a command's stdout / the comment-bridge JSON). `signal` is an OTLP signal name
+  // (logs|metrics|traces) or `azure` for the App Insights envelope batch.
+  try { process.stderr.write(`[telemetry:${signal}] ${JSON.stringify(payload)}\n`); } catch { /* ignore */ }
+}
+
+// ---- process-wide singleton -------------------------------------------------
+let _client = null;
+export function telemetry() { if (!_client) _client = createClient(); return _client; }
+
+// Convenience proxies (most callers just want these).
+export const configureTelemetry = (opts) => telemetry().configure(opts);
+export const refreshTelemetry = () => telemetry().refresh();
+export const emit = (name, props) => telemetry().emit(name, props);
+export const count = (metric, n) => telemetry().count(metric, n);
+export const gauge = (metric, value) => telemetry().gauge(metric, value);
+export const observe = (metric, value) => telemetry().observe(metric, value);
+export const startSpan = (name, attrs) => telemetry().startSpan(name, attrs);
+export const flushTelemetry = (opts) => telemetry().flush(opts);
+export const shutdownTelemetry = (opts) => telemetry().shutdown(opts);
+export const telemetryMode = () => telemetry().mode();
+export const telemetryPreview = () => telemetry().preview();
+export { auditPath };
+
+// A browser request is already a bounded batch. Process it with an isolated vault-scoped client
+// so concurrent project tabs can never share resource identity, consent policy, or retry state.
+export async function submitTelemetryBatch({ events = [], counters = {}, gauges = {}, histograms = {} } = {}, opts = {}) {
+  const client = createClient();
+  client.configure(opts);
+  for (const event of events) {
+    if (event && typeof event.name === 'string') client.emit(event.name, event.props || {});
+  }
+  for (const [name, value] of Object.entries(counters || {})) client.count(name, value);
+  for (const [name, value] of Object.entries(gauges || {})) client.gauge(name, value);
+  for (const [name, values] of Object.entries(histograms || {})) {
+    if (Array.isArray(values)) for (const value of values) client.observe(name, value);
+  }
+  return client.flush({ requeue: false });
+}
+
+// Read the last `n` lines of the local audit trail (for `sonorance telemetry show`).
+export async function readAudit(n = 20) {
+  try {
+    const txt = await readFile(auditPath(), 'utf8');
+    return txt.trim().split('\n').filter(Boolean).slice(-n).map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  } catch { return []; }
+}
+
+// Reset the singleton (tests only).
+export function _resetTelemetryForTest() { _client = null; }