@ngockhoale/ukit 3.0.5 → 3.0.7

package/src/core/observability/emit/config.js

@@ -0,0 +1,29 @@
+/**
+ * config.js (TASK-007, SPEC §8 / §13) — observability stage gate.
+ *
+ *   resolveStage(config) → 'off' | 'shadow' | 'canary' | 'default'
+ *
+ * Reads `observability.stage` from the project runtime config object.
+ * Stages promote off → shadow → canary → default; the kill switch is
+ * setting the value back to 'off'. Absent config, absent key, non-object
+ * intermediate, or malformed stage value all resolve to 'off' — a bad
+ * config can never promote the recorder.
+ *
+ * Same semantics as resolveConfigStage(config, 'observability.stage') in
+ * src/core/runtimeConfig.js; kept dependency-free here so the emit hot
+ * path never pulls the runtime-config module graph (and its package.json
+ * read) into a hook deadline. VALID_ROUTE_STAGES is the frozen vocabulary
+ * this mirrors — a stage rename is a breaking config change either way.
+ */
+
+const VALID_STAGES = new Set(['off', 'shadow', 'canary', 'default']);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function resolveStage(config = null) {
+  const node = isPlainObject(config) ? config.observability : undefined;
+  const stage = isPlainObject(node) ? node.stage : undefined;
+  return VALID_STAGES.has(stage) ? stage : 'off';
+}

package/src/core/observability/emit/recorder.js

@@ -0,0 +1,297 @@
+/**
+ * recorder.js (TASK-007, SPEC §5 DF-FR04/DF-FR08, §8) — the single semantic
+ * emission seam.
+ *
+ *   createRecorder({ root, config, queueSize?, writer?, clock? })
+ *     → { emit, startSpan, endSpan, flush, health }
+ *
+ * Pipeline per emit(): stage gate → fill missing envelope fields →
+ * validateSemanticRecord → sanitizeObserved → bounded in-memory queue.
+ * Nothing reaches disk from emit(); flush() drains the queue through the
+ * segment store's appendRecord (TASK-006) — the recorder composes the
+ * writer, it never reimplements writes.
+ *
+ * Guarantees (DF-FR04):
+ *   - emit() is synchronous, non-blocking, and never throws — every failure
+ *     is a typed { status: 'dropped', reason } plus a health() counter.
+ *   - The queue is bounded; at the bound the OLDEST queued record is
+ *     evicted (dropped_oldest++) and emit reports { status: 'dropped',
+ *     reason: 'queue-full' } so the caller sees the loss — the incoming
+ *     record is still queued (flight-recorder policy: newest data wins).
+ *   - flush({ deadlineMs }) races every write against the remaining
+ *     deadline and returns 'partial' rather than overrunning; a writer
+ *     failure returns a typed 'error' FlushResult and never fails the
+ *     user task.
+ *   - No LLM, no sync fs, no daemon. Stage is read live per emit, so
+ *     config.observability.stage = 'off' is an immediate kill switch.
+ *
+ * DF-FR08: model.completed/model.failed records emitted without
+ * payload.resource are stamped { value: null, source: 'UNKNOWN' } —
+ * host-blind stays explicitly unknown, never 0, never invented.
+ */
+
+import crypto from 'node:crypto';
+
+import { validateSemanticRecord } from '../schema/validate.js';
+import { sanitizeObserved } from '../privacy/sanitizeObserved.js';
+import { SEMANTIC_REGISTRY } from '../schema/registry.js';
+import { SCHEMA_VERSION } from '../schema/constants.js';
+import { appendRecord } from '../segments/retention.js';
+import { resolveStage } from './config.js';
+
+const DEFAULT_QUEUE_SIZE = 1024;
+const SPAN_STATUSES = new Set(['completed', 'failed', 'blocked']);
+// Semantic names whose payload carries typed resource usage (DF-FR08).
+const RESOURCE_SEMANTICS = new Set(['model.completed', 'model.failed']);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function defaultClock() {
+  return {
+    nowMs: () => Date.now(),
+    nowNs: () => process.hrtime.bigint(),
+    iso: () => new Date().toISOString(),
+  };
+}
+
+export function createRecorder({ root, config, queueSize, writer, clock } = {}) {
+  const bound = Number.isInteger(queueSize) && queueSize > 0 ? queueSize : DEFAULT_QUEUE_SIZE;
+  const write = typeof writer === 'function' ? writer : (record) => appendRecord(root, record);
+  const time = clock && typeof clock.nowNs === 'function' ? clock : defaultClock();
+
+  const state = {
+    queue: [],
+    pumping: null,
+    sequence: 0,
+    boot_id: `boot-${crypto.randomUUID()}`,
+    writer_id: `recorder-${crypto.randomUUID()}`,
+    accepted: 0,
+    written: 0,
+    dropped_stage_off: 0,
+    dropped_invalid: 0,
+    dropped_sanitized: 0,
+    dropped_oldest: 0,
+    dropped_write: 0,
+    write_failures: 0,
+    invalid_spans: 0,
+    last_error: null,
+  };
+
+  function fillEnvelope(record) {
+    const out = { ...record };
+    if (out.record_type === undefined || out.record_type === null) out.record_type = 'fact';
+    if (out.schema_version === undefined || out.schema_version === null) {
+      out.schema_version = SCHEMA_VERSION;
+    }
+    if (typeof out.record_id !== 'string' || out.record_id.length === 0) {
+      out.record_id = `rec-${crypto.randomUUID()}`;
+    }
+    if (typeof out.boot_id !== 'string' || out.boot_id.length === 0) out.boot_id = state.boot_id;
+    if (typeof out.writer_id !== 'string' || out.writer_id.length === 0) {
+      out.writer_id = state.writer_id;
+    }
+    // The recorder owns sequence only when the caller did not supply one —
+    // caller-provided (writer_id, sequence) pairs pass through untouched so
+    // corpus/adapter records keep their identity.
+    if (!Number.isInteger(out.sequence)) out.sequence = ++state.sequence;
+    if (typeof out.wall_time_utc !== 'string') out.wall_time_utc = time.iso();
+    if (out.monotonic_ns === undefined || out.monotonic_ns === null) {
+      out.monotonic_ns = Number(time.nowNs());
+    }
+    if (typeof out.importance !== 'string') out.importance = 'normal';
+    if (typeof out.privacy_class !== 'string') {
+      const entry = SEMANTIC_REGISTRY[out.semantic_name];
+      out.privacy_class = entry ? entry.privacy_class : 'internal';
+    }
+    if (isPlainObject(out.payload)) {
+      out.payload = { ...out.payload };
+      if (RESOURCE_SEMANTICS.has(out.semantic_name) && out.payload.resource === undefined) {
+        out.payload.resource = { value: null, source: 'UNKNOWN' };
+      }
+    }
+    return out;
+  }
+
+  function emit(record) {
+    try {
+      if (resolveStage(config) === 'off') {
+        state.dropped_stage_off += 1;
+        return { status: 'dropped', reason: 'stage-off' };
+      }
+      const candidate = isPlainObject(record) ? fillEnvelope(record) : record;
+      const validation = validateSemanticRecord(candidate);
+      if (!validation.ok) {
+        state.dropped_invalid += 1;
+        return { status: 'dropped', reason: 'invalid' };
+      }
+      const clean = sanitizeObserved(candidate);
+      if (!clean.ok) {
+        state.dropped_sanitized += 1;
+        return { status: 'dropped', reason: 'sanitize-rejected' };
+      }
+      let evicted = false;
+      if (state.queue.length >= bound) {
+        state.queue.shift();
+        state.dropped_oldest += 1;
+        evicted = true;
+      }
+      state.queue.push(clean.record);
+      state.accepted += 1;
+      return evicted
+        ? { status: 'dropped', reason: 'queue-full' }
+        : { status: 'accepted' };
+    } catch {
+      state.dropped_invalid += 1;
+      return { status: 'dropped', reason: 'recorder-error' };
+    }
+  }
+
+  function startSpan(traceId, operation) {
+    const trace_id = typeof traceId === 'string' && traceId.length > 0
+      ? traceId
+      : `trace-${crypto.randomUUID()}`;
+    const span = {
+      trace_id,
+      span_id: `span-${crypto.randomUUID()}`,
+      execution_id: `exec-${trace_id}`,
+      operation: typeof operation === 'string' ? operation : 'task',
+      start_ns: time.nowNs(),
+      ended: false,
+    };
+    emit({
+      semantic_name: 'execution.started',
+      trace_id: span.trace_id,
+      span_id: span.span_id,
+      parent_span_id: null,
+      execution_id: span.execution_id,
+      payload: { operation: span.operation, duration_ms: null },
+    });
+    return span;
+  }
+
+  function endSpan(span, status) {
+    if (!isPlainObject(span) || span.ended || !SPAN_STATUSES.has(status)) {
+      state.invalid_spans += 1;
+      return;
+    }
+    span.ended = true;
+    const duration_ms = Math.max(0, Number(time.nowNs() - span.start_ns) / 1e6);
+    emit({
+      semantic_name: `execution.${status}`,
+      trace_id: span.trace_id,
+      span_id: span.span_id,
+      parent_span_id: null,
+      execution_id: span.execution_id,
+      payload: { operation: span.operation, duration_ms },
+    });
+  }
+
+  // Race one write against the remaining deadline. The record stays at the
+  // head of the queue until a write is known to have completed: on timeout
+  // the late write may still land, so a later retry can duplicate the line —
+  // bounded telemetry accepts a rare duplicate over blocking the caller.
+
+  async function writeBounded(record, budgetMs) {
+    const writePromise = Promise.resolve()
+      .then(() => write(record))
+      .then((r) => (r && r.ok ? 'ok' : (r && r.reason) || 'write-failed'))
+      .catch(() => 'write-failed');
+    if (!Number.isFinite(budgetMs) || budgetMs <= 0) return 'deadline';
+    let timer;
+    try {
+      return await Promise.race([
+        writePromise,
+        new Promise((resolve) => {
+          timer = setTimeout(() => resolve('deadline'), budgetMs);
+          if (timer.unref) timer.unref();
+        }),
+      ]);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async function pump(deadlineMs) {
+    const started = time.nowMs();
+    const deadline = Number.isFinite(deadlineMs) ? started + deadlineMs : null;
+    const result = { status: 'ok', written: 0, dropped: 0, remaining: 0, elapsed_ms: 0 };
+
+    while (state.queue.length > 0) {
+      const remaining = deadline === null ? Infinity : deadline - time.nowMs();
+      if (remaining <= 0) {
+        result.status = 'partial';
+        result.reason = 'deadline';
+        break;
+      }
+      const record = state.queue[0];
+      const outcome = await writeBounded(record, remaining);
+      if (outcome === 'ok') {
+        state.queue.shift();
+        state.written += 1;
+        result.written += 1;
+        continue;
+      }
+      if (outcome === 'deadline') {
+        result.status = 'partial';
+        result.reason = 'deadline';
+        break;
+      }
+      // Writer failure: drop the failed record (never silently requeue a
+      // poison record into an infinite retry), abort the batch, report a
+      // typed error — the caller's task is unaffected.
+      state.queue.shift();
+      state.dropped_write += 1;
+      state.write_failures += 1;
+      state.last_error = outcome;
+      result.status = 'error';
+      result.reason = outcome;
+      result.dropped += 1;
+      break;
+    }
+
+    result.remaining = state.queue.length;
+    result.elapsed_ms = Math.max(0, time.nowMs() - started);
+    return result;
+  }
+
+  async function flush({ deadlineMs } = {}) {
+    // Serialize concurrent flushes: a second caller waits for the in-flight
+    // pump (bounded by that pump's own deadline), then drains what remains.
+    if (state.pumping) {
+      try {
+        await state.pumping;
+      } catch {
+        /* pump() never rejects; belt-and-suspenders */
+      }
+    }
+    const run = pump(deadlineMs);
+    state.pumping = run;
+    try {
+      return await run;
+    } finally {
+      if (state.pumping === run) state.pumping = null;
+    }
+  }
+
+  function health() {
+    return {
+      stage: resolveStage(config),
+      queue_depth: state.queue.length,
+      queue_bound: bound,
+      accepted: state.accepted,
+      written: state.written,
+      dropped_stage_off: state.dropped_stage_off,
+      dropped_invalid: state.dropped_invalid,
+      dropped_sanitized: state.dropped_sanitized,
+      dropped_oldest: state.dropped_oldest,
+      dropped_write: state.dropped_write,
+      write_failures: state.write_failures,
+      invalid_spans: state.invalid_spans,
+      last_error: state.last_error,
+    };
+  }
+
+  return { emit, startSpan, endSpan, flush, health };
+}

package/src/core/observability/evaluation/aiPacket.js

@@ -0,0 +1,230 @@
+/**
+ * aiPacket.js (TASK-013, SPEC §5 DF-FR12, §8) — compact offline evaluator
+ * packet.
+ *
+ *   buildEvaluatorPacket(summaries): SafePacket
+ *
+ * Builds the bounded, sanitized packet an offline AI evaluator consumes.
+ * The packet carries ONLY the evaluator's reading sequence — summary →
+ * anomalies → representative evidence refs — derived from TraceSummaries.
+ * It never contains raw records, prompts, tee output, or payload content.
+ *
+ * Contract:
+ *   - Hard cap: serialized packet never exceeds PACKET_MAX_BYTES (16KB).
+ *     Overflow drops whole traces deterministically with explicit
+ *     `truncated`/`omitted_traces` markers — never silent.
+ *   - Sanitized: every string passes redactString (redaction rules +
+ *     secret scanner + length cap); unknown fields are dropped, not
+ *     carried through.
+ *   - Deterministic: no clock, no randomness; traces are sorted by
+ *     trace_id so input order cannot change the output.
+ *   - Evaluator opinion is a separate provenance layer (DF-FR02): this
+ *     packet is INPUT to an evaluator, never a decision itself.
+ */
+
+import { scanText } from '../../sensitiveValueScanner.js';
+import { redactString } from '../privacy/redaction.js';
+
+export const PACKET_MAX_BYTES = 16 * 1024;
+export const PACKET_VERSION = 'df-eval-packet-1';
+
+const MAX_STRING_CHARS = 1024;
+const MAX_SPANS_PER_TRACE = 16;
+const MAX_EVIDENCE_REFS_PER_TRACE = 24;
+const MAX_DEPTH = 8;
+const MAX_OBJECT_KEYS = 64;
+const MAX_ARRAY_ITEMS = 128;
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function num(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+/**
+ * Recursive sanitizer: strings go through the shared redaction pipeline,
+ * containers are bounded, unknown types collapse to null.
+ */
+function sanitizeValue(value, depth) {
+  if (value === null) return null;
+  const t = typeof value;
+  if (t === 'boolean') return value;
+  if (t === 'number') return Number.isFinite(value) ? value : null;
+  if (t === 'string') {
+    return redactString(value, { scanner: scanText, maxChars: MAX_STRING_CHARS });
+  }
+  if (depth >= MAX_DEPTH) return null;
+  if (Array.isArray(value)) {
+    return value.slice(0, MAX_ARRAY_ITEMS).map((item) => sanitizeValue(item, depth + 1));
+  }
+  if (isPlainObject(value)) {
+    const out = {};
+    for (const key of Object.keys(value).slice(0, MAX_OBJECT_KEYS)) {
+      out[key] = sanitizeValue(value[key], depth + 1);
+    }
+    return out;
+  }
+  return null;
+}
+
+/** Typed anomaly list — codes + counts only, mirroring digest.js rules. */
+function anomaliesOf(summary) {
+  const out = [];
+  const drops = isPlainObject(summary.drops) ? summary.drops : {};
+  const retries = isPlainObject(summary.retries) ? summary.retries : {};
+  const resource = isPlainObject(summary.resource) ? summary.resource : {};
+  const coverage = isPlainObject(summary.coverage) ? summary.coverage : {};
+
+  if (summary.telemetry_complete === false) out.push({ code: 'telemetry_incomplete' });
+  if (num(drops.dropped_count) > 0) {
+    out.push({
+      code: 'dropped_records',
+      count: drops.dropped_count,
+      reasons: Object.keys(isPlainObject(drops.by_reason) ? drops.by_reason : {}).sort(),
+    });
+  }
+  if (num(drops.redacted) > 0) out.push({ code: 'redacted_records', count: drops.redacted });
+  if (num(retries.retries) > 0) {
+    out.push({ code: 'retries', count: retries.retries, model_attempts: num(retries.model_attempts) });
+  }
+  if (num(retries.failed_spans) > 0) out.push({ code: 'failed_spans', count: retries.failed_spans });
+  if (num(resource.unknown_count) > 0) {
+    out.push({ code: 'host_blind_resource', count: resource.unknown_count });
+  }
+  if (num(coverage.open_spans) > 0) out.push({ code: 'open_spans', count: coverage.open_spans });
+  if (num(coverage.orphan_spans) > 0) {
+    out.push({ code: 'orphan_spans', count: coverage.orphan_spans });
+  }
+  if (num(coverage.duplicate_ends) > 0) {
+    out.push({ code: 'duplicate_ends', count: coverage.duplicate_ends });
+  }
+  return out;
+}
+
+/**
+ * Representative evidence: record IDs of anomalous spans (failed/blocked/
+ * retried) first, then the root span's end record — refs only, never
+ * record content.
+ */
+function evidenceRefsOf(summary) {
+  const spans = Array.isArray(summary.spans) ? summary.spans : [];
+  const refs = [];
+  for (const span of spans) {
+    if (!isPlainObject(span)) continue;
+    const anomalous =
+      span.status === 'failed' ||
+      span.status === 'blocked' ||
+      (typeof span.attempt_index === 'number' && span.attempt_index > 1);
+    if (anomalous && typeof span.end_record_id === 'string') refs.push(span.end_record_id);
+  }
+  const root = spans.find((s) => isPlainObject(s) && s.parent_span_id === null);
+  if (root && typeof root.end_record_id === 'string') refs.push(root.end_record_id);
+  return [...new Set(refs)].slice(0, MAX_EVIDENCE_REFS_PER_TRACE);
+}
+
+function spanDigestOf(span) {
+  if (!isPlainObject(span)) return null;
+  return {
+    span_id: typeof span.span_id === 'string' ? span.span_id : null,
+    family: typeof span.family === 'string' ? span.family : 'unknown',
+    operation: typeof span.operation === 'string' ? span.operation : null,
+    status: typeof span.status === 'string' ? span.status : 'open',
+    duration_ms: num(span.duration_ms),
+    attempt_index: Number.isInteger(span.attempt_index) ? span.attempt_index : null,
+  };
+}
+
+function traceEntryOf(summary) {
+  const s = isPlainObject(summary) ? summary : {};
+  const spans = Array.isArray(s.spans) ? s.spans : [];
+  const durations = isPlainObject(s.durations) ? s.durations : {};
+  const retries = isPlainObject(s.retries) ? s.retries : {};
+  const drops = isPlainObject(s.drops) ? s.drops : {};
+  const cache = isPlainObject(s.cache) ? s.cache : {};
+  const resource = isPlainObject(s.resource) ? s.resource : {};
+  const coverage = isPlainObject(s.coverage) ? s.coverage : {};
+
+  return {
+    trace_id: typeof s.trace_id === 'string' ? s.trace_id : null,
+    metric_version: typeof s.metric_version === 'string' ? s.metric_version : null,
+    telemetry_complete: s.telemetry_complete === true,
+    critical_path_ms: num(s.critical_path_ms),
+    durations: {
+      overall: sanitizeValue(durations.overall, 1),
+      model: sanitizeValue(durations.model, 1),
+      tool: sanitizeValue(durations.tool, 1),
+    },
+    retries: {
+      retries: num(retries.retries),
+      model_attempts: num(retries.model_attempts),
+      failed_spans: num(retries.failed_spans),
+    },
+    drops: { events: num(drops.events), dropped_count: num(drops.dropped_count) },
+    cache: { hit_rate: num(cache.hit_rate), hits: num(cache.hits), misses: num(cache.misses) },
+    resource: {
+      total_value: num(resource.total_value),
+      numeric_count: num(resource.numeric_count),
+      unknown_count: num(resource.unknown_count),
+    },
+    coverage: { records: num(coverage.records), spans: num(coverage.spans) },
+    anomalies: anomaliesOf(s),
+    spans: spans.slice(0, MAX_SPANS_PER_TRACE).map(spanDigestOf).filter(Boolean),
+    evidence_refs: evidenceRefsOf(s),
+  };
+}
+
+function buildPacket(traces, totalCount, truncated, omitted) {
+  return {
+    packet_version: PACKET_VERSION,
+    generated_by: 'buildEvaluatorPacket',
+    metric_versions: [...new Set(traces.map((t) => t.metric_version).filter(Boolean))].sort(),
+    trace_count: totalCount,
+    truncated,
+    omitted_traces: omitted,
+    limits: {
+      max_bytes: PACKET_MAX_BYTES,
+      max_spans_per_trace: MAX_SPANS_PER_TRACE,
+      max_evidence_refs_per_trace: MAX_EVIDENCE_REFS_PER_TRACE,
+    },
+    traces,
+  };
+}
+
+function packetBytes(packet) {
+  return Buffer.byteLength(JSON.stringify(packet), 'utf8');
+}
+
+export function buildEvaluatorPacket(summaries) {
+  if (!Array.isArray(summaries)) {
+    throw new TypeError('buildEvaluatorPacket: summaries must be an array of TraceSummary');
+  }
+
+  const traces = summaries
+    .map(traceEntryOf)
+    .map((entry) => sanitizeValue(entry, 0))
+    .sort((a, b) => {
+      const at = a.trace_id === null ? '' : a.trace_id;
+      const bt = b.trace_id === null ? '' : b.trace_id;
+      return at < bt ? -1 : at > bt ? 1 : 0;
+    });
+
+  const total = traces.length;
+  let packet = buildPacket(traces, total, false, 0);
+  if (packetBytes(packet) <= PACKET_MAX_BYTES) return packet;
+
+  // Deterministic bound: keep the largest trace prefix that fits the cap.
+  let lo = 0;
+  let hi = traces.length;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (packetBytes(buildPacket(traces.slice(0, mid), total, true, total - mid)) <= PACKET_MAX_BYTES) {
+      lo = mid;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  packet = buildPacket(traces.slice(0, lo), total, true, total - lo);
+  return packet;
+}