@evo-dev/core 0.0.1-alpha

package/src/learning/index.ts

@@ -0,0 +1,714 @@
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export type LearningCandidateStatus = "candidate" | "rejected" | "deferred";
+export type LearningCandidateKind =
+  | "lesson"
+  | "anti-criteria"
+  | "workflow-improvement"
+  | "skill-improvement";
+export type LearningCandidateScopeLevel = "user" | "project" | "workflow" | "skill" | "asset";
+export type LearningCandidateConfidence = "low" | "medium" | "high";
+export type LearningReviewDecision = "rejected" | "deferred";
+
+export interface LearningCandidate {
+  version: 1;
+  id: string;
+  kind: LearningCandidateKind;
+  status: LearningCandidateStatus;
+  routingInfluence: false;
+  scope: {
+    level: LearningCandidateScopeLevel;
+    projectId: string | null;
+    workflowId: string | null;
+    skillId: string | null;
+    assetId?: string | null;
+  };
+  content: {
+    summary: string;
+    howToApply: string;
+    antiCriteriaImpact: string[];
+  };
+  provenance: {
+    taskId: string | null;
+    taskContractRef: string | null;
+    workflowRunId: string | null;
+    evidenceRefs: string[];
+    sourceType:
+      | "task-close"
+      | "verification-failure"
+      | "review-finding"
+      | "user-feedback"
+      | "manual-candidate";
+    createdAt: string;
+    createdBy: "evodev" | "user";
+    rawPromptStored: false;
+    sourceContentStored: false;
+    rawCommandOutputStored: false;
+  };
+  privacy: {
+    classification: "local-private";
+    containsSource: false;
+    containsSecrets: false;
+    containsInternalLinks: false;
+    containsPersonalData: false;
+  };
+  review: {
+    decision: "pending" | "rejected" | "deferred";
+    reviewedAt: string | null;
+    reviewedBy: string | null;
+    reason?: string;
+  };
+  retention: {
+    staleAfter: string | null;
+    deleteAllowed: true;
+    exportAllowed: true;
+  };
+  confidence: LearningCandidateConfidence;
+}
+
+export interface LearningReviewDecisionRecord {
+  version: 1;
+  candidateId: string;
+  decision: LearningReviewDecision;
+  decidedAt: string;
+  decidedBy: "user";
+  reason: string | null;
+  writesAcceptedMemory: false;
+  affectsRouting: false;
+  candidateStatus: "rejected" | "deferred";
+}
+
+export interface LearningLintFinding {
+  candidateId: string;
+  severity: "error" | "warning";
+  field: string;
+  message: string;
+}
+
+export interface LearningLintResult {
+  ok: boolean;
+  candidatesChecked: number;
+  decisionsChecked: number;
+  findings: LearningLintFinding[];
+}
+
+export interface LearningReviewEntry {
+  candidate: LearningCandidate;
+  decision: "pending" | "deferred" | "rejected";
+  decisionRecord: LearningReviewDecisionRecord | null;
+  stale: boolean;
+}
+
+export interface LearningReviewOptions {
+  includeRejected?: boolean;
+  now?: string;
+}
+
+export interface LearningLintOptions {
+  decisions?: LearningReviewDecisionRecord[];
+  now?: string;
+}
+
+const LEARNING_CANDIDATE_KINDS = [
+  "lesson",
+  "anti-criteria",
+  "workflow-improvement",
+  "skill-improvement",
+] as const;
+const LEARNING_CANDIDATE_STATUSES = ["candidate", "rejected", "deferred"] as const;
+const LEARNING_SCOPE_LEVELS = ["user", "project", "workflow", "skill", "asset"] as const;
+const LEARNING_SOURCE_TYPES = [
+  "task-close",
+  "verification-failure",
+  "review-finding",
+  "user-feedback",
+  "manual-candidate",
+] as const;
+const LEARNING_CREATED_BY_VALUES = ["evodev", "user"] as const;
+const LEARNING_REVIEW_DECISIONS = ["pending", "rejected", "deferred"] as const;
+const LEARNING_CONFIDENCE_VALUES = ["low", "medium", "high"] as const;
+const LEARNING_DECISION_VALUES = ["rejected", "deferred"] as const;
+const LEARNING_DECIDED_BY_VALUES = ["user"] as const;
+const LEARNING_CANDIDATE_DECISION_STATUSES = ["rejected", "deferred"] as const;
+
+const FORBIDDEN_RAW_KEYS = new Set([
+  "commandhistory",
+  "commandoutput",
+  "credential",
+  "credentials",
+  "env",
+  "internalurl",
+  "memorybody",
+  "memorybodies",
+  "password",
+  "privatekey",
+  "prompt",
+  "promptbody",
+  "prompttext",
+  "rawcommand",
+  "rawcommandoutput",
+  "rawlog",
+  "rawlogs",
+  "rawoutput",
+  "rawpayload",
+  "rawprompt",
+  "secret",
+  "secretvalue",
+  "source",
+  "sourcebody",
+  "sourcecode",
+  "sourcecontent",
+  "sourcetext",
+  "stderr",
+  "stdout",
+  "token",
+  "transcript",
+  "transcriptbody",
+  "transcripttext",
+]);
+const SENSITIVE_TEXT_PATTERN =
+  /https?:\/\/\S+|\b(secret|token|password|passwd|private|internal|api[_-]?key|apikey|credential|credentials|raw log|raw logs|raw output|raw source|raw prompt|shell history|command history)\b/i;
+const PROTECTED_PATH_PATTERN =
+  /(^|[~/\\])(?:USER|KNOWLEDGE|LEARNING|OBSERVABILITY|PACKS|RELEASES|logs?|memory|\.env[^/\\]*)(?:$|[/\\])|PROJECTS[/\\][^/\\]+[/\\]LEARNING(?:$|[/\\])|\.evodev[/\\](?:USER|KNOWLEDGE|LEARNING|OBSERVABILITY|PACKS|RELEASES)(?:$|[/\\])/i;
+
+export function createLearningCandidate(input: {
+  id: string;
+  kind: LearningCandidateKind;
+  scope: LearningCandidate["scope"];
+  content: LearningCandidate["content"];
+  provenance: Omit<
+    LearningCandidate["provenance"],
+    "rawPromptStored" | "sourceContentStored" | "rawCommandOutputStored"
+  >;
+  retention?: Partial<LearningCandidate["retention"]>;
+  confidence?: LearningCandidateConfidence;
+}): LearningCandidate {
+  const candidate: LearningCandidate = {
+    version: 1,
+    id: sanitizeId(input.id),
+    kind: input.kind,
+    status: "candidate",
+    routingInfluence: false,
+    scope: sanitizeScope(input.scope),
+    content: {
+      summary: sanitizeText(input.content.summary),
+      howToApply: sanitizeText(input.content.howToApply),
+      antiCriteriaImpact: input.content.antiCriteriaImpact.map(sanitizeText),
+    },
+    provenance: {
+      taskId: sanitizeNullableId(input.provenance.taskId),
+      taskContractRef: sanitizeNullableText(input.provenance.taskContractRef),
+      workflowRunId: sanitizeNullableId(input.provenance.workflowRunId),
+      evidenceRefs: input.provenance.evidenceRefs.map(sanitizeText),
+      sourceType: input.provenance.sourceType,
+      createdAt: sanitizeText(input.provenance.createdAt),
+      createdBy: input.provenance.createdBy,
+      rawPromptStored: false,
+      sourceContentStored: false,
+      rawCommandOutputStored: false,
+    },
+    privacy: createSafePrivacy(),
+    review: { decision: "pending", reviewedAt: null, reviewedBy: null },
+    retention: {
+      staleAfter:
+        input.retention?.staleAfter === undefined
+          ? null
+          : sanitizeNullableText(input.retention.staleAfter),
+      deleteAllowed: true,
+      exportAllowed: true,
+    },
+    confidence: input.confidence ?? "medium",
+  };
+  validateLearningCandidate(candidate);
+  return candidate;
+}
+
+export function validateLearningCandidate(candidate: LearningCandidate): void {
+  if (!isRecord(candidate)) throw new Error("Learning candidate must be an object.");
+  if (candidate.version !== 1) throw new Error("Learning candidate version must be 1.");
+  assertEnumValue("kind", candidate.kind, LEARNING_CANDIDATE_KINDS);
+  assertEnumValue("status", candidate.status, LEARNING_CANDIDATE_STATUSES);
+  if (candidate.status !== "candidate") {
+    throw new Error("Learning review queue accepts candidate status only.");
+  }
+  if (candidate.routingInfluence !== false) {
+    throw new Error("Learning candidate routingInfluence must be false in I5.");
+  }
+  if (!isRecord(candidate.scope)) throw new Error("Learning candidate scope must be an object.");
+  assertEnumValue("scope.level", candidate.scope.level, LEARNING_SCOPE_LEVELS);
+  if (!isRecord(candidate.content)) {
+    throw new Error("Learning candidate content must be an object.");
+  }
+  assertStringField("content.summary", candidate.content.summary);
+  assertStringField("content.howToApply", candidate.content.howToApply);
+  assertStringArrayField("content.antiCriteriaImpact", candidate.content.antiCriteriaImpact);
+  if (!isRecord(candidate.provenance)) {
+    throw new Error("Learning candidate provenance must be an object.");
+  }
+  assertEnumValue("provenance.sourceType", candidate.provenance.sourceType, LEARNING_SOURCE_TYPES);
+  assertEnumValue(
+    "provenance.createdBy",
+    candidate.provenance.createdBy,
+    LEARNING_CREATED_BY_VALUES,
+  );
+  assertStringField("provenance.createdAt", candidate.provenance.createdAt);
+  assertStringArrayField("provenance.evidenceRefs", candidate.provenance.evidenceRefs);
+  if (!isRecord(candidate.privacy)) {
+    throw new Error("Learning candidate privacy must be an object.");
+  }
+  assertEnumValue("privacy.classification", candidate.privacy.classification, ["local-private"]);
+  if (!isRecord(candidate.review)) throw new Error("Learning candidate review must be an object.");
+  assertEnumValue("review.decision", candidate.review.decision, LEARNING_REVIEW_DECISIONS);
+  if (candidate.review.decision !== "pending") {
+    throw new Error("Learning candidate review decision must be pending.");
+  }
+  if (!isRecord(candidate.retention)) {
+    throw new Error("Learning candidate retention must be an object.");
+  }
+  assertEnumValue("confidence", candidate.confidence, LEARNING_CONFIDENCE_VALUES);
+  if (
+    candidate.provenance.rawPromptStored !== false ||
+    candidate.provenance.sourceContentStored !== false ||
+    candidate.provenance.rawCommandOutputStored !== false
+  ) {
+    throw new Error("Learning candidate cannot store raw prompt/source/command output.");
+  }
+  if (
+    candidate.privacy.containsSource !== false ||
+    candidate.privacy.containsSecrets !== false ||
+    candidate.privacy.containsInternalLinks !== false ||
+    candidate.privacy.containsPersonalData !== false
+  ) {
+    throw new Error(
+      "Learning candidate privacy fields must be local-private and raw-content-free.",
+    );
+  }
+  if (candidate.retention.deleteAllowed !== true || candidate.retention.exportAllowed !== true) {
+    throw new Error("Learning candidate retention must allow delete and export.");
+  }
+  assertNoForbiddenContent(candidate);
+}
+
+export function validateLearningReviewDecisionRecord(record: LearningReviewDecisionRecord): void {
+  if (!isRecord(record)) throw new Error("Learning review decision must be an object.");
+  if (record.version !== 1) throw new Error("Learning review decision version must be 1.");
+  assertStringField("candidateId", record.candidateId);
+  assertEnumValue("decision", record.decision, LEARNING_DECISION_VALUES);
+  assertStringField("decidedAt", record.decidedAt);
+  assertEnumValue("decidedBy", record.decidedBy, LEARNING_DECIDED_BY_VALUES);
+  if (record.reason !== null) assertStringField("reason", record.reason);
+  if (record.writesAcceptedMemory !== false) {
+    throw new Error("Learning review decision writesAcceptedMemory must be false in I5.");
+  }
+  if (record.affectsRouting !== false) {
+    throw new Error("Learning review decision affectsRouting must be false in I5.");
+  }
+  assertEnumValue("candidateStatus", record.candidateStatus, LEARNING_CANDIDATE_DECISION_STATUSES);
+  if (record.candidateStatus !== record.decision) {
+    throw new Error("Learning review decision candidateStatus must match decision.");
+  }
+  assertNoForbiddenContent(record);
+}
+
+export function parseLearningCandidate(value: unknown): LearningCandidate {
+  if (!isRecord(value)) throw new Error("Invalid learning candidate JSON.");
+  validateLearningCandidate(value as unknown as LearningCandidate);
+  return value as unknown as LearningCandidate;
+}
+
+export function parseLearningReviewDecisionRecord(value: unknown): LearningReviewDecisionRecord {
+  if (!isRecord(value)) throw new Error("Invalid learning review decision JSON.");
+  validateLearningReviewDecisionRecord(value as unknown as LearningReviewDecisionRecord);
+  return value as unknown as LearningReviewDecisionRecord;
+}
+
+export async function readLearningCandidates(path: string): Promise<LearningCandidate[]> {
+  return parseJsonOrJsonlFile(path, parseLearningCandidate);
+}
+
+export async function readLearningReviewDecisions(
+  path: string,
+): Promise<LearningReviewDecisionRecord[]> {
+  return parseJsonOrJsonlFile(path, parseLearningReviewDecisionRecord);
+}
+
+export function resolveLearningCandidateQueuePath(homeDir: string): string {
+  return join(homeDir, ".evodev", "STATE", "learning", "candidates.jsonl");
+}
+
+export function resolveLearningDecisionPath(homeDir: string): string {
+  return join(homeDir, ".evodev", "STATE", "learning", "review-decisions.jsonl");
+}
+
+export async function appendLearningCandidate(
+  homeDir: string,
+  candidate: LearningCandidate,
+): Promise<string> {
+  validateLearningCandidate(candidate);
+  const path = resolveLearningCandidateQueuePath(homeDir);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(candidate)}\n`, { encoding: "utf8", flag: "a" });
+  return path;
+}
+
+export async function listLearningCandidates(homeDir: string): Promise<LearningCandidate[]> {
+  const path = resolveLearningCandidateQueuePath(homeDir);
+  if (!(await pathExists(path))) return [];
+  return readLearningCandidates(path);
+}
+
+export async function listLearningReviewDecisions(
+  homeDir: string,
+): Promise<LearningReviewDecisionRecord[]> {
+  const path = resolveLearningDecisionPath(homeDir);
+  if (!(await pathExists(path))) return [];
+  return readLearningReviewDecisions(path);
+}
+
+export function lintLearningCandidates(
+  candidates: LearningCandidate[],
+  options: LearningLintOptions = {},
+): LearningLintResult {
+  const findings: LearningLintFinding[] = [];
+
+  for (const candidate of candidates) {
+    try {
+      validateLearningCandidate(candidate);
+    } catch (error) {
+      findings.push({
+        candidateId: typeof candidate.id === "string" ? candidate.id : "unknown",
+        severity: "error",
+        field: "candidate",
+        message: error instanceof Error ? error.message : String(error),
+      });
+      continue;
+    }
+
+    for (const [field, value] of requiredFields(candidate)) {
+      if (value === undefined || value === null || value === "") {
+        findings.push({
+          candidateId: candidate.id,
+          severity: "error",
+          field,
+          message: "Required learning candidate field is missing.",
+        });
+      }
+    }
+
+    if (candidate.provenance.evidenceRefs.length === 0) {
+      findings.push({
+        candidateId: candidate.id,
+        severity: "error",
+        field: "provenance.evidenceRefs",
+        message: "Learning candidate must include at least one evidence ref.",
+      });
+    }
+
+    if (isCandidateStale(candidate, options.now)) {
+      findings.push({
+        candidateId: candidate.id,
+        severity: "error",
+        field: "retention.staleAfter",
+        message: "Learning candidate is stale and requires review before use.",
+      });
+    }
+
+    for (const [field, path] of candidatePathFields(candidate)) {
+      if (PROTECTED_PATH_PATTERN.test(path)) {
+        findings.push({
+          candidateId: candidate.id,
+          severity: "error",
+          field,
+          message: "Learning candidate references a protected/private path zone.",
+        });
+      }
+    }
+  }
+
+  for (const decision of options.decisions ?? []) {
+    try {
+      validateLearningReviewDecisionRecord(decision);
+    } catch (error) {
+      findings.push({
+        candidateId:
+          isRecord(decision) && typeof decision.candidateId === "string"
+            ? decision.candidateId
+            : "unknown",
+        severity: "error",
+        field: "decision",
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return {
+    ok: findings.every((finding) => finding.severity !== "error"),
+    candidatesChecked: candidates.length,
+    decisionsChecked: options.decisions?.length ?? 0,
+    findings,
+  };
+}
+
+export function buildLearningReviewEntries(
+  candidates: LearningCandidate[],
+  decisions: LearningReviewDecisionRecord[] = [],
+  options: LearningReviewOptions = {},
+): LearningReviewEntry[] {
+  const latestDecision = new Map<string, LearningReviewDecisionRecord>();
+  for (const decision of decisions) {
+    validateLearningReviewDecisionRecord(decision);
+    latestDecision.set(decision.candidateId, decision);
+  }
+
+  return candidates
+    .map((candidate) => {
+      validateLearningCandidate(candidate);
+      const decisionRecord = latestDecision.get(candidate.id) ?? null;
+      const decision: LearningReviewEntry["decision"] = decisionRecord?.decision ?? "pending";
+      return {
+        candidate,
+        decision,
+        decisionRecord,
+        stale: isCandidateStale(candidate, options.now),
+      };
+    })
+    .filter((entry) => options.includeRejected === true || entry.decision !== "rejected");
+}
+
+export function formatLearningReview(
+  candidates: LearningCandidate[],
+  decisions: LearningReviewDecisionRecord[] = [],
+  options: LearningReviewOptions = {},
+): string {
+  const entries = buildLearningReviewEntries(candidates, decisions, options);
+  return [
+    "EvoDev learning review queue",
+    "",
+    "Preview only: candidates are not accepted memory; accepted memory write is not implemented in I5.",
+    "Pending/deferred candidates do not affect routing; routingInfluence must remain false.",
+    `Candidates shown: ${entries.length}`,
+    ...entries.flatMap((entry) => [
+      "",
+      `- ${entry.candidate.id} (${entry.candidate.kind}, ${entry.candidate.scope.level}, ${entry.candidate.confidence})`,
+      `  Candidate status: ${entry.candidate.status}; decision state: ${entry.decision}`,
+      `  routingInfluence: ${entry.candidate.routingInfluence}; future influence: none in I5`,
+      `  Stale: ${entry.stale ? "yes" : "no"}; staleAfter: ${entry.candidate.retention.staleAfter ?? "none"}`,
+      `  Retention: deleteAllowed=${entry.candidate.retention.deleteAllowed}; exportAllowed=${entry.candidate.retention.exportAllowed}`,
+      `  Summary: ${entry.candidate.content.summary}`,
+      `  How to apply: ${entry.candidate.content.howToApply}`,
+      `  Provenance: task=${entry.candidate.provenance.taskId ?? "none"}, workflow=${entry.candidate.provenance.workflowRunId ?? "none"}, evidence=${entry.candidate.provenance.evidenceRefs.length}`,
+      "  Privacy: local-private; rawPrompt=false; sourceContent=false; rawCommandOutput=false; secrets=false; internalLinks=false",
+    ]),
+  ].join("\n");
+}
+
+export function formatLearningLint(result: LearningLintResult): string {
+  return [
+    "EvoDev learning lint",
+    "",
+    `Status: ${result.ok ? "PASS" : "FAIL"}`,
+    `Candidates checked: ${result.candidatesChecked}`,
+    `Decisions checked: ${result.decisionsChecked}`,
+    `Findings: ${result.findings.length}`,
+    ...result.findings.map(
+      (finding) =>
+        `- ${finding.severity.toUpperCase()} ${finding.candidateId} ${finding.field}: ${finding.message}`,
+    ),
+  ].join("\n");
+}
+
+export function createLearningReviewDecisionRecord(input: {
+  candidateId: string;
+  decision: LearningReviewDecision;
+  decidedAt?: string;
+  reason?: string | null;
+}): LearningReviewDecisionRecord {
+  assertEnumValue("decision", input.decision, LEARNING_DECISION_VALUES);
+  const candidateStatus = input.decision === "rejected" ? "rejected" : "deferred";
+  const record: LearningReviewDecisionRecord = {
+    version: 1,
+    candidateId: sanitizeId(input.candidateId),
+    decision: input.decision,
+    decidedAt: sanitizeText(input.decidedAt ?? new Date().toISOString()),
+    decidedBy: "user",
+    reason: input.reason === undefined ? null : sanitizeNullableText(input.reason),
+    writesAcceptedMemory: false,
+    affectsRouting: false,
+    candidateStatus,
+  };
+  validateLearningReviewDecisionRecord(record);
+  return record;
+}
+
+export async function appendLearningReviewDecision(
+  homeDir: string,
+  record: LearningReviewDecisionRecord,
+): Promise<string> {
+  validateLearningReviewDecisionRecord(record);
+  const path = resolveLearningDecisionPath(homeDir);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(record)}\n`, { encoding: "utf8", flag: "a" });
+  return path;
+}
+
+export async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error as NodeJS.ErrnoException).code === "ENOENT"
+    ) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function createSafePrivacy(): LearningCandidate["privacy"] {
+  return {
+    classification: "local-private",
+    containsSource: false,
+    containsSecrets: false,
+    containsInternalLinks: false,
+    containsPersonalData: false,
+  };
+}
+
+function sanitizeScope(scope: LearningCandidate["scope"]): LearningCandidate["scope"] {
+  return {
+    level: scope.level,
+    projectId: sanitizeNullableId(scope.projectId),
+    workflowId: sanitizeNullableId(scope.workflowId),
+    skillId: sanitizeNullableId(scope.skillId),
+    assetId: scope.assetId === undefined ? undefined : sanitizeNullableId(scope.assetId),
+  };
+}
+
+function requiredFields(candidate: LearningCandidate): Array<[string, unknown]> {
+  return [
+    ["id", candidate.id],
+    ["kind", candidate.kind],
+    ["status", candidate.status],
+    ["routingInfluence", candidate.routingInfluence],
+    ["scope.level", candidate.scope.level],
+    ["content.summary", candidate.content.summary],
+    ["content.howToApply", candidate.content.howToApply],
+    ["provenance.sourceType", candidate.provenance.sourceType],
+    ["provenance.createdAt", candidate.provenance.createdAt],
+    ["provenance.createdBy", candidate.provenance.createdBy],
+    ["privacy.classification", candidate.privacy.classification],
+    ["review.decision", candidate.review.decision],
+    ["retention.deleteAllowed", candidate.retention.deleteAllowed],
+    ["retention.exportAllowed", candidate.retention.exportAllowed],
+    ["confidence", candidate.confidence],
+  ];
+}
+
+async function parseJsonOrJsonlFile<T>(
+  path: string,
+  parseItem: (value: unknown) => T,
+): Promise<T[]> {
+  const raw = await readFile(path, "utf8");
+  if (raw.trim() === "") return [];
+
+  if (path.endsWith(".jsonl")) {
+    const lines = raw.split("\n").filter((line) => line.trim() !== "");
+    return lines.map((line) => parseItem(JSON.parse(line) as unknown));
+  }
+
+  const parsed = JSON.parse(raw) as unknown;
+  const values = Array.isArray(parsed) ? parsed : [parsed];
+  return values.map(parseItem);
+}
+
+function candidatePathFields(candidate: LearningCandidate): Array<[string, string]> {
+  return [
+    ["provenance.taskContractRef", candidate.provenance.taskContractRef],
+    ...candidate.provenance.evidenceRefs.map((ref, index): [string, string] => [
+      `provenance.evidenceRefs[${index}]`,
+      ref,
+    ]),
+  ].filter((entry): entry is [string, string] => typeof entry[1] === "string");
+}
+
+function isCandidateStale(candidate: LearningCandidate, now: string | undefined): boolean {
+  if (candidate.retention.staleAfter === null) return false;
+  const staleAfter = Date.parse(candidate.retention.staleAfter);
+  const current = Date.parse(now ?? new Date().toISOString());
+  return Number.isFinite(staleAfter) && Number.isFinite(current) && staleAfter < current;
+}
+
+function assertEnumValue(field: string, value: unknown, allowed: readonly string[]): void {
+  if (typeof value !== "string" || !allowed.includes(value)) {
+    throw new Error(`${field} must be one of: ${allowed.join(", ")}.`);
+  }
+}
+
+function assertStringField(field: string, value: unknown): void {
+  if (typeof value !== "string") {
+    throw new Error(`${field} must be a string.`);
+  }
+}
+
+function assertStringArrayField(field: string, value: unknown): void {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new Error(`${field} must be an array of strings.`);
+  }
+}
+
+function assertNoForbiddenContent(value: unknown): void {
+  if (typeof value === "string") {
+    if (value === "local-private") return;
+    if (SENSITIVE_TEXT_PATTERN.test(value)) {
+      throw new Error("Learning candidate contains sensitive content.");
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) assertNoForbiddenContent(item);
+    return;
+  }
+  if (!isRecord(value)) return;
+
+  for (const [key, child] of Object.entries(value)) {
+    const normalizedKey = normalizeKey(key);
+    if (FORBIDDEN_RAW_KEYS.has(normalizedKey)) {
+      throw new Error(`Learning candidate contains forbidden raw field: ${key}`);
+    }
+    assertNoForbiddenContent(child);
+  }
+}
+
+function sanitizeText(value: string): string {
+  return value.replace(SENSITIVE_TEXT_PATTERN, "[redacted]").slice(0, 500);
+}
+
+function sanitizeNullableText(value: string | null): string | null {
+  return value === null ? null : sanitizeText(value);
+}
+
+function sanitizeId(value: string): string {
+  const sanitized = sanitizeText(value)
+    .replace(/\[redacted\]/gi, "redacted")
+    .replace(/[^a-zA-Z0-9._-]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 100);
+  return sanitized || "learning-candidate";
+}
+
+function sanitizeNullableId(value: string | null): string | null {
+  return value === null ? null : sanitizeId(value);
+}
+
+function normalizeKey(key: string): string {
+  return key.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}