@evo-dev/core 0.0.1-alpha.1 → 0.0.1-alpha.10

package/src/evolution/shared.ts

@@ -0,0 +1,758 @@
+import { readdir } from "node:fs/promises";
+import { isAbsolute, relative, resolve } from "node:path";
+import { pathExists } from "../utils/index.ts";
+import {
+  detectSessionMemorySensitivity,
+  redactSessionMemoryCredentialText,
+} from "./evidence/session-memory/sensitivity.ts";
+import type {
+  EvolutionDistillationBatch,
+  EvolutionEpisodeKind,
+  EvolutionEpisodeStatus,
+  EvolutionEvidenceEventKind,
+  EvolutionEvidenceSourceKind,
+  EvolutionEvidenceWindow,
+  EvolutionEvosCase,
+  EvolutionKnowledgeKind,
+  EvolutionKnowledgeRecord,
+  EvolutionNormalizedEventType,
+  EvolutionPrivacyFields,
+  EvolutionProposalKind,
+  EvolutionRepoProposal,
+  EvolutionReviewCandidate,
+  EvolutionReviewState,
+  EvolutionTriggerReason,
+  EvolutionTriggerRecord,
+  EvolutionTriggerStatus,
+  EvolutionTriggerStrength,
+  SegmentEvolutionTriggerReason,
+  SegmentEvolutionTriggerRecord,
+  SegmentEvolutionTriggerStrength,
+} from "./schema.ts";
+
+export const MAX_EVIDENCE_EVENTS = 200;
+export const MAX_TEXT_LENGTH = 600;
+export const MAX_PROPOSED_CHANGE_LENGTH = 16 * 1024;
+export const PROCESS_LOCK_STALE_MS = 5 * 60 * 1000;
+export const EVIDENCE_SOURCE_KINDS: readonly EvolutionEvidenceSourceKind[] = [
+  "evodev-execution-event",
+  "team-agent-trace",
+  "session-trace",
+  "session-memory-segment",
+  "verification",
+  "review-summary",
+  "user-feedback",
+  "code-agent-trace-ref",
+];
+export const REVIEW_STATES: readonly EvolutionReviewState[] = [
+  "auto-accepted",
+  "auto-stored/unreviewed",
+  "needs-human",
+  "accepted",
+  "rejected",
+  "deferred",
+  "stale",
+  "deprecated",
+  "superseded",
+  "revoked",
+];
+export const KNOWLEDGE_KINDS: readonly EvolutionKnowledgeKind[] = [
+  "run-summary",
+  "lesson",
+  "rule",
+  "workflow-hint",
+  "skill-gap",
+  "role-note",
+  "verification-pattern",
+];
+export const PROPOSAL_KINDS: readonly EvolutionProposalKind[] = [
+  "skill",
+  "rule",
+  "role-agent",
+  "team",
+  "ci",
+  "test",
+  "docs",
+  "engineering-practice",
+];
+export const EVENT_KINDS: readonly EvolutionEvidenceEventKind[] = [
+  "trace",
+  "tool-call",
+  "skill-call",
+  "subagent",
+  "verification",
+  "review",
+  "user-feedback",
+  "error",
+  "run-state",
+];
+export const NORMALIZED_EVENT_TYPES: readonly EvolutionNormalizedEventType[] = [
+  "SessionStart",
+  "UserPromptSubmit",
+  "UserPromptExpansion",
+  "PreToolUse",
+  "PermissionRequest",
+  "PostToolUse",
+  "PostToolUseFailure",
+  "PostToolBatch",
+  "PermissionDenied",
+  "SubagentStart",
+  "Stop",
+  "StopFailure",
+  "TeammateIdle",
+  "SubagentStop",
+  "TaskCreated",
+  "TaskCompleted",
+  "PreCompact",
+  "PostCompact",
+  "SessionEnd",
+  "ConfigChange",
+  "CwdChanged",
+  "FileChanged",
+  "WorktreeCreate",
+  "WorktreeRemove",
+  "unknown",
+];
+export const TRIGGER_STRENGTHS: readonly EvolutionTriggerStrength[] = [
+  "none",
+  "conditional",
+  "strong",
+];
+export const TRIGGER_REASONS: readonly EvolutionTriggerReason[] = [
+  "none",
+  "turn-completed",
+  "task-completed",
+  "session-ended",
+  "role-completed",
+  "stop-failure",
+  "tool-failure",
+  "permission-denied",
+  "explicit-command",
+  "failure-signal",
+];
+export const EPISODE_KINDS: readonly EvolutionEpisodeKind[] = ["session", "turn", "task", "role"];
+export const EPISODE_STATUSES: readonly EvolutionEpisodeStatus[] = ["open", "closed", "failed"];
+export const TRIGGER_STATUSES: readonly EvolutionTriggerStatus[] = [
+  "pending",
+  "processing",
+  "consumed",
+  "failed",
+  "skipped",
+];
+export const SEGMENT_TRIGGER_REASONS: readonly SegmentEvolutionTriggerReason[] = [
+  "session-memory-init",
+  "session-memory-threshold",
+  "intent-refinement",
+  "user-interruption",
+  "failure-signal",
+  "permission-denied",
+  "verification-after-fix",
+  "explicit-memory-intent",
+];
+export const SEGMENT_TRIGGER_STRENGTHS: readonly SegmentEvolutionTriggerStrength[] = [
+  "normal",
+  "strong",
+];
+export const FORBIDDEN_RAW_KEYS = new Set([
+  "commandhistory",
+  "commandoutput",
+  "credential",
+  "credentials",
+  "env",
+  "fullsource",
+  "memorybody",
+  "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",
+]);
+export function validateEvolutionEvidenceWindow(window: EvolutionEvidenceWindow): void {
+  if (!isRecord(window)) throw new Error("Evidence window must be an object.");
+  if (window.schemaVersion !== 1) throw new Error("Evidence window schemaVersion must be 1.");
+  if (window.kind !== "evidence-window") throw new Error("Evidence window kind is invalid.");
+  assertString("projectKey", window.projectKey);
+  assertString("runId", window.runId);
+  assertString("id", window.id);
+  assertString("createdAt", window.createdAt);
+  assertPrivacy(window.privacy);
+  if (!Array.isArray(window.sourceRefs)) throw new Error("sourceRefs must be an array.");
+  for (const sourceRef of window.sourceRefs) {
+    assertString("sourceRefs.id", sourceRef.id);
+    assertEnum("sourceRefs.kind", sourceRef.kind, EVIDENCE_SOURCE_KINDS);
+    assertString("sourceRefs.path", sourceRef.path);
+    if (sourceRef.rawContentStored !== false)
+      throw new Error("sourceRefs.rawContentStored must be false.");
+    if (sourceRef.externalContentCopied !== false) {
+      throw new Error("sourceRefs.externalContentCopied must be false.");
+    }
+  }
+  if (!Array.isArray(window.events)) throw new Error("events must be an array.");
+  for (const event of window.events) {
+    assertString("events.id", event.id);
+    assertEnum("events.kind", event.kind, EVENT_KINDS);
+    assertEnum("events.eventType", event.eventType, NORMALIZED_EVENT_TYPES);
+    assertEnum("events.triggerStrength", event.triggerStrength, TRIGGER_STRENGTHS);
+    assertEnum("events.triggerReason", event.triggerReason, TRIGGER_REASONS);
+    assertString("events.summary", event.summary);
+    assertString("events.evidenceRef", event.evidenceRef);
+    if (!Array.isArray(event.episodeIds)) throw new Error("events.episodeIds must be an array.");
+    for (const episodeId of event.episodeIds) assertString("events.episodeIds", episodeId);
+    if (event.rawContentStored !== false) throw new Error("events.rawContentStored must be false.");
+  }
+  if (!Array.isArray(window.episodes)) throw new Error("episodes must be an array.");
+  for (const episode of window.episodes) {
+    assertString("episodes.id", episode.id);
+    assertEnum("episodes.kind", episode.kind, EPISODE_KINDS);
+    assertEnum("episodes.status", episode.status, EPISODE_STATUSES);
+    assertEnum("episodes.triggerStrength", episode.triggerStrength, TRIGGER_STRENGTHS);
+    assertEnum("episodes.triggerReason", episode.triggerReason, TRIGGER_REASONS);
+    assertString("episodes.summary", episode.summary);
+    if (!Array.isArray(episode.eventIds)) throw new Error("episodes.eventIds must be an array.");
+    for (const eventId of episode.eventIds) assertString("episodes.eventIds", eventId);
+    if (episode.rawContentStored !== false)
+      throw new Error("episodes.rawContentStored must be false.");
+  }
+  assertEnum("triggerPolicy.strongest", window.triggerPolicy.strongest, TRIGGER_STRENGTHS);
+  if (!Array.isArray(window.triggerPolicy.reasons))
+    throw new Error("triggerPolicy.reasons must be an array.");
+  for (const reason of window.triggerPolicy.reasons) {
+    assertEnum("triggerPolicy.reasons", reason, TRIGGER_REASONS);
+  }
+  assertNoForbiddenRawFields(window);
+}
+
+export function validateEvolutionKnowledgeRecord(record: EvolutionKnowledgeRecord): void {
+  if (!isRecord(record)) throw new Error("Knowledge record must be an object.");
+  if (record.schemaVersion !== 1) throw new Error("Knowledge record schemaVersion must be 1.");
+  assertEnum("kind", record.kind, KNOWLEDGE_KINDS);
+  assertEnum("reviewState", record.reviewState, REVIEW_STATES);
+  assertEnum("authority", record.authority, ["contextual", "reviewed"]);
+  if (record.reviewState === "accepted" && record.authority !== "reviewed") {
+    throw new Error("Accepted knowledge must use reviewed authority.");
+  }
+  if (
+    (record.reviewState === "auto-stored/unreviewed" ||
+      record.reviewState === "auto-accepted" ||
+      record.reviewState === "needs-human") &&
+    record.authority !== "contextual"
+  ) {
+    throw new Error("Unreviewed knowledge must remain contextual.");
+  }
+  if (record.runtime.hardBlocking !== false) {
+    throw new Error("Knowledge runtime.hardBlocking must be false.");
+  }
+  assertPrivacy(record.privacy);
+  assertProvenance(record.provenance);
+  assertNoForbiddenRawFields(record);
+}
+
+export function validateEvolutionDistillationBatch(batch: EvolutionDistillationBatch): void {
+  if (!isRecord(batch)) throw new Error("Distillation batch must be an object.");
+  if (batch.schemaVersion !== 1) throw new Error("Distillation batch schemaVersion must be 1.");
+  validateEvolutionEvidenceWindow(batch.evidenceWindow);
+  for (const record of batch.knowledgeRecords) validateEvolutionKnowledgeRecord(record);
+  for (const evosCase of batch.evosCases) validateEvolutionEvosCase(evosCase);
+  for (const proposal of batch.repoProposals) validateEvolutionRepoProposal(proposal);
+  assertNoForbiddenRawFields(batch);
+}
+
+export function createEvolutionKnowledgeRecord(
+  input: Omit<EvolutionKnowledgeRecord, "schemaVersion">,
+): EvolutionKnowledgeRecord {
+  const record: EvolutionKnowledgeRecord = {
+    ...input,
+    schemaVersion: 1,
+    id: sanitizeId(input.id),
+    title: sanitizeText(input.title),
+    projectKey: sanitizeId(input.projectKey),
+    summary: sanitizeText(input.summary),
+    body: sanitizeText(input.body),
+    roleTags: uniqueSanitizedIds(input.roleTags),
+    tags: uniqueSanitizedIds(input.tags),
+    privacy: { ...input.privacy },
+  };
+  record.privacy.internalLinksStored =
+    detectSessionMemorySensitivity(record).reasons.includes("url");
+  validateEvolutionKnowledgeRecord(record);
+  return record;
+}
+
+export function createEvolutionEvosCase(
+  input: Omit<EvolutionEvosCase, "schemaVersion" | "kind">,
+): EvolutionEvosCase {
+  const evosCase: EvolutionEvosCase = {
+    ...input,
+    schemaVersion: 1,
+    kind: "evos-case",
+    id: sanitizeId(input.id),
+    projectKey: sanitizeId(input.projectKey),
+    title: sanitizeText(input.title),
+    roleTags: uniqueSanitizedIds(input.roleTags),
+    tags: uniqueSanitizedIds(input.tags),
+    trigger: {
+      kind: input.trigger.kind,
+      summary: sanitizeText(input.trigger.summary),
+    },
+    intervention: {
+      summary: sanitizeText(input.intervention.summary),
+      roleIds: uniqueSanitizedIds(input.intervention.roleIds),
+    },
+    result: {
+      summary: sanitizeText(input.result.summary),
+      verificationSignals: input.result.verificationSignals.map(sanitizeText),
+    },
+    expectedFutureBehavior: sanitizeText(input.expectedFutureBehavior),
+    privacy: { ...input.privacy },
+  };
+  evosCase.privacy.internalLinksStored =
+    detectSessionMemorySensitivity(evosCase).reasons.includes("url");
+  validateEvolutionEvosCase(evosCase);
+  return evosCase;
+}
+
+export function createEvolutionRepoProposal(
+  input: Omit<EvolutionRepoProposal, "schemaVersion">,
+): EvolutionRepoProposal {
+  const proposal: EvolutionRepoProposal = {
+    ...input,
+    schemaVersion: 1,
+    id: sanitizeId(input.id),
+    projectKey: sanitizeId(input.projectKey),
+    title: sanitizeText(input.title),
+    summary: sanitizeText(input.summary),
+    rationale: sanitizeText(input.rationale),
+    roleTags: uniqueSanitizedIds(input.roleTags),
+    tags: uniqueSanitizedIds(input.tags),
+    plannedFiles: input.plannedFiles.map((file) => ({
+      relativePath: sanitizeRelativePath(file.relativePath),
+      action: file.action,
+      reason: sanitizeText(file.reason),
+      ...(file.proposedChange === undefined
+        ? {}
+        : { proposedChange: sanitizeProposedChange(file.proposedChange) }),
+    })),
+    privacy: { ...input.privacy },
+  };
+  proposal.privacy.internalLinksStored =
+    detectSessionMemorySensitivity(proposal).reasons.includes("url");
+  validateEvolutionRepoProposal(proposal);
+  return proposal;
+}
+
+export function validateEvolutionEvosCase(evosCase: EvolutionEvosCase): void {
+  if (!isRecord(evosCase)) throw new Error("Evos case must be an object.");
+  if (evosCase.schemaVersion !== 1) throw new Error("Evos case schemaVersion must be 1.");
+  if (evosCase.kind !== "evos-case") throw new Error("Evos case kind is invalid.");
+  assertEnum("reviewState", evosCase.reviewState, REVIEW_STATES);
+  assertPrivacy(evosCase.privacy);
+  assertProvenance(evosCase.provenance);
+  assertNoForbiddenRawFields(evosCase);
+}
+
+export function validateEvolutionRepoProposal(proposal: EvolutionRepoProposal): void {
+  if (!isRecord(proposal)) throw new Error("Repo proposal must be an object.");
+  if (proposal.schemaVersion !== 1) throw new Error("Repo proposal schemaVersion must be 1.");
+  assertEnum("kind", proposal.kind, PROPOSAL_KINDS);
+  assertEnum("reviewState", proposal.reviewState, [
+    "pending",
+    "accepted",
+    "rejected",
+    "deferred",
+    "applied",
+  ]);
+  if (
+    proposal.reviewStateChangedAt !== undefined &&
+    Number.isNaN(new Date(proposal.reviewStateChangedAt).getTime())
+  ) {
+    throw new Error("Repo proposal reviewStateChangedAt must be a valid timestamp.");
+  }
+  for (const file of proposal.plannedFiles) {
+    if (file.proposedChange !== undefined && file.proposedChange.trim() === "") {
+      throw new Error("Repo proposal proposedChange must not be empty.");
+    }
+  }
+  if (proposal.lastDecision !== undefined) {
+    assertEnum("lastDecision.state", proposal.lastDecision.state, [
+      "accepted",
+      "rejected",
+      "deferred",
+    ]);
+    if (
+      proposal.lastDecision.reason !== null &&
+      (proposal.lastDecision.reason.trim() === "" || proposal.lastDecision.reason.length > 500)
+    ) {
+      throw new Error("Repo proposal decision reason must be 1-500 characters.");
+    }
+    if (Number.isNaN(new Date(proposal.lastDecision.decidedAt).getTime())) {
+      throw new Error("Repo proposal decision timestamp must be valid.");
+    }
+  }
+  if (proposal.apply.autoApply !== false || proposal.apply.requiresExplicitCommand !== true) {
+    throw new Error("Repo proposal must require explicit apply.");
+  }
+  assertPrivacy(proposal.privacy);
+  assertProvenance(proposal.provenance);
+  assertNoForbiddenRawFields(proposal);
+}
+
+export function hasConcreteRepoProposalChanges(proposal: EvolutionRepoProposal): boolean {
+  return (
+    proposal.targetRepoPath !== null &&
+    proposal.targetRepoPath.trim() !== "" &&
+    proposal.plannedFiles.length > 0 &&
+    proposal.plannedFiles.every(
+      (file) => file.proposedChange !== undefined && file.proposedChange.trim() !== "",
+    )
+  );
+}
+
+export function validateEvolutionReviewCandidate(candidate: EvolutionReviewCandidate): void {
+  if (!isRecord(candidate)) throw new Error("Review candidate must be an object.");
+  if (candidate.schemaVersion !== 1) {
+    throw new Error("Review candidate schemaVersion must be 1.");
+  }
+  if (candidate.kind !== "evolution-review-candidate") {
+    throw new Error("Review candidate kind is invalid.");
+  }
+  assertString("reviewCandidate.id", candidate.id);
+  assertString("reviewCandidate.projectKey", candidate.projectKey);
+  assertString("reviewCandidate.runId", candidate.runId);
+  assertString("reviewCandidate.createdAt", candidate.createdAt);
+  assertString("reviewCandidate.candidateKind", candidate.candidateKind);
+  assertString("reviewCandidate.title", candidate.title);
+  assertString("reviewCandidate.targetStore", candidate.targetStore);
+  assertString("reviewCandidate.targetPath", candidate.targetPath);
+  assertString("reviewCandidate.stableKey", candidate.stableKey);
+  assertEnum("reviewCandidate.reviewState", candidate.reviewState, [
+    "needs-human",
+    "accepted",
+    "rejected",
+    "deferred",
+  ]);
+  if (
+    candidate.reviewStateChangedAt !== undefined &&
+    Number.isNaN(new Date(candidate.reviewStateChangedAt).getTime())
+  ) {
+    throw new Error("Review candidate reviewStateChangedAt must be a valid timestamp.");
+  }
+  if (!Array.isArray(candidate.reasons))
+    throw new Error("Review candidate reasons must be an array.");
+  for (const reason of candidate.reasons) assertString("reviewCandidate.reasons", reason);
+  if (!isRecord(candidate.provenance))
+    throw new Error("Review candidate provenance must be an object.");
+  assertString("reviewCandidate.provenance.runId", candidate.provenance.runId);
+  assertString(
+    "reviewCandidate.provenance.evidenceWindowId",
+    candidate.provenance.evidenceWindowId,
+  );
+  if (candidate.provenance.createdBy !== "evodev") {
+    throw new Error("Review candidate provenance.createdBy must be evodev.");
+  }
+  if (!Array.isArray(candidate.provenance.evidenceRefs)) {
+    throw new Error("Review candidate evidenceRefs must be an array.");
+  }
+  for (const evidenceRef of candidate.provenance.evidenceRefs) {
+    assertString("reviewCandidate.provenance.evidenceRefs", evidenceRef);
+  }
+  if (
+    candidate.provenance.rawLogsStored !== false ||
+    candidate.provenance.rawPromptsStored !== false ||
+    candidate.provenance.sourceDumpsStored !== false ||
+    candidate.provenance.rawCommandOutputStored !== false
+  ) {
+    throw new Error("Review candidate provenance must remain metadata-only.");
+  }
+  assertPrivacy(candidate.privacy);
+  assertNoForbiddenRawFields(candidate);
+}
+
+export function validateEvolutionTriggerRecord(trigger: EvolutionTriggerRecord): void {
+  if (!isRecord(trigger)) throw new Error("Evolution trigger must be an object.");
+  if (trigger.schemaVersion !== 1) throw new Error("Evolution trigger schemaVersion must be 1.");
+  if (trigger.kind !== "evolution-trigger") throw new Error("Evolution trigger kind is invalid.");
+  assertString("trigger.id", trigger.id);
+  assertString("trigger.projectKey", trigger.projectKey);
+  assertString("trigger.runId", trigger.runId);
+  assertEnum("trigger.eventType", trigger.eventType, NORMALIZED_EVENT_TYPES);
+  assertEnum("trigger.triggerStrength", trigger.triggerStrength, TRIGGER_STRENGTHS);
+  assertEnum("trigger.triggerReason", trigger.triggerReason, TRIGGER_REASONS);
+  assertEnum("trigger.status", trigger.status, TRIGGER_STATUSES);
+  assertString("trigger.summary", trigger.summary);
+  assertString("trigger.createdAt", trigger.createdAt);
+  assertString("trigger.updatedAt", trigger.updatedAt);
+  if (typeof trigger.attempts !== "number" || trigger.attempts < 0) {
+    throw new Error("trigger.attempts must be a non-negative number.");
+  }
+  if (trigger.rawContentStored !== false)
+    throw new Error("trigger.rawContentStored must be false.");
+  assertPrivacy(trigger.privacy);
+  assertNoForbiddenRawFields(trigger);
+}
+
+export function validateSegmentEvolutionTriggerRecord(
+  trigger: SegmentEvolutionTriggerRecord,
+): void {
+  if (!isRecord(trigger)) throw new Error("Segment evolution trigger must be an object.");
+  if (trigger.schemaVersion !== 1)
+    throw new Error("Segment evolution trigger schemaVersion must be 1.");
+  if (trigger.kind !== "segment-evolution-trigger") {
+    throw new Error("Segment evolution trigger kind is invalid.");
+  }
+  assertString("segmentTrigger.id", trigger.id);
+  assertString("segmentTrigger.projectKey", trigger.projectKey);
+  assertString("segmentTrigger.sessionKey", trigger.sessionKey);
+  assertString("segmentTrigger.segmentId", trigger.segmentId);
+  assertString("segmentTrigger.segmentPath", trigger.segmentPath);
+  assertEnum("segmentTrigger.strength", trigger.strength, SEGMENT_TRIGGER_STRENGTHS);
+  assertEnum("segmentTrigger.reason", trigger.reason, SEGMENT_TRIGGER_REASONS);
+  assertEnum("segmentTrigger.status", trigger.status, TRIGGER_STATUSES);
+  assertString("segmentTrigger.summary", trigger.summary);
+  assertString("segmentTrigger.createdAt", trigger.createdAt);
+  assertString("segmentTrigger.updatedAt", trigger.updatedAt);
+  if (trigger.runId !== null) assertString("segmentTrigger.runId", trigger.runId);
+  if (trigger.roleId !== null) assertString("segmentTrigger.roleId", trigger.roleId);
+  if (typeof trigger.attempts !== "number" || trigger.attempts < 0) {
+    throw new Error("segmentTrigger.attempts must be a non-negative number.");
+  }
+  if (trigger.rawContentStored !== false) {
+    throw new Error("segmentTrigger.rawContentStored must be false.");
+  }
+}
+
+export function parseKnowledgeRecord(value: unknown): EvolutionKnowledgeRecord {
+  validateEvolutionKnowledgeRecord(value as EvolutionKnowledgeRecord);
+  return value as EvolutionKnowledgeRecord;
+}
+
+export function parseEvosCase(value: unknown): EvolutionEvosCase {
+  validateEvolutionEvosCase(value as EvolutionEvosCase);
+  return value as EvolutionEvosCase;
+}
+
+export function parseRepoProposal(value: unknown): EvolutionRepoProposal {
+  validateEvolutionRepoProposal(value as EvolutionRepoProposal);
+  return value as EvolutionRepoProposal;
+}
+
+export function parseReviewCandidate(value: unknown): EvolutionReviewCandidate {
+  validateEvolutionReviewCandidate(value as EvolutionReviewCandidate);
+  return value as EvolutionReviewCandidate;
+}
+
+export function parseTrigger(value: unknown): EvolutionTriggerRecord {
+  validateEvolutionTriggerRecord(value as EvolutionTriggerRecord);
+  return value as EvolutionTriggerRecord;
+}
+
+export function parseSegmentTrigger(value: unknown): SegmentEvolutionTriggerRecord {
+  validateSegmentEvolutionTriggerRecord(value as SegmentEvolutionTriggerRecord);
+  return value as SegmentEvolutionTriggerRecord;
+}
+
+export async function listDirectoryNames(dir: string): Promise<string[]> {
+  if (!(await pathExists(dir))) return [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+export function uniqueSorted(values: string[]): string[] {
+  return [...new Set(values)].sort();
+}
+
+export function collectRoleIds(evidenceWindow: EvolutionEvidenceWindow): string[] {
+  return uniqueSanitizedIds([
+    ...evidenceWindow.sourceRefs.flatMap((sourceRef) =>
+      sourceRef.roleId === null ? [] : [sourceRef.roleId],
+    ),
+    ...evidenceWindow.events.flatMap((event) => (event.roleId === null ? [] : [event.roleId])),
+  ]);
+}
+
+export function createPrivacyFields(value?: unknown): EvolutionPrivacyFields {
+  return {
+    classification: "local-private",
+    rawPromptsStored: false,
+    rawLogsStored: false,
+    sourceDumpsStored: false,
+    rawCommandOutputStored: false,
+    secretsStored: false,
+    internalLinksStored:
+      value !== undefined && detectSessionMemorySensitivity(value).reasons.includes("url"),
+  };
+}
+
+export function assertPrivacy(privacy: EvolutionPrivacyFields): void {
+  if (!isRecord(privacy)) throw new Error("privacy must be an object.");
+  if (privacy.classification !== "local-private") {
+    throw new Error("privacy.classification must be local-private.");
+  }
+  if (
+    privacy.rawPromptsStored !== false ||
+    privacy.rawLogsStored !== false ||
+    privacy.sourceDumpsStored !== false ||
+    privacy.rawCommandOutputStored !== false ||
+    privacy.secretsStored !== false
+  ) {
+    throw new Error("Evolution privacy fields must forbid raw content and credentials.");
+  }
+  if (typeof privacy.internalLinksStored !== "boolean") {
+    throw new Error("privacy.internalLinksStored must be boolean.");
+  }
+}
+
+export function assertProvenance(provenance: EvolutionKnowledgeRecord["provenance"]): void {
+  if (!isRecord(provenance)) throw new Error("provenance must be an object.");
+  assertString("provenance.runId", provenance.runId);
+  assertString("provenance.evidenceWindowId", provenance.evidenceWindowId);
+  assertString("provenance.createdAt", provenance.createdAt);
+  if (provenance.createdBy !== "evodev") throw new Error("provenance.createdBy must be evodev.");
+  if (
+    provenance.rawLogsStored !== false ||
+    provenance.rawPromptsStored !== false ||
+    provenance.sourceDumpsStored !== false ||
+    provenance.rawCommandOutputStored !== false
+  ) {
+    throw new Error(
+      "Evolution provenance cannot store raw logs, prompts, source, or command output.",
+    );
+  }
+}
+
+function assertEnum<T extends string>(
+  field: string,
+  value: unknown,
+  allowed: readonly T[],
+): asserts value is T {
+  if (typeof value !== "string" || !allowed.includes(value as T)) {
+    throw new Error(`${field} must be one of: ${allowed.join(", ")}`);
+  }
+}
+
+export function assertString(field: string, value: unknown): asserts value is string {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${field} must be a non-empty string.`);
+  }
+}
+
+export function assertNoForbiddenRawFields(value: unknown, path = ""): void {
+  if (value === null || value === undefined) return;
+  if (typeof value === "string") {
+    if (detectSessionMemorySensitivity(value).classification === "credential") {
+      throw new Error(`Evolution record contains a credential at ${path || "value"}.`);
+    }
+    return;
+  }
+  if (typeof value !== "object") return;
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => assertNoForbiddenRawFields(item, `${path}[${index}]`));
+    return;
+  }
+  for (const [key, child] of Object.entries(value)) {
+    const normalizedKey = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+    if (FORBIDDEN_RAW_KEYS.has(normalizedKey)) {
+      throw new Error(
+        `Evolution record contains forbidden raw field: ${path ? `${path}.` : ""}${key}`,
+      );
+    }
+    assertNoForbiddenRawFields(child, path ? `${path}.${key}` : key);
+  }
+}
+
+export function sanitizeText(value: string): string {
+  return redactSessionMemoryCredentialText(value)
+    .value.replace(/\s+/g, " ")
+    .trim()
+    .slice(0, MAX_TEXT_LENGTH);
+}
+
+export function sanitizeProposedChange(value: string): string {
+  return redactSessionMemoryCredentialText(value)
+    .value.replaceAll("\r\n", "\n")
+    .replaceAll("\r", "\n")
+    .trim()
+    .slice(0, MAX_PROPOSED_CHANGE_LENGTH);
+}
+
+export function sanitizeId(value: string): string {
+  return (
+    value
+      .replace(/[^a-zA-Z0-9._/-]/g, "-")
+      .replace(/[\\/]+/g, "-")
+      .slice(0, 160) || "local"
+  );
+}
+
+export function sanitizeStorageId(field: string, value: string): string {
+  const sanitized = sanitizeId(value);
+  if (sanitized === "." || sanitized === "..") {
+    throw new Error(`Invalid evolution ${field}: ${value}`);
+  }
+  if (sanitized.includes("/") || sanitized.includes("\\")) {
+    throw new Error(`Invalid evolution ${field}: ${value}`);
+  }
+  return sanitized;
+}
+
+export function assertPathDescendant(root: string, candidate: string, field: string): void {
+  const normalizedRoot = resolve(root);
+  const normalizedCandidate = resolve(candidate);
+  const relativePath = relative(normalizedRoot, normalizedCandidate);
+  if (relativePath === "" || relativePath.startsWith("..") || isAbsolute(relativePath)) {
+    throw new Error(`Evolution path ${field} escaped expected root.`);
+  }
+}
+
+export function sanitizeOptionalId(value: unknown): string | null {
+  if (typeof value !== "string" || value.trim() === "") return null;
+  return sanitizeId(value);
+}
+
+export function uniqueSanitizedIds(values: string[]): string[] {
+  return [...new Set(values.map(sanitizeId).filter((value) => value !== ""))];
+}
+
+export function sanitizeRelativePath(value: string): string {
+  const sanitized = value.replace(/\\/g, "/").replace(/^\/+/, "");
+  if (sanitized === "" || sanitized.startsWith("../") || sanitized.includes("/../")) {
+    throw new Error(`Invalid relative path in repo proposal: ${value}`);
+  }
+  return sanitized;
+}
+
+export function displayPath(homeDir: string, path: string): string {
+  const relativePath = relative(homeDir, path);
+  if (relativePath !== "" && !relativePath.startsWith("..")) return `~/${relativePath}`;
+  return path;
+}
+
+export function optionalString(value: unknown): string | null {
+  return typeof value === "string" && value.trim() !== "" ? value : null;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}