@ngockhoale/ukit 3.0.12 → 3.1.0

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

@@ -2,17 +2,19 @@
  * aiPacket.js (TASK-013, SPEC §5 DF-FR12, §8) — compact offline evaluator
  * packet.
  *
- *   buildEvaluatorPacket(summaries): SafePacket
+ *   buildEvaluatorPacket(summaries, extras?): 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.
+ * anomalies → representative evidence refs — derived from TraceSummaries,
+ * plus (when `extras` is given) the derived `anomalies` and
+ * `opportunities` sections from the analytics lane (TASK-014, DF2-FR14).
  * 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.
+ *     Overflow sheds whole traces first, then `opportunities`, then
+ *     `anomalies` — each section omission is marked in `omitted_sections`.
  *   - Sanitized: every string passes redactString (redaction rules +
  *     secret scanner + length cap); unknown fields are dropped, not
  *     carried through.
@@ -175,8 +177,8 @@ function traceEntryOf(summary) {
   };
 }
 
-function buildPacket(traces, totalCount, truncated, omitted) {
-  return {
+function buildPacket(traces, totalCount, truncated, omitted, sections = null, omittedSections = []) {
+  const packet = {
     packet_version: PACKET_VERSION,
     generated_by: 'buildEvaluatorPacket',
     metric_versions: [...new Set(traces.map((t) => t.metric_version).filter(Boolean))].sort(),
@@ -190,17 +192,37 @@ function buildPacket(traces, totalCount, truncated, omitted) {
     },
     traces,
   };
+  // Extras keys exist only when the caller supplied them — the unpinned
+  // trace-only shape (no anomalies/opportunities keys) stays intact.
+  if (sections !== null) {
+    packet.anomalies = sections.anomalies;
+    packet.opportunities = sections.opportunities;
+    packet.omitted_sections = omittedSections;
+  }
+  return packet;
 }
 
 function packetBytes(packet) {
   return Buffer.byteLength(JSON.stringify(packet), 'utf8');
 }
 
-export function buildEvaluatorPacket(summaries) {
+export function buildEvaluatorPacket(summaries, extras = {}) {
   if (!Array.isArray(summaries)) {
     throw new TypeError('buildEvaluatorPacket: summaries must be an array of TraceSummary');
   }
 
+  // DF2-FR14: the runner passes the derived analytics sections alongside
+  // the trace summaries. Both go through the same sanitizer as trace
+  // content — no caller field survives untouched.
+  const hasExtras =
+    isPlainObject(extras) &&
+    (extras.anomalies !== undefined || extras.opportunities !== undefined);
+  const anomalies =
+    hasExtras && Array.isArray(extras.anomalies) ? sanitizeValue(extras.anomalies, 0) : [];
+  const opportunities =
+    hasExtras && Array.isArray(extras.opportunities) ? sanitizeValue(extras.opportunities, 0) : [];
+  const sections = hasExtras ? { anomalies, opportunities } : null;
+
   const traces = summaries
     .map(traceEntryOf)
     .map((entry) => sanitizeValue(entry, 0))
@@ -211,7 +233,7 @@ export function buildEvaluatorPacket(summaries) {
     });
 
   const total = traces.length;
-  let packet = buildPacket(traces, total, false, 0);
+  let packet = buildPacket(traces, total, false, 0, sections);
   if (packetBytes(packet) <= PACKET_MAX_BYTES) return packet;
 
   // Deterministic bound: keep the largest trace prefix that fits the cap.
@@ -219,12 +241,32 @@ export function buildEvaluatorPacket(summaries) {
   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) {
+    if (
+      packetBytes(buildPacket(traces.slice(0, mid), total, true, total - mid, sections)) <=
+      PACKET_MAX_BYTES
+    ) {
       lo = mid;
     } else {
       hi = mid - 1;
     }
   }
-  packet = buildPacket(traces.slice(0, lo), total, true, total - lo);
+  packet = buildPacket(traces.slice(0, lo), total, true, total - lo, sections);
+  if (packetBytes(packet) <= PACKET_MAX_BYTES) return packet;
+
+  // Traces alone no longer fit: shed the derived sections next —
+  // opportunities before anomalies — each omission recorded explicitly.
+  const omittedSections = [];
+  for (const name of ['opportunities', 'anomalies']) {
+    const kept =
+      name === 'opportunities'
+        ? { anomalies, opportunities: [] }
+        : { anomalies: [], opportunities: [] };
+    packet = buildPacket(traces.slice(0, lo), total, true, total - lo, kept, [
+      ...omittedSections,
+      name,
+    ]);
+    omittedSections.push(name);
+    if (packetBytes(packet) <= PACKET_MAX_BYTES) return packet;
+  }
   return packet;
 }

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

@@ -0,0 +1,95 @@
+// outcomes.js (TASK-013, SPEC §5 DF2-FR13, §7, §8) — canonical outcome
+// signals. One write-time seam:
+//
+//   recordOutcome({recorder, ref?, verdict, kind, source?, sessionId?,
+//     evidenceRefs?}) → EmitResult
+//
+// EmitResult is the recorder's own { status: 'accepted'|'dropped', reason? }
+// so callers see the true fate; only caller-side validation failures are
+// invented here: bad verdict → dropped/invalid-verdict, bad kind →
+// dropped/invalid-kind, missing recorder → dropped/recorder-missing.
+// Off-stage → the recorder's own dropped/stage-off (this module never
+// bypasses the gate, and never throws — a caller can always log the result
+// and move on).
+//
+// Payload (SPEC §7): {verdict, kind, source, trace_ref|execution_ref,
+// evidence_refs[], ref:{kind:'trace'|'execution'|'unresolved', value?}}.
+// `ref` is honest joining: a resolved ref lands BOTH as a typed
+// {kind,value} and as the SPEC-shaped trace_ref/execution_ref field; a
+// missing or ambiguous ref emits ref:{kind:'unresolved'} — never guessed,
+// never fabricated (SPEC §8 honesty + task test 3). trace_ref/execution_ref
+// are omitted when unresolved rather than filled with a placeholder.
+//
+// Payload discipline: metadata only. Free-form feedback text is denied at
+// the sanitize boundary anyway; this module never puts it in a payload —
+// pass ids via sessionId/evidenceRefs instead.
+
+const VERDICTS = new Set(['accepted', 'rejected', 'revised', 'unknown']);
+const KINDS = new Set(['user-correction', 'acceptance', 'verification', 'manual']);
+const REF_KINDS = new Set(['trace', 'execution']);
+const EVIDENCE_REFS_MAX = 32;
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+
+// One honest resolution: 'trace'|'execution' → {kind,value}; anything else
+// → {kind:'unresolved'}. Accepts {kind,value}, {trace_ref}, {execution_ref},
+// {traceRef}, {executionRef} so callers pass whichever shape their record
+// already carries; a bare string is ambiguous between the two ref kinds and
+// resolves honestly to unresolved rather than guessing the join key.
+function resolveRef(ref) {
+  if (!isPlainObject(ref)) return { kind: 'unresolved' };
+  if (REF_KINDS.has(ref.kind) && isNonEmptyString(ref.value)) {
+    return { kind: ref.kind, value: ref.value };
+  }
+  const trace = ref.trace_ref ?? ref.traceRef;
+  if (isNonEmptyString(trace)) return { kind: 'trace', value: trace };
+  const execution = ref.execution_ref ?? ref.executionRef;
+  if (isNonEmptyString(execution)) return { kind: 'execution', value: execution };
+  return { kind: 'unresolved' };
+}
+
+function cleanEvidenceRefs(refs) {
+  if (!Array.isArray(refs)) return [];
+  return refs.filter(isNonEmptyString).slice(0, EVIDENCE_REFS_MAX);
+}
+
+export function recordOutcome({ recorder, ref, verdict, kind, source, sessionId, evidenceRefs } = {}) {
+  if (!VERDICTS.has(verdict)) {
+    return { status: 'dropped', reason: 'invalid-verdict' };
+  }
+  if (!KINDS.has(kind)) {
+    return { status: 'dropped', reason: 'invalid-kind' };
+  }
+  if (!recorder || typeof recorder.emit !== 'function') {
+    return { status: 'dropped', reason: 'recorder-missing' };
+  }
+
+  const resolved = resolveRef(ref);
+  const payload = {
+    verdict,
+    kind,
+    source: isNonEmptyString(source) ? source : 'unknown',
+    ref: resolved,
+    evidence_refs: cleanEvidenceRefs(evidenceRefs),
+  };
+  if (resolved.kind === 'trace') payload.trace_ref = resolved.value;
+  if (resolved.kind === 'execution') payload.execution_ref = resolved.value;
+
+  const record = { semantic_name: 'outcome.observed', payload };
+  if (isNonEmptyString(sessionId)) record.session_id = sessionId;
+
+  // emit() is already never-throw and returns a typed EmitResult; the guard
+  // keeps this seam honest even if a caller hands it a hand-rolled recorder
+  // that violates that contract.
+  try {
+    return recorder.emit(record);
+  } catch {
+    return { status: 'dropped', reason: 'recorder-error' };
+  }
+}

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

@@ -0,0 +1,225 @@
+/**
+ * runner.js (TASK-014, SPEC §5 DF2-FR14, §6, §8) — the AI evaluation lane.
+ *
+ *   runEvaluation({ root, config, clock?, provider? })
+ *     → Promise<{ status: 'ran'|'skipped'|'degraded', reason?,
+ *                 packet_bytes, findings_accepted, findings_rejected,
+ *                 kb_ids[] }>
+ *   proposeAdaptation({ root?, clock?, proposal? })
+ *     → { status: 'unsupported', reason, kb_id? }   (P3 seam — never applies)
+ *
+ * `root` is the observability storage root: retained records live under
+ * `root/segments` and the optimization KB (optimization-kb.jsonl) is
+ * appended directly under `root`, alongside crashes/ and
+ * last-projection.json.
+ *
+ * Pipeline: rebuildIndex → detectAnomalies + detectOpportunities →
+ * buildEvaluatorPacket → injected provider → findings.js validation →
+ * append accepted findings to the KB as `evaluation` records.
+ *
+ * Provider seam: the evaluator transport is out of scope (planner decision
+ * — HTTP/UNIC plumbing is a later cycle's wiring). The provider is an
+ * injected async function `(packetJson) → { findings: [...] }`; dispatch
+ * only happens when BOTH sides exist: the operator opted in via
+ * `observability.evaluator.provider` and a callable `provider` was
+ * injected. Configured-but-unwired reports `provider_unavailable` so the
+ * CLI can distinguish "not configured" from "transport not wired yet".
+ * Without the config opt-in nothing ever runs — the deterministic
+ * analytics lane stays the default.
+ *
+ * Contract:
+ *   - never throws on data; every failure path is a typed status.
+ *   - `skipped` reasons: no-provider | provider_unavailable | no-data
+ *   - `degraded` reasons: invalid_root | rebuild_failed |
+ *     provider_timeout | provider_error | provider_malformed_response
+ *   - KB entries carry provenance.source 'evaluated_judgment' + evidence
+ *     refs; findings.js re-shapes them so evaluator opinion is recorded
+ *     with decision 'unsupported', applied false — never promoted.
+ */
+
+import path from 'node:path';
+
+import { rebuildIndex } from '../analytics/rebuild.js';
+import { detectAnomalies } from '../analytics/anomalies.js';
+import { detectOpportunities } from '../analytics/opportunities.js';
+import { buildEvaluatorPacket } from './aiPacket.js';
+import { validateEvaluatorFindings } from './findings.js';
+import { createOptimizationStore } from './optimizationKnowledge.js';
+
+const SEGMENTS_DIR = 'segments';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_TIMEOUT_MS = 10 * 60_000;
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function result(status, extra = {}) {
+  return {
+    status,
+    packet_bytes: 0,
+    findings_accepted: 0,
+    findings_rejected: 0,
+    kb_ids: [],
+    ...extra,
+  };
+}
+
+/**
+ * Read `observability.evaluator` from the runtime config. Fail-safe like
+ * resolveStage: absent or malformed node → null (lane off); a present
+ * node still requires a non-empty `provider` name. `timeoutMs` clamps to
+ * (0, 10min], defaulting to 30s.
+ */
+function resolveEvaluatorConfig(config) {
+  const node = isPlainObject(config) ? config.observability : undefined;
+  if (!isPlainObject(node)) return null;
+  const evaluator = node.evaluator;
+  if (!isPlainObject(evaluator)) return null;
+  if (typeof evaluator.provider !== 'string' || evaluator.provider.length === 0) return null;
+  const raw = evaluator.timeoutMs;
+  const timeoutMs =
+    typeof raw === 'number' && Number.isFinite(raw) && raw > 0
+      ? Math.min(raw, MAX_TIMEOUT_MS)
+      : DEFAULT_TIMEOUT_MS;
+  return {
+    provider: evaluator.provider,
+    endpoint: typeof evaluator.endpoint === 'string' ? evaluator.endpoint : null,
+    model: typeof evaluator.model === 'string' ? evaluator.model : null,
+    timeoutMs,
+  };
+}
+
+function timeoutError() {
+  const err = new Error('evaluator provider timed out');
+  err.code = 'UKIT_EVALUATOR_TIMEOUT';
+  return err;
+}
+
+/** Race the injected provider against timeoutMs; the loser is dropped. */
+function callProvider(provider, packetJson, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(timeoutError()), timeoutMs);
+    if (typeof timer.unref === 'function') timer.unref();
+    Promise.resolve()
+      .then(() => provider(packetJson))
+      .then(resolve, reject)
+      .finally(() => clearTimeout(timer));
+  });
+}
+
+/**
+ * Record one validated finding as an optimization-KB `evaluation` entry.
+ * findings.js already guarantees claim + evidence_refs and pins
+ * decision 'unsupported' / applied false — the store re-checks that
+ * contract itself, so an evaluator opinion can never be promoted here.
+ */
+function toKbEntry(finding, evaluator) {
+  return {
+    hypothesis: finding.claim,
+    evidence_refs: finding.evidence_refs,
+    decision: 'unsupported',
+    applied: false,
+    provenance: { source: 'evaluated_judgment' },
+    alternative_explanations: Array.isArray(finding.alternatives) ? finding.alternatives : [],
+    versions: {
+      confidence: finding.confidence,
+      evaluator_provider: evaluator.provider,
+      evaluator_model: evaluator.model,
+    },
+  };
+}
+
+export async function runEvaluation({ root, config, clock, provider } = {}) {
+  if (typeof root !== 'string' || root.length === 0) {
+    return result('degraded', { reason: 'invalid_root' });
+  }
+
+  // Provider gate first: no evaluator config → the deterministic lane is
+  // all that ever runs; never build or dispatch a packet the operator
+  // did not ask to send.
+  const evaluator = resolveEvaluatorConfig(config);
+  if (evaluator === null) return result('skipped', { reason: 'no-provider' });
+  if (typeof provider !== 'function') {
+    return result('skipped', { reason: 'provider_unavailable' });
+  }
+
+  let rebuilt;
+  try {
+    rebuilt = await rebuildIndex(path.join(root, SEGMENTS_DIR));
+  } catch {
+    return result('degraded', { reason: 'rebuild_failed' });
+  }
+  const summaries = Array.isArray(rebuilt && rebuilt.summaries) ? rebuilt.summaries : [];
+  if (summaries.length === 0) return result('skipped', { reason: 'no-data' });
+
+  const anomalies = detectAnomalies(summaries);
+  const opportunities = detectOpportunities(summaries);
+  const packet = buildEvaluatorPacket(summaries, { anomalies, opportunities });
+  const packetJson = JSON.stringify(packet);
+  const packetBytes = Buffer.byteLength(packetJson, 'utf8');
+
+  let payload;
+  try {
+    payload = await callProvider(provider, packetJson, evaluator.timeoutMs);
+  } catch (err) {
+    return result('degraded', {
+      reason: err && err.code === 'UKIT_EVALUATOR_TIMEOUT' ? 'provider_timeout' : 'provider_error',
+      packet_bytes: packetBytes,
+    });
+  }
+
+  const { findings, rejected } = validateEvaluatorFindings(payload);
+  // candidate_index null means the whole payload was malformed — that is
+  // a provider contract violation, reported as degraded rather than a
+  // clean run with zero findings.
+  if (rejected.some((entry) => entry && entry.candidate_index === null)) {
+    return result('degraded', {
+      reason: 'provider_malformed_response',
+      packet_bytes: packetBytes,
+      findings_rejected: rejected.length,
+    });
+  }
+
+  const store = createOptimizationStore({ root, clock });
+  const kbIds = [];
+  for (const finding of findings) {
+    const { id } = store.recordOptimization(toKbEntry(finding, evaluator));
+    kbIds.push(id);
+  }
+
+  return result('ran', {
+    packet_bytes: packetBytes,
+    findings_accepted: findings.length,
+    findings_rejected: rejected.length,
+    kb_ids: kbIds,
+  });
+}
+
+/**
+ * P3 adaptive-actuation seam — interface only. Proposals are recorded in
+ * the optimization KB as `unsupported`/unapplied evidence (never applied,
+ * never gated on), and the caller always gets the same typed answer: this
+ * lane does not actuate.
+ */
+export function proposeAdaptation({ root, clock, proposal } = {}) {
+  let kbId = null;
+  if (typeof root === 'string' && root.length > 0) {
+    const store = createOptimizationStore({ root, clock });
+    kbId = store.recordOptimization({
+      hypothesis: typeof proposal === 'string' && proposal.length > 0
+        ? proposal
+        : 'adaptive actuation proposal (unnamed)',
+      evidence_refs: [],
+      decision: 'unsupported',
+      applied: false,
+      provenance: { source: 'optimization_decision' },
+      versions: { interface: 'proposeAdaptation', interface_only: true },
+    }).id;
+  }
+  return {
+    status: 'unsupported',
+    reason: 'adaptive actuation is interface-only (P3); proposals are recorded, never applied',
+    ...(kbId ? { kb_id: kbId } : {}),
+  };
+}

package/src/core/observability/privacy/allowlist.js

@@ -11,7 +11,7 @@
  * redaction rules change so downstream readers can detect stale records.
  */
 
-export const REDACTION_VERSION = 'df-redact-3';
+export const REDACTION_VERSION = 'df-redact-5';
 
 /**
  * Envelope fields permitted on a persisted record (DF-FR01) plus the
@@ -39,6 +39,11 @@ export const ALLOWED_FIELDS = new Set([
   'payload',
   'origin',
   'redaction_version',
+  // DF2-FR01 v1.1 additive envelope fields: multi-agent correlation ids and
+  // the recorder's sampling policy stamp — additive, never required.
+  'agent_id',
+  'project_instance_id',
+  'sampling',
 ]);
 
 /**
@@ -130,7 +135,7 @@ export const ALLOWED_SUPPORT_PAYLOAD_FIELDS = new Set([
   'exit_code',
   'signal',
   'attempt',
-  'attempts',
+  'attempt_index',
   'retry_count',
   'duration_ms',
   'elapsed_ms',
@@ -140,6 +145,7 @@ export const ALLOWED_SUPPORT_PAYLOAD_FIELDS = new Set([
   'count',
   'total',
   'dropped',
+  'dropped_count',
   'sampled',
   'truncated',
   'cache',
@@ -157,8 +163,22 @@ export const ALLOWED_SUPPORT_PAYLOAD_FIELDS = new Set([
   'p95',
   'p99',
   'min',
-  'max',
   'mean',
+  // DF2-FR01 v1.1: metadata-only payload keys for the new semantic names —
+  // counts, kinds, opaque refs, verdict, detector, evidence_refs, crash
+  // codes/digest, and the sampling stamp shape. Never content fields.
+  'item_count',
+  'ref',
+  'trace_ref',
+  'execution_ref',
+  'verdict',
+  'detector',
+  'evidence_refs',
+  'cohort_key',
+  'codes',
+  'digest',
+  'policy_version',
+  'rate',
 ]);
 
 // --- size caps (prototype defaults per SPEC §14; freeze after measurement) ---

package/src/core/observability/schema/compatibility.js

@@ -109,9 +109,9 @@ export function checkRegistryCompatibility(prev, next, options = {}) {
 }
 
 /**
- * Gate a semantic envelope on its declared schema major. Tolerates any
- * unknown optional fields — version compatibility is judged ONLY on
- * `schema_version` (DF-FR03 additive-only tolerance lives upstream in
+ * Gate a semantic envelope on its declared schema major. The version gate
+ * itself never inspects fields — compatibility is judged ONLY on
+ * `schema_version` (envelope-field strictness lives in
  * validateSemanticRecord).
  *
  * @param {object} record — candidate semantic envelope.
@@ -133,3 +133,48 @@ export function validateEnvelopeSchemaVersion(record) {
   }
   return { ok: true };
 }
+
+/**
+ * Reader tolerance check (DF2-FR01): a v1 reader can consume records that
+ * carry v1.1 additive envelope fields (agent_id, project_instance_id,
+ * sampling) because the additive contract keeps schema_version at 1.
+ * The check gates on schema_version and REPORTS which fields were newer
+ * than the reader's known set — tolerance is observed, not assumed.
+ *
+ * @param {object} record — candidate semantic envelope.
+ * @returns {{ ok: true, newerFields: string[] } | { ok: false, reason: string }}
+ */
+export function checkReaderTolerance(record) {
+  const gate = validateEnvelopeSchemaVersion(record);
+  if (!gate.ok) return gate;
+  const newerFields = Object.keys(record).filter((key) => !V1_0_ENVELOPE_FIELDS.has(key));
+  return { ok: true, newerFields };
+}
+
+// The v1.0 baseline envelope — what a reader frozen before the v1.1
+// additive release knows about. `redaction_version` is the stamp
+// sanitizeObserved adds before persistence; v1.1's agent_id,
+// project_instance_id and sampling are intentionally ABSENT so the check
+// reports them as tolerated-but-newer.
+const V1_0_ENVELOPE_FIELDS = new Set([
+  'record_type',
+  'semantic_name',
+  'schema_version',
+  'record_id',
+  'trace_id',
+  'span_id',
+  'parent_span_id',
+  'execution_id',
+  'session_id',
+  'project_ref',
+  'boot_id',
+  'writer_id',
+  'sequence',
+  'wall_time_utc',
+  'monotonic_ns',
+  'importance',
+  'privacy_class',
+  'origin',
+  'payload',
+  'redaction_version',
+]);

package/src/core/observability/schema/constants.js

@@ -26,6 +26,11 @@ export const ENVELOPE_FIELDS = Object.freeze([
   'privacy_class',
   'origin',
   'payload',
+  // DF2-FR01 v1.1 additive optional fields (introduced_version '1.1') —
+  // multi-agent correlation ids and the recorder's sampling policy stamp.
+  'agent_id',
+  'project_instance_id',
+  'sampling',
 ]);
 
 export const REQUIRED_ENVELOPE_FIELDS = Object.freeze([

package/src/core/observability/schema/registry.js

@@ -14,6 +14,7 @@
 import { PRIVACY_CLASSES } from './constants.js';
 
 const V1 = '1';
+const V1_1 = '1.1';
 
 export const SEMANTIC_REGISTRY = Object.freeze({
   'execution.started': {
@@ -160,6 +161,55 @@ export const SEMANTIC_REGISTRY = Object.freeze({
     introduced_version: V1,
     deprecated: null,
   },
+  // --- schema v1.1 additions (DF2-FR01, append-only) ---
+  'memory.write': {
+    definition: 'A memory item was written to the store. Payload carries counts, kinds and an opaque ref — never content.',
+    unit: 'items',
+    privacy_class: 'sensitive',
+    retention_hint: 'aggregate',
+    introduced_version: V1_1,
+    deprecated: null,
+  },
+  'memory.retrieved': {
+    definition: 'Memory items were retrieved for a task. Payload carries counts, kinds and an opaque ref — never content.',
+    unit: 'items',
+    privacy_class: 'sensitive',
+    retention_hint: 'aggregate',
+    introduced_version: V1_1,
+    deprecated: null,
+  },
+  'retrieval.query': {
+    definition: 'A retrieval query ran against memory or context stores. Payload carries the query kind, result count and duration — never query text.',
+    unit: 'ms',
+    privacy_class: 'internal',
+    retention_hint: 'aggregate',
+    introduced_version: V1_1,
+    deprecated: null,
+  },
+  'outcome.observed': {
+    definition: 'A user or system outcome signal was observed and linked to a trace or execution ref. Payload carries verdict, kind, source and evidence_refs.',
+    unit: 'event',
+    privacy_class: 'internal',
+    retention_hint: 'retain',
+    introduced_version: V1_1,
+    deprecated: null,
+  },
+  'anomaly.detected': {
+    definition: 'A deterministic detector flagged an anomalous trace. Payload carries detector, kind, evidence_refs, typed confidence and cohort_key.',
+    unit: 'event',
+    privacy_class: 'internal',
+    retention_hint: 'retain',
+    introduced_version: V1_1,
+    deprecated: null,
+  },
+  'telemetry.crashed': {
+    definition: 'The host process crashed or exited abnormally; capture wrote a bounded crash file. Payload carries signal/error kind codes and a digest — never stacks or paths.',
+    unit: 'event',
+    privacy_class: 'internal',
+    retention_hint: 'retain',
+    introduced_version: V1_1,
+    deprecated: null,
+  },
 });
 
 // Error/wait/reason vocabulary: codes + definitions, no free-text grouping.
@@ -312,6 +362,13 @@ export const REASON_CODES = Object.freeze({
     deprecated: null,
     privacy_class: 'internal',
   },
+  CONFIG_INVALID: {
+    definition: 'Sampling configuration was malformed; sampling disabled for this boot.',
+    unit: null,
+    introduced_version: V1_1,
+    deprecated: null,
+    privacy_class: 'internal',
+  },
 });
 
 // Guard: registry privacy classes must stay inside the frozen vocabulary.