@yemi33/minions 0.1.2424 → 0.1.2425

package/engine/review-learning.js

@@ -0,0 +1,1236 @@
+// engine/review-learning.js — bounded domain primitives for review-derived memory.
+
+const crypto = require('crypto');
+const {
+  normalizeIsoTimestamp,
+  parseCanonicalPrId,
+  redactSecrets,
+  truncateTextBytes,
+} = require('./shared');
+
+const REVIEW_LEARNING_SOURCE_TYPE = 'review-learning';
+const REVIEW_LEARNING_DISPOSITIONS = Object.freeze({
+  ACCEPTED_FIXED: 'accepted-fixed',
+  SATISFIED_ELSEWHERE: 'satisfied-elsewhere',
+  INVALID: 'invalid',
+  STALE: 'stale',
+  DEFERRED: 'deferred',
+  OUT_OF_SCOPE_FOLLOW_UP: 'out-of-scope-follow-up',
+});
+const REVIEW_LEARNING_EVENT_TYPES = Object.freeze([
+  'candidate-created',
+  'candidate-updated',
+  'created',
+  'retrieved',
+  'applied',
+  'considered-not-applicable',
+  'contradicted',
+  'retracted',
+  'restored',
+  'pinned',
+  'superseded',
+  'repeated-finding',
+  'promotion-requested',
+]);
+const REVIEW_LEARNING_APPLICATION_OUTCOMES = Object.freeze([
+  'applied',
+  'considered-not-applicable',
+  'contradicted',
+]);
+// Human operator controls map to matching lifecycle events. `pin` and
+// `restore` reactivate a lesson (retaining provenance); `retract` quarantines
+// it. Emitting these keeps the operator audit trail aligned with the
+// agent-driven application/contradiction events.
+const REVIEW_LEARNING_HUMAN_ACTION_EVENTS = Object.freeze({
+  pin: 'pinned',
+  retract: 'retracted',
+  restore: 'restored',
+});
+const REVIEW_LEARNING_BOUNDS = Object.freeze({
+  projectBytes: 120,
+  prIdBytes: 320,
+  sourceKeyBytes: 240,
+  findingKeyBytes: 640,
+  areaBytes: 360,
+  titleBytes: 240,
+  bodyBytes: 4096,
+  ruleBytes: 1024,
+  rules: 8,
+  facets: 20,
+  facetBytes: 300,
+  evidence: 20,
+  evidenceBytes: 400,
+  metadataBytes: 4096,
+  metadataStringBytes: 768,
+  metadataKeys: 32,
+  metadataItems: 32,
+  metadataEntries: 128,
+  metadataDepth: 3,
+  selectedIds: 32,
+  selectedIdBytes: 160,
+  selectedIdsBytes: 4096,
+  decisionTraceEntries: 64,
+  decisionReasons: 8,
+  decisionReasonBytes: 96,
+  decisionTraceBytes: 8192,
+  queryBytes: 2048,
+  eventKeyBytes: 64,
+  refBytes: 320,
+  commentSources: 64,
+  commentAuthorBytes: 160,
+  completionLearnings: 8,
+  completionApplications: 32,
+  completionLearningsBytes: 65536,
+  completionApplicationsBytes: 16384,
+  completionMemoryIdBytes: 160,
+  applicationEvidenceBytes: 400,
+  diagnostics: 8,
+  diagnosticBytes: 600,
+  transitionEvidence: 4,
+  lifecycleEvents: 50000,
+  retrievalRuns: 5000,
+  // Retention (P-1ed2fb5f): unresolved candidates expire after 180 days;
+  // compact lifecycle events are retained for at most one year (in addition to
+  // the 50000-row cap). These windows are deliberately decoupled from KB file
+  // TTL — active procedural lessons persist until superseded or retracted.
+  candidateExpiryMs: 180 * 24 * 60 * 60 * 1000,
+  lifecycleEventMaxAgeMs: 365 * 24 * 60 * 60 * 1000,
+  applicableTopK: 4,
+  applicableBytes: 4096,
+});
+
+const DISPOSITIONS = new Set(Object.values(REVIEW_LEARNING_DISPOSITIONS));
+const POSITIVE_DISPOSITIONS = new Set([
+  REVIEW_LEARNING_DISPOSITIONS.ACCEPTED_FIXED,
+  REVIEW_LEARNING_DISPOSITIONS.SATISFIED_ELSEWHERE,
+]);
+const EVENT_TYPES = new Set(REVIEW_LEARNING_EVENT_TYPES);
+const APPLICATION_OUTCOMES = new Set(REVIEW_LEARNING_APPLICATION_OUTCOMES);
+const AUDIENCES = new Set(['author', 'project-team']);
+const PROHIBITED_FIELD_RE = /^(?:body|content|text|prompt|messages?|conversation|transcript|chain[-_]?of[-_]?thought|reasoning|stdout|stderr|raw(?:prompt|comment|reviewer|transcript))$|(?:raw|prompt|comment|reviewer|transcript|conversation).*(?:body|content|text|payload|output)|(?:chain[-_]?of[-_]?thought|reasoning)/i;
+const DECISION_KEYS = new Set(['id', 'selected', 'rank', 'score', 'reason', 'reasons', 'decision', 'outcome']);
+
+const CANDIDATE_TRANSITIONS = Object.freeze({
+  [REVIEW_LEARNING_DISPOSITIONS.ACCEPTED_FIXED]: Object.freeze({
+    status: 'superseded',
+    candidateState: 'promoted',
+    terminal: true,
+    requiresLesson: true,
+  }),
+  [REVIEW_LEARNING_DISPOSITIONS.SATISFIED_ELSEWHERE]: Object.freeze({
+    status: 'superseded',
+    candidateState: 'promoted',
+    terminal: true,
+    requiresLesson: true,
+  }),
+  [REVIEW_LEARNING_DISPOSITIONS.INVALID]: Object.freeze({
+    status: 'retracted',
+    candidateState: 'closed-invalid',
+    terminal: true,
+    requiresLesson: false,
+  }),
+  [REVIEW_LEARNING_DISPOSITIONS.STALE]: Object.freeze({
+    status: 'expired',
+    candidateState: 'closed-stale',
+    terminal: true,
+    requiresLesson: false,
+  }),
+  [REVIEW_LEARNING_DISPOSITIONS.DEFERRED]: Object.freeze({
+    status: 'candidate',
+    candidateState: 'deferred',
+    terminal: false,
+    requiresLesson: false,
+  }),
+  [REVIEW_LEARNING_DISPOSITIONS.OUT_OF_SCOPE_FOLLOW_UP]: Object.freeze({
+    status: 'candidate',
+    candidateState: 'follow-up',
+    terminal: false,
+    requiresLesson: false,
+  }),
+});
+
+function _byteLength(value) {
+  return Buffer.byteLength(String(value || ''), 'utf8');
+}
+
+function _required(value, label) {
+  const text = String(value == null ? '' : value).trim();
+  if (!text) throw new TypeError(`${label} is required`);
+  return text;
+}
+
+function _boundedIdentifier(value, maxBytes, label, pattern = /^[a-z0-9][a-z0-9._:/#|@+-]*$/i) {
+  const text = _required(value, label);
+  if (_byteLength(text) > maxBytes) throw new TypeError(`${label} exceeds ${maxBytes} bytes`);
+  if (!pattern.test(text)) throw new TypeError(`${label} has an invalid format`);
+  return text;
+}
+
+function _optionalIdentifier(value, maxBytes, label) {
+  if (value == null || String(value).trim() === '') return null;
+  return _boundedIdentifier(value, maxBytes, label);
+}
+
+function _shortHash(value) {
+  return crypto.createHash('sha256').update(String(value)).digest('hex').slice(0, 16);
+}
+
+function _ruleHash(value) {
+  return `sha256:${crypto.createHash('sha256').update(String(value)).digest('hex')}`;
+}
+
+function redactBoundedText(value, maxBytes, label = 'text') {
+  const limit = Math.max(0, Math.floor(Number(maxBytes) || 0));
+  if (!limit) return '';
+  const redacted = redactSecrets(String(value == null ? '' : value));
+  return truncateTextBytes(redacted.trim(), limit);
+}
+
+function normalizeDisposition(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (normalized === 'already-resolved') return REVIEW_LEARNING_DISPOSITIONS.SATISFIED_ELSEWHERE;
+  if (!DISPOSITIONS.has(normalized)) throw new TypeError(`invalid review-learning disposition: ${value}`);
+  return normalized;
+}
+
+function normalizeProjectKey(value) {
+  const project = _required(value, 'review-learning project')
+    .toLowerCase()
+    .replace(/\s+/g, '-');
+  return _boundedIdentifier(
+    project,
+    REVIEW_LEARNING_BOUNDS.projectBytes,
+    'review-learning project',
+    /^[a-z0-9][a-z0-9._-]*$/,
+  );
+}
+
+function normalizeCanonicalPrId(value) {
+  const input = _required(value, 'canonical PR id');
+  const parsed = parseCanonicalPrId(input);
+  if (!parsed || !Number.isSafeInteger(parsed.prNumber) || parsed.prNumber < 1) {
+    throw new TypeError(`invalid canonical PR id: ${input}`);
+  }
+  const separator = parsed.scope.indexOf(':');
+  const host = parsed.scope.slice(0, separator);
+  const segments = parsed.scope.slice(separator + 1).split('/').map(segment => (
+    segment.replace(/%20/gi, ' ').trim().toLowerCase()
+  ));
+  let expectedSegments = 0;
+  if (host === 'github') expectedSegments = 2;
+  else if (host === 'ado') expectedSegments = 3;
+  const invalidSegment = segments.some(segment => (
+    !segment
+    || /[|#\u0000-\u001f\u007f]/.test(segment)
+    || (host === 'github' && !/^[a-z0-9][a-z0-9._-]*$/.test(segment))
+  ));
+  if (!expectedSegments || segments.length !== expectedSegments || invalidSegment) {
+    throw new TypeError(`invalid canonical PR id: ${input}`);
+  }
+  const normalized = `${host}:${segments.join('/')}#${parsed.prNumber}`;
+  return _boundedIdentifier(
+    normalized,
+    REVIEW_LEARNING_BOUNDS.prIdBytes,
+    'canonical PR id',
+    /^(?:github|ado):[^|#\u0000-\u001f\u007f]+#[1-9]\d*$/,
+  );
+}
+
+function normalizeFindingSourceKey(value) {
+  const input = _required(value, 'finding source key').toLowerCase();
+  const parts = input.split(':');
+  if (parts.length < 3 || !['github', 'ado'].includes(parts[0])) {
+    throw new TypeError('finding source key must be host-namespaced with github: or ado:');
+  }
+  for (const part of parts) {
+    if (!/^[a-z0-9][a-z0-9._-]*$/.test(part)) {
+      throw new TypeError(`invalid finding source key segment: ${part}`);
+    }
+  }
+  if (_byteLength(input) > REVIEW_LEARNING_BOUNDS.sourceKeyBytes) {
+    throw new TypeError(`finding source key exceeds ${REVIEW_LEARNING_BOUNDS.sourceKeyBytes} bytes`);
+  }
+  return input;
+}
+
+function _normalizeTimestamp(value) {
+  return normalizeIsoTimestamp(value);
+}
+
+function hashReviewCommentContent(content) {
+  return `sha256:${crypto.createHash('sha256').update(String(content || ''), 'utf8').digest('hex')}`;
+}
+
+function buildReviewCommentSource(input = {}) {
+  const host = String(input.host || '').trim().toLowerCase().replace(/^gh$/, 'github');
+  const commentId = _boundedIdentifier(input.commentId, 160, 'review comment id');
+  const commentType = String(input.commentType || '').trim().toLowerCase();
+  let key;
+  let threadId = null;
+
+  if (host === 'github') {
+    if (commentType !== 'issue' && commentType !== 'review') {
+      throw new TypeError(`invalid GitHub review comment type: ${input.commentType}`);
+    }
+    key = `github:${commentType}-comment:${commentId.toLowerCase()}`;
+  } else if (host === 'ado') {
+    threadId = _boundedIdentifier(input.threadId, 160, 'ADO review thread id').toLowerCase();
+    key = `ado:thread:${threadId}:comment:${commentId.toLowerCase()}`;
+  } else {
+    throw new TypeError(`invalid review comment host: ${input.host}`);
+  }
+
+  return {
+    key: normalizeFindingSourceKey(key),
+    ...(host === 'github' ? { commentType } : { threadId, commentType: commentType || 'text' }),
+    author: redactBoundedText(
+      input.author || 'unknown',
+      REVIEW_LEARNING_BOUNDS.commentAuthorBytes,
+      'review comment author',
+    ),
+    createdAt: _normalizeTimestamp(input.createdAt),
+    updatedAt: _normalizeTimestamp(input.updatedAt || input.createdAt),
+    contentHash: hashReviewCommentContent(input.content),
+  };
+}
+
+function normalizeReviewCommentSources(sources) {
+  if (!Array.isArray(sources)) return [];
+  const byKey = new Map();
+  for (const source of sources) {
+    if (!source || typeof source !== 'object') continue;
+    const key = normalizeFindingSourceKey(source.key);
+    const githubMatch = key.match(/^github:(issue|review)-comment:([^:]+)$/);
+    const adoMatch = key.match(/^ado:thread:([^:]+):comment:([^:]+)$/);
+    if (!githubMatch && !adoMatch) throw new TypeError(`unsupported review comment source key: ${key}`);
+    const contentHash = String(source.contentHash || '').trim().toLowerCase();
+    if (!/^sha256:[0-9a-f]{64}$/.test(contentHash)) {
+      throw new TypeError(`invalid review comment content hash for ${key}`);
+    }
+    const normalized = {
+      key,
+      ...(githubMatch
+        ? { commentType: githubMatch[1] }
+        : {
+            threadId: adoMatch[1],
+            commentType: redactBoundedText(source.commentType || 'text', 48, 'ADO comment type').toLowerCase(),
+          }),
+      author: redactBoundedText(
+        source.author || 'unknown',
+        REVIEW_LEARNING_BOUNDS.commentAuthorBytes,
+        'review comment author',
+      ),
+      createdAt: _normalizeTimestamp(source.createdAt),
+      updatedAt: _normalizeTimestamp(source.updatedAt || source.createdAt),
+      contentHash,
+    };
+    byKey.set(key, normalized);
+  }
+  return [...byKey.values()]
+    .sort((a, b) => (
+      String(a.updatedAt || a.createdAt || '').localeCompare(String(b.updatedAt || b.createdAt || ''))
+      || a.key.localeCompare(b.key)
+    ))
+    .slice(-REVIEW_LEARNING_BOUNDS.commentSources);
+}
+
+function selectReviewCommentSourceSnapshot(currentFeedback, observedSources) {
+  const current = normalizeReviewCommentSources(currentFeedback?.commentSources);
+  if (currentFeedback?.pendingFix && String(currentFeedback.feedbackContent || '').trim() && current.length > 0) {
+    return current;
+  }
+  return normalizeReviewCommentSources(observedSources);
+}
+
+function migrateLegacyReviewCommentEdits(previous, sourceKeys) {
+  if (!previous || typeof previous !== 'object' || Array.isArray(previous)) return {};
+  const keys = [...new Set((Array.isArray(sourceKeys) ? sourceKeys : [])
+    .map(normalizeFindingSourceKey))];
+  const bareIds = keys.map(key => key.slice(key.lastIndexOf(':') + 1));
+  const counts = new Map();
+  for (const id of bareIds) counts.set(id, (counts.get(id) || 0) + 1);
+  const migrated = {};
+  for (let index = 0; index < keys.length; index++) {
+    const key = keys[index];
+    const bareId = bareIds[index];
+    if (previous[key] != null) {
+      migrated[key] = previous[key];
+    } else if (counts.get(bareId) === 1 && previous[bareId] != null) {
+      migrated[key] = previous[bareId];
+    }
+  }
+  return migrated;
+}
+
+function buildFindingKey({ project, prId, pr, sourceKey } = {}) {
+  const normalizedProject = normalizeProjectKey(project);
+  const normalizedPr = normalizeCanonicalPrId(prId || pr);
+  const normalizedSource = normalizeFindingSourceKey(sourceKey);
+  const prHost = normalizedPr.slice(0, normalizedPr.indexOf(':'));
+  const sourceHost = normalizedSource.slice(0, normalizedSource.indexOf(':'));
+  if (prHost !== sourceHost) {
+    throw new TypeError(`finding source host ${sourceHost} does not match PR host ${prHost}`);
+  }
+  const findingKey = `${normalizedProject}|${normalizedPr}|${normalizedSource}`;
+  if (_byteLength(findingKey) > REVIEW_LEARNING_BOUNDS.findingKeyBytes) {
+    throw new TypeError(`finding key exceeds ${REVIEW_LEARNING_BOUNDS.findingKeyBytes} bytes`);
+  }
+  return findingKey;
+}
+
+function normalizeFindingKey(value) {
+  const parts = _required(value, 'finding key').split('|');
+  if (parts.length !== 3) throw new TypeError('finding key must contain project, PR, and source identity');
+  return buildFindingKey({ project: parts[0], prId: parts[1], sourceKey: parts[2] });
+}
+
+function _assertFindingScope(findingKey, project, prId) {
+  const [findingProject, findingPr] = findingKey.split('|');
+  if (findingProject !== project) {
+    throw new TypeError(`finding key project ${findingProject} does not match record scope ${project}`);
+  }
+  if (findingPr !== prId) {
+    throw new TypeError(`finding key PR ${findingPr} does not match record PR ${prId}`);
+  }
+}
+
+function _normalizeFile(value) {
+  let file = String(value == null ? '' : value).trim().replace(/\\/g, '/').toLowerCase();
+  file = file.replace(/:\d+(?::\d+)?$/, '').replace(/^\.\//, '').replace(/\/+/g, '/');
+  if (!file || file.startsWith('/') || /^[a-z]:\//.test(file)) return '';
+  const parts = file.split('/');
+  if (parts.some(part => !part || part === '.' || part === '..')) return '';
+  file = file.replace(/\s+/g, '-');
+  if (!/^[a-z0-9@+_.\-/]+$/.test(file)) return '';
+  return _byteLength(file) <= REVIEW_LEARNING_BOUNDS.facetBytes ? file : '';
+}
+
+function _normalizeSymbol(value) {
+  const symbol = String(value == null ? '' : value).trim().toLowerCase().replace(/\s+/g, '');
+  if (!symbol || !/^[a-z_$][a-z0-9_$#.:/<>,~+-]*$/.test(symbol)) return '';
+  return _byteLength(symbol) <= REVIEW_LEARNING_BOUNDS.facetBytes ? symbol : '';
+}
+
+function _normalizeTag(value) {
+  const tag = String(value == null ? '' : value).trim().toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  if (!tag) return '';
+  return _byteLength(tag) <= 64 ? tag : '';
+}
+
+function _normalizeList(values, normalizer, max = REVIEW_LEARNING_BOUNDS.facets) {
+  const input = Array.isArray(values) ? values : (values == null || values === '' ? [] : [values]);
+  const normalized = [...new Set(input.map(normalizer).filter(Boolean))].sort();
+  return normalized.slice(0, max);
+}
+
+function normalizeReviewFacets(input = {}) {
+  const files = _normalizeList(input.files, _normalizeFile);
+  const symbols = _normalizeList(input.symbols, _normalizeSymbol);
+  const tags = _normalizeList(input.tags, _normalizeTag);
+  return { files, symbols, tags, area: normalizeReviewArea({ files, symbols, tags }) };
+}
+
+function normalizeReviewArea(input = {}) {
+  if (typeof input === 'string') {
+    const area = input.trim().toLowerCase().replace(/\\/g, '/');
+    if (area === 'general') return area;
+    if (!/^(?:symbol|file|tags):[a-z0-9@+_$#.,:|<>=~\-/]+$/.test(area)) {
+      throw new TypeError(`invalid review-learning area: ${input}`);
+    }
+    if (_byteLength(area) > REVIEW_LEARNING_BOUNDS.areaBytes) {
+      throw new TypeError(`review-learning area exceeds ${REVIEW_LEARNING_BOUNDS.areaBytes} bytes`);
+    }
+    return area;
+  }
+  const symbols = _normalizeList(input.symbols, _normalizeSymbol);
+  if (symbols.length) return `symbol:${symbols[0]}`;
+  const files = _normalizeList(input.files, _normalizeFile);
+  const tags = _normalizeList(input.tags, _normalizeTag);
+  if (files.length) return `file:${files[0]}${tags.length ? `|tags:${tags.join(',')}` : ''}`;
+  if (tags.length) return `tags:${tags.join(',')}`;
+  return 'general';
+}
+
+function _assertSafeFieldName(key) {
+  if (!/^[a-z][a-z0-9_.-]{0,63}$/i.test(key)) throw new TypeError(`invalid metadata field: ${key}`);
+  if (PROHIBITED_FIELD_RE.test(key)) throw new TypeError(`prohibited review-learning field: ${key}`);
+}
+
+function assertNoProhibitedReviewPayload(value, depth = 0) {
+  if (depth > REVIEW_LEARNING_BOUNDS.metadataDepth + 2 || value == null) return;
+  if (Array.isArray(value)) {
+    for (const entry of value) assertNoProhibitedReviewPayload(entry, depth + 1);
+    return;
+  }
+  if (typeof value !== 'object') return;
+  for (const [key, nested] of Object.entries(value)) {
+    _assertSafeFieldName(key);
+    assertNoProhibitedReviewPayload(nested, depth + 1);
+  }
+}
+
+function _normalizeMetadataValue(value, depth, state) {
+  if (depth > REVIEW_LEARNING_BOUNDS.metadataDepth) {
+    throw new TypeError(`review-learning metadata exceeds depth ${REVIEW_LEARNING_BOUNDS.metadataDepth}`);
+  }
+  state.entries += 1;
+  if (state.entries > REVIEW_LEARNING_BOUNDS.metadataEntries) {
+    throw new TypeError(`review-learning metadata exceeds ${REVIEW_LEARNING_BOUNDS.metadataEntries} entries`);
+  }
+  if (value == null || typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new TypeError('review-learning metadata numbers must be finite');
+    return value;
+  }
+  if (typeof value === 'string') {
+    return redactBoundedText(
+      value,
+      REVIEW_LEARNING_BOUNDS.metadataStringBytes,
+      'review-learning metadata string',
+    );
+  }
+  if (Array.isArray(value)) {
+    if (value.length > REVIEW_LEARNING_BOUNDS.metadataItems) {
+      throw new TypeError(`review-learning metadata arrays are limited to ${REVIEW_LEARNING_BOUNDS.metadataItems} items`);
+    }
+    return value.map(item => _normalizeMetadataValue(item, depth + 1, state));
+  }
+  if (typeof value === 'object') {
+    const entries = Object.entries(value).filter(([, nested]) => nested !== undefined);
+    if (entries.length > REVIEW_LEARNING_BOUNDS.metadataKeys) {
+      throw new TypeError(`review-learning metadata objects are limited to ${REVIEW_LEARNING_BOUNDS.metadataKeys} keys`);
+    }
+    const normalized = {};
+    for (const [key, nested] of entries) {
+      _assertSafeFieldName(key);
+      normalized[key] = _normalizeMetadataValue(nested, depth + 1, state);
+    }
+    return normalized;
+  }
+  throw new TypeError(`unsupported review-learning metadata value: ${typeof value}`);
+}
+
+function normalizeReviewMetadata(metadata = {}) {
+  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
+    throw new TypeError('review-learning metadata must be an object');
+  }
+  const normalized = _normalizeMetadataValue(metadata, 0, { entries: 0 });
+  if (_byteLength(JSON.stringify(normalized)) > REVIEW_LEARNING_BOUNDS.metadataBytes) {
+    throw new TypeError(`review-learning metadata exceeds ${REVIEW_LEARNING_BOUNDS.metadataBytes} bytes`);
+  }
+  return normalized;
+}
+
+function _normalizeAgent(value, label) {
+  return _boundedIdentifier(
+    String(value || '').trim().toLowerCase(),
+    96,
+    label,
+    /^[a-z][a-z0-9-]*$/,
+  );
+}
+
+function _normalizeEvidence(values) {
+  const input = Array.isArray(values) ? values : (values == null || values === '' ? [] : [values]);
+  return [...new Set(input.map(value => redactBoundedText(
+    value,
+    REVIEW_LEARNING_BOUNDS.evidenceBytes,
+    'review-learning evidence',
+  )).filter(Boolean))].slice(0, REVIEW_LEARNING_BOUNDS.evidence);
+}
+
+function classifyExactEvidence(values) {
+  const kinds = new Set();
+  for (const value of _normalizeEvidence(values)) {
+    if (/(?:^|[\s`("'[])(?:[a-z]:[\\/])?[\w@+./\\-]+\.[a-z0-9]+:\d+(?::\d+)?\b/i.test(value)) {
+      kinds.add('current-code');
+    }
+    if (/\bcommit(?:\s+|[:#])?[0-9a-f]{7,40}\b/i.test(value)) {
+      kinds.add('commit');
+    }
+    if (/(?:^|[\s`("'[])(?:\.\/)?(?:test|tests)\/[\w@+./-]+\.(?:test|spec)\.[a-z0-9]+(?::\d+(?::\d+)?)?\b/i.test(value)) {
+      kinds.add('test');
+    }
+  }
+  return [...kinds].sort();
+}
+
+function _assertCompletionObject(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError(`${label} must be an object`);
+  }
+  return value;
+}
+
+function _assertCompletionFields(value, allowed, label) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) throw new TypeError(`${label} has unsupported field: ${key}`);
+  }
+}
+
+function _completionString(value, label, maxBytes, { required = true } = {}) {
+  if (typeof value !== 'string') throw new TypeError(`${label} must be a string`);
+  const normalized = redactBoundedText(value, maxBytes, label);
+  if (required && !normalized) throw new TypeError(`${label} is required`);
+  return normalized;
+}
+
+function _completionIdentifier(value, label, maxBytes, pattern) {
+  if (typeof value !== 'string') throw new TypeError(`${label} must be a string`);
+  return _boundedIdentifier(value, maxBytes, label, pattern);
+}
+
+function _completionStringList(values, label, maxItems, maxBytes, normalizer, { required = false } = {}) {
+  if (!Array.isArray(values)) throw new TypeError(`${label} must be an array`);
+  if (values.length > maxItems) throw new TypeError(`${label} is limited to ${maxItems} entries`);
+  const normalized = [];
+  const seen = new Set();
+  for (const value of values) {
+    if (typeof value !== 'string') throw new TypeError(`${label} entries must be strings`);
+    const item = normalizer
+      ? normalizer(value)
+      : redactBoundedText(value, maxBytes, `${label} entry`);
+    if (!item) throw new TypeError(`${label} contains an invalid entry`);
+    if (seen.has(item)) continue;
+    seen.add(item);
+    normalized.push(item);
+  }
+  if (required && normalized.length === 0) throw new TypeError(`${label} requires at least one entry`);
+  return normalized;
+}
+
+function _normalizeCompletionFile(value) {
+  return _normalizeFile(value);
+}
+
+function _normalizeCompletionSymbol(value) {
+  const symbol = String(value == null ? '' : value).trim();
+  if (/\s/.test(symbol)) return '';
+  return _normalizeSymbol(symbol);
+}
+
+function _normalizeCompletionTag(value) {
+  return _normalizeTag(value);
+}
+
+function _normalizeCompletionMemoryId(value, label) {
+  return _completionIdentifier(
+    value,
+    label,
+    REVIEW_LEARNING_BOUNDS.completionMemoryIdBytes,
+    /^M-[a-z0-9][a-z0-9._:-]*$/i,
+  );
+}
+
+function _normalizeCompletionContext(context = {}) {
+  const project = normalizeProjectKey(context.project);
+  const prId = normalizeCanonicalPrId(context.prId || context.pr);
+  const authorAgent = _normalizeAgent(context.authorAgent, 'completion author agent');
+  const rawAllowed = context.allowedSourceKeys instanceof Set
+    ? [...context.allowedSourceKeys]
+    : context.allowedSourceKeys;
+  if (!Array.isArray(rawAllowed)) throw new TypeError('allowed review-learning sources must be an array');
+  const allowedSourceKeys = new Set(rawAllowed.map((value) => {
+    if (typeof value !== 'string') throw new TypeError('allowed review-learning source keys must be strings');
+    const sourceKey = normalizeFindingSourceKey(value);
+    buildFindingKey({ project, prId, sourceKey });
+    return sourceKey;
+  }));
+  return { project, prId, authorAgent, allowedSourceKeys };
+}
+
+function _normalizeCompletionLearning(input, context) {
+  _assertCompletionObject(input, 'review learning');
+  assertNoProhibitedReviewPayload(input);
+  _assertCompletionFields(input, new Set([
+    'rule',
+    'disposition',
+    'source',
+    'project',
+    'authorAgent',
+    'applicability',
+    'files',
+    'symbols',
+    'tags',
+    'evidence',
+    'confidence',
+    'repeatedOf',
+  ]), 'review learning');
+
+  const source = _assertCompletionObject(input.source, 'review learning source');
+  _assertCompletionFields(source, new Set(['pr', 'sourceKey']), 'review learning source');
+  if (typeof source.pr !== 'string') throw new TypeError('review learning source PR must be a string');
+  if (typeof source.sourceKey !== 'string') throw new TypeError('review learning source key must be a string');
+  const sourcePr = normalizeCanonicalPrId(source.pr);
+  if (sourcePr !== context.prId) {
+    throw new TypeError(`review learning source does not match dispatch PR ${context.prId}`);
+  }
+  const sourceKey = normalizeFindingSourceKey(source.sourceKey);
+  if (!context.allowedSourceKeys.has(sourceKey)) {
+    throw new TypeError('review learning source key is not an allowed source for this dispatch');
+  }
+
+  if (typeof input.project !== 'string') throw new TypeError('review learning project must be a string');
+  const project = normalizeProjectKey(input.project);
+  if (project !== context.project) {
+    throw new TypeError(`review learning project does not match dispatch project ${context.project}`);
+  }
+  if (typeof input.authorAgent !== 'string') throw new TypeError('review learning author agent must be a string');
+  const authorAgent = _normalizeAgent(input.authorAgent, 'review learning author agent');
+  if (authorAgent !== context.authorAgent) {
+    throw new TypeError(`review learning author agent does not match dispatch author agent ${context.authorAgent}`);
+  }
+  if (typeof input.applicability !== 'string') {
+    throw new TypeError('review learning applicability must be a string');
+  }
+  const applicability = input.applicability.trim().toLowerCase();
+  if (!AUDIENCES.has(applicability)) {
+    throw new TypeError(`invalid review learning applicability: ${input.applicability}`);
+  }
+  if (typeof input.disposition !== 'string') {
+    throw new TypeError('review learning disposition must be a string');
+  }
+  const disposition = normalizeDisposition(input.disposition);
+  if (typeof input.confidence !== 'number' || !Number.isFinite(input.confidence)) {
+    throw new TypeError('review learning confidence must be a finite number');
+  }
+  if (input.confidence < 0 || input.confidence > 1) {
+    throw new TypeError('review learning confidence must be between 0 and 1');
+  }
+
+  const normalized = {
+    rule: _completionString(input.rule, 'review learning rule', REVIEW_LEARNING_BOUNDS.ruleBytes),
+    disposition,
+    source: { pr: sourcePr, sourceKey },
+    project,
+    authorAgent,
+    applicability,
+    files: _completionStringList(
+      input.files,
+      'review learning files',
+      REVIEW_LEARNING_BOUNDS.facets,
+      REVIEW_LEARNING_BOUNDS.facetBytes,
+      _normalizeCompletionFile,
+    ),
+    symbols: _completionStringList(
+      input.symbols,
+      'review learning symbols',
+      REVIEW_LEARNING_BOUNDS.facets,
+      REVIEW_LEARNING_BOUNDS.facetBytes,
+      _normalizeCompletionSymbol,
+    ),
+    tags: _completionStringList(
+      input.tags,
+      'review learning tags',
+      REVIEW_LEARNING_BOUNDS.facets,
+      64,
+      _normalizeCompletionTag,
+    ),
+    evidence: _completionStringList(
+      input.evidence,
+      'review learning evidence',
+      REVIEW_LEARNING_BOUNDS.evidence,
+      REVIEW_LEARNING_BOUNDS.evidenceBytes,
+      null,
+      { required: true },
+    ),
+    confidence: input.confidence,
+  };
+  if (input.repeatedOf != null) {
+    normalized.repeatedOf = _normalizeCompletionMemoryId(input.repeatedOf, 'review learning repeatedOf');
+  }
+  return normalized;
+}
+
+function normalizeCompletionReviewLearnings(values, context = {}) {
+  if (!Array.isArray(values)) throw new TypeError('reviewLearnings must be an array');
+  if (values.length > REVIEW_LEARNING_BOUNDS.completionLearnings) {
+    throw new TypeError(`reviewLearnings accepts at most ${REVIEW_LEARNING_BOUNDS.completionLearnings} entries`);
+  }
+  const normalizedContext = _normalizeCompletionContext(context);
+  const normalized = values.map(value => _normalizeCompletionLearning(value, normalizedContext));
+  if (_byteLength(JSON.stringify(normalized)) > REVIEW_LEARNING_BOUNDS.completionLearningsBytes) {
+    throw new TypeError(`reviewLearnings exceeds ${REVIEW_LEARNING_BOUNDS.completionLearningsBytes} bytes`);
+  }
+  return normalized;
+}
+
+function normalizeCompletionReviewLearningApplications(values) {
+  if (!Array.isArray(values)) throw new TypeError('reviewLearningApplications must be an array');
+  if (values.length > REVIEW_LEARNING_BOUNDS.completionApplications) {
+    throw new TypeError(`reviewLearningApplications accepts at most ${REVIEW_LEARNING_BOUNDS.completionApplications} entries`);
+  }
+  const seen = new Set();
+  const normalized = values.map((input) => {
+    _assertCompletionObject(input, 'review learning application');
+    assertNoProhibitedReviewPayload(input);
+    _assertCompletionFields(input, new Set(['id', 'outcome', 'evidence']), 'review learning application');
+    const id = _normalizeCompletionMemoryId(input.id, 'review learning application id');
+    if (seen.has(id)) throw new TypeError(`duplicate review learning application id: ${id}`);
+    seen.add(id);
+    if (typeof input.outcome !== 'string') {
+      throw new TypeError('review learning application outcome must be a string');
+    }
+    const outcome = input.outcome.trim().toLowerCase();
+    if (!APPLICATION_OUTCOMES.has(outcome)) {
+      throw new TypeError(`invalid review learning application outcome: ${input.outcome}`);
+    }
+    if (input.evidence == null) throw new TypeError('review learning application evidence is required');
+    const application = {
+      id,
+      outcome,
+      evidence: _completionString(
+        input.evidence,
+        'review learning application evidence',
+        REVIEW_LEARNING_BOUNDS.applicationEvidenceBytes,
+      ),
+    };
+    return application;
+  });
+  if (_byteLength(JSON.stringify(normalized)) > REVIEW_LEARNING_BOUNDS.completionApplicationsBytes) {
+    throw new TypeError(`reviewLearningApplications exceeds ${REVIEW_LEARNING_BOUNDS.completionApplicationsBytes} bytes`);
+  }
+  return normalized;
+}
+
+function _normalizeRules(input) {
+  const values = Array.isArray(input.rules)
+    ? input.rules
+    : (input.rule == null ? [] : [input.rule]);
+  if (!values.length) throw new TypeError('at least one review-learning rule is required');
+  if (values.length > REVIEW_LEARNING_BOUNDS.rules) {
+    throw new TypeError(`review-learning rules are limited to ${REVIEW_LEARNING_BOUNDS.rules}`);
+  }
+  const rules = [...new Set(values.map(value => redactBoundedText(
+    value,
+    REVIEW_LEARNING_BOUNDS.ruleBytes,
+    'review-learning rule',
+  )).filter(Boolean))].sort((a, b) => a.localeCompare(b));
+  if (!rules.length) throw new TypeError('at least one non-empty review-learning rule is required');
+  return rules;
+}
+
+function _buildLessonMetadata(base, collections) {
+  let metadata = normalizeReviewMetadata({
+    ...base,
+    ruleHashes: [],
+    files: [],
+    symbols: [],
+    tags: [],
+    evidence: [],
+  });
+  for (const [key, values] of Object.entries(collections)) {
+    for (const value of values) {
+      try {
+        metadata = normalizeReviewMetadata({
+          ...metadata,
+          [key]: [...metadata[key], value],
+        });
+      } catch (err) {
+        if (!/metadata exceeds \d+ bytes/i.test(String(err?.message || ''))) throw err;
+        break;
+      }
+    }
+  }
+  return metadata;
+}
+
+function buildCandidateMemoryRecord(input = {}) {
+  assertNoProhibitedReviewPayload(input);
+  const findingKey = normalizeFindingKey(input.findingKey);
+  const project = normalizeProjectKey(input.project);
+  const prId = normalizeCanonicalPrId(input.prId || input.pr);
+  _assertFindingScope(findingKey, project, prId);
+  const authorAgent = _normalizeAgent(input.authorAgent, 'candidate author agent');
+  const reviewerAgent = _normalizeAgent(input.reviewerAgent, 'candidate reviewer agent');
+  const area = normalizeReviewArea(input.area || input);
+  const sourceHash = input.sourceHash
+    ? _boundedIdentifier(input.sourceHash, 160, 'candidate source hash')
+    : null;
+  const metadata = normalizeReviewMetadata({
+    ...(input.metadata || {}),
+    kind: 'review-learning-candidate',
+    findingKey,
+    prId,
+    authorAgent,
+    reviewerAgent,
+    sourceHash,
+    area,
+    candidateState: 'unverified',
+    workItemId: input.workItemId || null,
+    dispatchId: input.dispatchId || null,
+  });
+  const title = `Review finding candidate ${_shortHash(findingKey)}`;
+  const body = redactBoundedText(
+    `An actionable review finding (${findingKey}) is awaiting verified resolution. `
+      + 'Verify the current code and record a canonical disposition before creating reusable guidance.',
+    REVIEW_LEARNING_BOUNDS.bodyBytes,
+    'review-learning candidate body',
+  );
+  return {
+    memoryType: 'procedural',
+    scopeType: 'project',
+    scopeKey: project,
+    title,
+    body,
+    tags: ['review-learning', 'candidate'],
+    sourceType: REVIEW_LEARNING_SOURCE_TYPE,
+    sourceRef: findingKey,
+    trust: 'system',
+    importance: 0.4,
+    confidence: 0.25,
+    status: 'candidate',
+    metadata,
+  };
+}
+
+function buildLessonMemoryRecord(input = {}) {
+  assertNoProhibitedReviewPayload(input);
+  const findingKey = normalizeFindingKey(input.findingKey);
+  const project = normalizeProjectKey(input.project);
+  const prId = normalizeCanonicalPrId(input.prId || input.pr);
+  _assertFindingScope(findingKey, project, prId);
+  const disposition = normalizeDisposition(input.disposition);
+  if (!POSITIVE_DISPOSITIONS.has(disposition)) {
+    throw new TypeError(`active review-learning lessons require a positive disposition, got ${disposition}`);
+  }
+  const authorAgent = _normalizeAgent(input.authorAgent, 'lesson author agent');
+  const audience = String(input.audience || '').trim().toLowerCase();
+  if (!AUDIENCES.has(audience)) throw new TypeError(`invalid review-learning audience: ${input.audience}`);
+  const rules = _normalizeRules(input);
+  const facets = normalizeReviewFacets(input);
+  const area = input.area ? normalizeReviewArea(input.area) : facets.area;
+  const evidence = _normalizeEvidence(input.evidence);
+  const sourceKey = findingKey.split('|')[2];
+  const confidence = Number.isFinite(Number(input.confidence))
+    ? Math.max(0, Math.min(1, Number(input.confidence)))
+    : 0.8;
+  const metadata = _buildLessonMetadata({
+    ...(input.metadata || {}),
+    kind: 'review-learning-lesson',
+    findingKey,
+    prId,
+    sourceKey,
+    authorAgent,
+    audience,
+    disposition,
+    area,
+  }, {
+    ruleHashes: rules.map(_ruleHash),
+    files: facets.files,
+    symbols: facets.symbols,
+    tags: facets.tags,
+    evidence,
+  });
+  const body = redactBoundedText(
+    `Rules:\n${rules.map(rule => `- ${rule}`).join('\n')}`,
+    REVIEW_LEARNING_BOUNDS.bodyBytes,
+    'review-learning lesson body',
+  );
+  const title = redactBoundedText(
+    `Review lesson: ${rules[0]}`,
+    REVIEW_LEARNING_BOUNDS.titleBytes,
+    'review-learning lesson title',
+  );
+  return {
+    memoryType: 'procedural',
+    scopeType: 'project',
+    scopeKey: project,
+    title,
+    body,
+    tags: ['review-learning', 'procedural', ...facets.tags],
+    sourceType: REVIEW_LEARNING_SOURCE_TYPE,
+    sourceRef: findingKey,
+    trust: 'system',
+    importance: Number.isFinite(Number(input.importance))
+      ? Math.max(0, Math.min(1, Number(input.importance)))
+      : 0.8,
+    confidence,
+    status: 'active',
+    metadata,
+  };
+}
+
+function _lessonRuleHashes(record) {
+  const metadataHashes = Array.isArray(record?.metadata?.ruleHashes)
+    ? record.metadata.ruleHashes.filter(value => /^sha256:[0-9a-f]{64}$/.test(value))
+    : [];
+  const bodyRules = metadataHashes.length === 0
+    ? String(record?.body || '')
+      .split(/\r?\n/)
+      .map(line => line.match(/^\s*-\s+(.+)$/)?.[1] || '')
+      .filter(Boolean)
+    : [];
+  return [...new Set([
+    ...metadataHashes,
+    ...bodyRules.map(rule => _ruleHash(redactBoundedText(
+      rule,
+      REVIEW_LEARNING_BOUNDS.ruleBytes,
+      'review-learning match rule',
+    ))),
+  ])].sort();
+}
+
+function findDeterministicRepeatedLessonMatch(input = {}, records = []) {
+  const current = normalizeReviewFacets(input);
+  const currentRuleHashes = _normalizeRules(input).map(_ruleHash);
+  const matches = [];
+  for (const record of Array.isArray(records) ? records : []) {
+    const lessonId = String(record?.id || '').trim();
+    if (!lessonId || record?.status !== 'active') continue;
+    if (record?.sourceType !== REVIEW_LEARNING_SOURCE_TYPE) continue;
+    if (record?.metadata?.kind !== 'review-learning-lesson') continue;
+    const prior = normalizeReviewFacets(record.metadata);
+    const exactSymbol = current.symbols.find(symbol => prior.symbols.includes(symbol));
+    if (exactSymbol) {
+      matches.push({ lessonId, reason: `exact-symbol:${exactSymbol}`, rank: 0 });
+      continue;
+    }
+    const exactFile = current.files.find(file => prior.files.includes(file));
+    if (!exactFile) continue;
+    const priorRuleHashes = _lessonRuleHashes(record);
+    const exactRuleHash = currentRuleHashes.find(ruleHash => priorRuleHashes.includes(ruleHash));
+    if (exactRuleHash) {
+      matches.push({
+        lessonId,
+        reason: `exact-file-rule:${exactFile}:${exactRuleHash.slice(0, 23)}`,
+        rank: 1,
+      });
+      continue;
+    }
+    const exactTag = current.tags.find(tag => prior.tags.includes(tag));
+    if (exactTag) {
+      matches.push({ lessonId, reason: `exact-file-tag:${exactFile}:${exactTag}`, rank: 2 });
+    }
+  }
+  matches.sort((a, b) => a.rank - b.rank
+    || a.lessonId.localeCompare(b.lessonId)
+    || a.reason.localeCompare(b.reason));
+  if (!matches.length) return null;
+  const { lessonId, reason } = matches[0];
+  return { lessonId, reason };
+}
+
+function candidateTransitionFor(disposition) {
+  const normalized = normalizeDisposition(disposition);
+  return { disposition: normalized, ...CANDIDATE_TRANSITIONS[normalized] };
+}
+
+function normalizeSelectedIds(values) {
+  if (values == null) return [];
+  if (!Array.isArray(values)) throw new TypeError('retrieval selectedIds must be an array');
+  const selected = [];
+  const seen = new Set();
+  for (const value of values) {
+    const id = redactBoundedText(value, REVIEW_LEARNING_BOUNDS.selectedIdBytes, 'selected memory id')
+      .replace(/\s+/g, '-');
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    selected.push(id);
+    if (selected.length >= REVIEW_LEARNING_BOUNDS.selectedIds) break;
+  }
+  while (_byteLength(JSON.stringify(selected)) > REVIEW_LEARNING_BOUNDS.selectedIdsBytes) selected.pop();
+  return selected;
+}
+
+function _normalizeReason(value) {
+  return redactBoundedText(value, REVIEW_LEARNING_BOUNDS.decisionReasonBytes, 'retrieval reason')
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function normalizeDecisionTrace(values) {
+  if (values == null) return [];
+  if (!Array.isArray(values)) throw new TypeError('retrieval decisionTrace must be an array');
+  const trace = [];
+  for (const raw of values.slice(0, REVIEW_LEARNING_BOUNDS.decisionTraceEntries)) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+      throw new TypeError('retrieval decision entries must be objects');
+    }
+    assertNoProhibitedReviewPayload(raw);
+    for (const key of Object.keys(raw)) {
+      if (!DECISION_KEYS.has(key)) throw new TypeError(`unsupported retrieval decision field: ${key}`);
+    }
+    const entry = {};
+    if (raw.id != null) {
+      entry.id = redactBoundedText(raw.id, REVIEW_LEARNING_BOUNDS.selectedIdBytes, 'decision memory id')
+        .replace(/\s+/g, '-');
+    }
+    if (typeof raw.selected === 'boolean') entry.selected = raw.selected;
+    if (Number.isInteger(Number(raw.rank)) && Number(raw.rank) >= 0) entry.rank = Number(raw.rank);
+    if (Number.isFinite(Number(raw.score))) entry.score = Number(raw.score);
+    const outcome = raw.outcome ?? raw.decision;
+    if (outcome != null) entry.outcome = _normalizeReason(outcome);
+    const reasons = raw.reasons ?? (raw.reason == null ? [] : [raw.reason]);
+    if (!Array.isArray(reasons)) throw new TypeError('retrieval decision reasons must be an array');
+    entry.reasons = [...new Set(reasons
+      .slice(0, REVIEW_LEARNING_BOUNDS.decisionReasons)
+      .map(_normalizeReason)
+      .filter(Boolean))];
+    trace.push(entry);
+  }
+  while (_byteLength(JSON.stringify(trace)) > REVIEW_LEARNING_BOUNDS.decisionTraceBytes) trace.pop();
+  return trace;
+}
+
+function normalizeRetrievalKind(value) {
+  const kind = String(value || 'general').trim().toLowerCase();
+  return _boundedIdentifier(kind, 64, 'retrieval kind', /^[a-z][a-z0-9-]*$/);
+}
+
+// ── Diagnostics filter normalizers (P-1ed2fb5f) ────────────────────────────
+// Each rejects malformed input with an actionable TypeError so the dashboard
+// API can surface a 400 rather than silently ignoring an invalid filter.
+function normalizeAudienceFilter(value) {
+  const audience = String(value || '').trim().toLowerCase();
+  if (!AUDIENCES.has(audience)) {
+    throw new TypeError(
+      `invalid review-learning audience: ${value} (expected ${[...AUDIENCES].join(' or ')})`,
+    );
+  }
+  return audience;
+}
+
+function normalizeSourceTypeFilter(value) {
+  const sourceType = String(value || '').trim().toLowerCase();
+  return _boundedIdentifier(sourceType, 64, 'memory source type', /^[a-z][a-z0-9-]*$/);
+}
+
+function normalizeAgentFilter(value) {
+  const agent = String(value || '').trim().toLowerCase();
+  return _boundedIdentifier(agent, 96, 'agent filter', /^[a-z0-9][a-z0-9._-]*$/);
+}
+
+function normalizeEventTypeFilter(value) {
+  return normalizeLifecycleEventType(value);
+}
+
+function normalizeLifecycleEventType(value) {
+  const eventType = String(value || '').trim().toLowerCase();
+  if (!EVENT_TYPES.has(eventType)) throw new TypeError(`invalid review-learning event type: ${value}`);
+  return eventType;
+}
+
+function buildLifecycleEventKey(event = {}) {
+  const identity = [
+    event.eventType,
+    event.memoryId,
+    event.findingKey,
+    event.project,
+    event.agent,
+    event.area,
+    event.disposition,
+    event.workItemId,
+    event.dispatchId,
+    event.identity,
+  ].map(value => String(value == null ? '' : value).trim().toLowerCase());
+  const eventKey = `rl-event-${crypto.createHash('sha256').update(JSON.stringify(identity)).digest('hex').slice(0, 40)}`;
+  if (_byteLength(eventKey) > REVIEW_LEARNING_BOUNDS.eventKeyBytes) {
+    throw new TypeError(`event key exceeds ${REVIEW_LEARNING_BOUNDS.eventKeyBytes} bytes`);
+  }
+  return eventKey;
+}
+
+function normalizeLifecycleEvent(input = {}) {
+  assertNoProhibitedReviewPayload(input);
+  const eventType = normalizeLifecycleEventType(input.eventType);
+  const project = normalizeProjectKey(input.project);
+  const memoryId = _optionalIdentifier(input.memoryId, REVIEW_LEARNING_BOUNDS.refBytes, 'event memory id');
+  let findingKey = null;
+  if (input.findingKey != null && String(input.findingKey).trim() !== '') {
+    const rawFindingKey = String(input.findingKey).trim();
+    findingKey = rawFindingKey.includes('|')
+      ? normalizeFindingKey(rawFindingKey)
+      : _boundedIdentifier(
+        rawFindingKey,
+        REVIEW_LEARNING_BOUNDS.findingKeyBytes,
+        'event finding key',
+      );
+    const findingProject = findingKey.includes('|') ? findingKey.split('|', 1)[0] : project;
+    if (findingProject !== project) {
+      throw new TypeError(`finding key project ${findingProject} does not match event scope ${project}`);
+    }
+  }
+  if (!memoryId && !findingKey) throw new TypeError('lifecycle event requires memoryId or findingKey');
+  const disposition = input.disposition == null || String(input.disposition).trim() === ''
+    ? null
+    : normalizeDisposition(input.disposition);
+  const normalized = {
+    eventType,
+    memoryId,
+    findingKey,
+    project,
+    agent: _optionalIdentifier(input.agent, 96, 'event agent'),
+    area: normalizeReviewArea(input.area || 'general'),
+    disposition,
+    workItemId: _optionalIdentifier(input.workItemId, REVIEW_LEARNING_BOUNDS.refBytes, 'event work item id'),
+    dispatchId: _optionalIdentifier(input.dispatchId, REVIEW_LEARNING_BOUNDS.refBytes, 'event dispatch id'),
+    identity: _optionalIdentifier(input.identity, REVIEW_LEARNING_BOUNDS.refBytes, 'event identity'),
+    metadata: normalizeReviewMetadata(input.metadata || {}),
+    createdAt: Number.isFinite(Number(input.createdAt)) ? Number(input.createdAt) : Date.now(),
+  };
+  normalized.eventKey = buildLifecycleEventKey(normalized);
+  return normalized;
+}
+
+function upsertReviewLearningCandidate(input) {
+  return require('./memory-store').upsertReviewLearningCandidate(input);
+}
+
+function upsertReviewLearningLesson(input) {
+  return require('./memory-store').upsertReviewLearningLesson(input);
+}
+
+function transitionReviewLearningCandidate(findingKey, disposition, options) {
+  return require('./memory-store').transitionReviewLearningCandidate(findingKey, disposition, options);
+}
+
+module.exports = {
+  REVIEW_LEARNING_SOURCE_TYPE,
+  REVIEW_LEARNING_DISPOSITIONS,
+  REVIEW_LEARNING_EVENT_TYPES,
+  REVIEW_LEARNING_APPLICATION_OUTCOMES,
+  REVIEW_LEARNING_HUMAN_ACTION_EVENTS,
+  REVIEW_LEARNING_BOUNDS,
+  POSITIVE_DISPOSITIONS,
+  CANDIDATE_TRANSITIONS,
+  normalizeDisposition,
+  normalizeProjectKey,
+  normalizeCanonicalPrId,
+  normalizeFindingSourceKey,
+  hashReviewCommentContent,
+  buildReviewCommentSource,
+  normalizeReviewCommentSources,
+  selectReviewCommentSourceSnapshot,
+  migrateLegacyReviewCommentEdits,
+  buildFindingKey,
+  normalizeFindingKey,
+  normalizeReviewArea,
+  normalizeReviewFacets,
+  redactBoundedText,
+  assertNoProhibitedReviewPayload,
+  normalizeReviewMetadata,
+  classifyExactEvidence,
+  normalizeCompletionReviewLearnings,
+  normalizeCompletionReviewLearningApplications,
+  buildCandidateMemoryRecord,
+  buildLessonMemoryRecord,
+  findDeterministicRepeatedLessonMatch,
+  candidateTransitionFor,
+  normalizeSelectedIds,
+  normalizeDecisionTrace,
+  normalizeRetrievalKind,
+  normalizeAudienceFilter,
+  normalizeSourceTypeFilter,
+  normalizeAgentFilter,
+  normalizeEventTypeFilter,
+  normalizeLifecycleEventType,
+  buildLifecycleEventKey,
+  normalizeLifecycleEvent,
+  upsertReviewLearningCandidate,
+  upsertReviewLearningLesson,
+  transitionReviewLearningCandidate,
+};