@evo-dev/core 0.0.1-alpha.3 → 0.0.1-alpha.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evo-dev/core",
-  "version": "0.0.1-alpha.3",
+  "version": "0.0.1-alpha.5",
   "type": "module",
   "repository": {
     "type": "git",

package/src/agents/index.ts

@@ -3,7 +3,7 @@ import {
   type ScopedKnowledgeContextPack,
   createScopedKnowledgeContextPack,
   formatScopedKnowledgePromptBlock,
-} from "../knowledge/index.ts";
+} from "../evolution/knowledge/index.ts";
 import type { TaskContract, TaskExecutionMode } from "../task/index.ts";
 
 export type AgentPersistence = "named" | "dynamic";

package/src/code-agent-traces/index.ts

@@ -1,8 +1,8 @@
-import { createHash } from "node:crypto";
 import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, normalize, relative } from "node:path";
 import { resolveEvoDevPaths } from "../config/paths.ts";
 import { resolveTraceSessionKey, resolveTraceTeamContext } from "../runtime-logs/index.ts";
+import { normalizeTimestamp, sha256Short } from "../utils/index.ts";
 
 export type CodeAgentTraceTarget = "claude" | "codex";
 export type CodeAgentTraceRefSource =
@@ -440,7 +440,7 @@ function hasRawTraversalSegment(path: string): boolean {
 
 function hashOptionalIdentifier(value: string | null): string | null {
   if (value === null || value.trim() === "") return null;
-  return `sha256-${createHash("sha256").update(value).digest("hex").slice(0, 16)}`;
+  return `sha256-${sha256Short(value)}`;
 }
 
 function sanitizeHashMetadata(value: string | null): string | null {
@@ -454,8 +454,7 @@ function sanitizePersistentIdentifier(value: string, prefix: string): string {
   if (!SENSITIVE_IDENTIFIER_PATTERN.test(value) && !SENSITIVE_IDENTIFIER_PATTERN.test(pathSafe)) {
     return pathSafe;
   }
-  const hash = createHash("sha256").update(value).digest("hex").slice(0, 16);
-  return `${prefix}-${hash}`;
+  return `${prefix}-${sha256Short(value)}`;
 }
 
 function sanitizeNotes(notes: string[]): string[] {
@@ -471,12 +470,6 @@ function sanitizeNote(note: string): string {
   return truncated;
 }
 
-function normalizeTimestamp(value?: Date | string): string {
-  if (value instanceof Date) return value.toISOString();
-  if (typeof value === "string" && value.trim() !== "") return new Date(value).toISOString();
-  return new Date().toISOString();
-}
-
 function optionalString(value: unknown): string | null {
   return typeof value === "string" && value.trim() !== "" ? value : null;
 }

package/src/config/settings.ts

@@ -1,4 +1,9 @@
 import { readFile } from "node:fs/promises";
+import {
+  type SessionMemoryPolicySnapshot,
+  createDefaultSessionMemoryPolicy,
+  parseSessionMemoryPolicy,
+} from "../evolution/evidence/session-memory/index.ts";
 import { type HookSettings, createDefaultHookSettings, parseHookSettings } from "../hooks/index.ts";
 import { EvoDevConfigError, describeType } from "./errors.ts";
 import { resolveEvoDevPaths } from "./paths.ts";
@@ -14,6 +19,7 @@ export interface MemorySettings {
   runtimeInjection: boolean;
   staleReview: boolean;
   lexicalIndex: boolean;
+  sessionMemory: SessionMemoryPolicySnapshot;
 }
 
 export interface EvoDevSettings {
@@ -115,6 +121,7 @@ export function createDefaultMemorySettings(): MemorySettings {
     runtimeInjection: true,
     staleReview: true,
     lexicalIndex: true,
+    sessionMemory: createDefaultSessionMemoryPolicy(),
   };
 }
 
@@ -247,6 +254,9 @@ function parseMemorySettings(value: unknown, path: string): MemorySettings {
       input.lexicalIndex === undefined
         ? defaults.lexicalIndex
         : expectBoolean(input.lexicalIndex, `${path}.lexicalIndex`),
+    sessionMemory: parseSessionMemoryPolicy(
+      isPlainRecord(input.sessionMemory) ? input.sessionMemory : defaults.sessionMemory,
+    ),
   };
 }
 
@@ -311,6 +321,10 @@ function expectRecord(value: unknown, path: string): Record<string, unknown> {
   return value as Record<string, unknown>;
 }
 
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 function isNotFoundError(error: unknown): boolean {
   return (
     error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT"

package/src/config/store.ts

@@ -1,6 +1,6 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
-import { ensureOkfKnowledgeBase } from "../knowledge/index.ts";
+import { ensureOkfKnowledgeBase } from "../evolution/knowledge/index.ts";
 import { EvoDevConfigError } from "./errors.ts";
 import { type EvoDevPaths, resolveEvoDevPaths } from "./paths.ts";
 import { type EvoDevRegistry, createDefaultRegistry, parseRegistry } from "./registry.ts";

package/src/daemon/index.ts

@@ -2,7 +2,7 @@ import { randomBytes } from "node:crypto";
 import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { type IncomingMessage, createServer } from "node:http";
 import { dirname, join } from "node:path";
-import { listEvolutionTriggers, processEvolutionTriggers } from "../evolution/index.ts";
+import { listEvolutionTriggers, processEvolutionTriggers } from "../evolution/control/index.ts";
 import { listObservabilityEvents } from "../observability/index.ts";
 import {
   type TeamRuntimeAdapter,

package/src/evolution/candidates/index.ts

@@ -0,0 +1,505 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { resolveEvoDevPaths } from "../../config/paths.ts";
+import { pathExists, readJsonFiles, writeJsonFile as writeJson } from "../../utils/index.ts";
+import { resolveEvolutionPaths } from "../paths.ts";
+import type {
+  EvolutionEvosCase,
+  EvolutionEvosCaseQueryResult,
+  EvolutionKnowledgeRecord,
+  EvolutionKnowledgeReviewHistoryRecord,
+  EvolutionRepoProposal,
+  EvolutionReviewCandidate,
+  EvolutionReviewSnapshot,
+  EvolutionReviewState,
+  EvolutionTriggerRecord,
+} from "../schema.ts";
+import {
+  REVIEW_STATES,
+  hasConcreteRepoProposalChanges,
+  listDirectoryNames,
+  parseEvosCase,
+  parseKnowledgeRecord,
+  parseRepoProposal,
+  parseReviewCandidate,
+  parseTrigger,
+  sanitizeId,
+  sanitizeStorageId,
+  sanitizeText,
+  uniqueSorted,
+  validateEvolutionKnowledgeRecord,
+  validateEvolutionRepoProposal,
+} from "../shared.ts";
+
+const REVIEW_LOCK_WAIT_MS = 2_000;
+const REVIEW_LOCK_RETRY_MS = 10;
+
+export async function withEvolutionReviewDecisionLock<T>(
+  input: {
+    homeDir: string;
+    kind: "learning" | "knowledge" | "repo-proposal";
+    itemId: string;
+  },
+  operation: () => Promise<T>,
+): Promise<T> {
+  const paths = resolveEvoDevPaths(input.homeDir);
+  const key = createHash("sha256").update(`${input.kind}\0${input.itemId}`).digest("hex");
+  const lockPath = join(paths.stateDir, "evolution", ".review-locks", `${key}.lock`);
+  const deadline = Date.now() + REVIEW_LOCK_WAIT_MS;
+  await mkdir(dirname(lockPath), { recursive: true });
+
+  while (true) {
+    try {
+      await writeFile(
+        lockPath,
+        `${JSON.stringify({ version: 1, kind: input.kind, acquiredAt: new Date().toISOString(), pid: process.pid })}\n`,
+        { encoding: "utf8", flag: "wx" },
+      );
+      break;
+    } catch (error) {
+      if (!isAlreadyExistsError(error)) throw error;
+      if (Date.now() >= deadline) throw new Error("Review decision lock is busy or stale.");
+      await sleep(REVIEW_LOCK_RETRY_MS);
+    }
+  }
+
+  try {
+    return await operation();
+  } finally {
+    await rm(lockPath, { force: true });
+  }
+}
+
+export async function readEvolutionReviewSnapshot(input: {
+  homeDir: string;
+  projectKey?: string;
+}): Promise<EvolutionReviewSnapshot> {
+  const paths = resolveEvoDevPaths(input.homeDir);
+  const projectKeys =
+    input.projectKey === undefined
+      ? await listEvolutionReviewProjectKeys(paths)
+      : [sanitizeStorageId("projectKey", input.projectKey)];
+  const knowledgeRecords: EvolutionKnowledgeRecord[] = [];
+  const evosCases: EvolutionEvosCase[] = [];
+  const repoProposals: EvolutionRepoProposal[] = [];
+  const reviewCandidates: EvolutionReviewCandidate[] = [];
+  const triggers: EvolutionTriggerRecord[] = [];
+
+  for (const projectKey of projectKeys) {
+    const resolved = resolveEvolutionPaths({
+      homeDir: input.homeDir,
+      projectKey,
+      runId: "review",
+    });
+    knowledgeRecords.push(
+      ...(await readJsonFiles(resolved.knowledgeRecordsDir, parseKnowledgeRecord)),
+    );
+    evosCases.push(...(await readJsonFiles(resolved.evosCasesProjectDir, parseEvosCase)));
+  }
+
+  const evolutionStateDir = join(paths.stateDir, "evolution");
+  const stateProjectKeys =
+    input.projectKey === undefined
+      ? await listDirectoryNames(evolutionStateDir)
+      : [sanitizeStorageId("projectKey", input.projectKey)];
+  for (const projectKey of stateProjectKeys) {
+    const projectStateDir = join(evolutionStateDir, projectKey);
+    const runIds = await listDirectoryNames(projectStateDir);
+    for (const runId of runIds) {
+      const proposalsDir = join(projectStateDir, runId, "proposals");
+      const reviewCandidatesDir = join(projectStateDir, runId, "review-candidates");
+      repoProposals.push(...(await readJsonFiles(proposalsDir, parseRepoProposal)));
+      reviewCandidates.push(...(await readJsonFiles(reviewCandidatesDir, parseReviewCandidate)));
+      triggers.push(
+        ...(await readJsonFiles(join(projectStateDir, runId, "triggers"), parseTrigger)),
+      );
+    }
+  }
+
+  return {
+    projectKey:
+      input.projectKey === undefined ? null : sanitizeStorageId("projectKey", input.projectKey),
+    knowledgeRecords,
+    evosCases,
+    repoProposals,
+    reviewCandidates,
+    triggers,
+  };
+}
+
+async function listEvolutionReviewProjectKeys(
+  paths: ReturnType<typeof resolveEvoDevPaths>,
+): Promise<string[]> {
+  const legacyKnowledgeProjectKeys = (
+    await Promise.all(
+      (
+        await listDirectoryNames(paths.knowledgeDir)
+      ).map(async (projectKey) =>
+        (await pathExists(join(paths.knowledgeDir, projectKey, "records"))) ? projectKey : null,
+      ),
+    )
+  ).filter((projectKey): projectKey is string => projectKey !== null);
+  return uniqueSorted([
+    ...legacyKnowledgeProjectKeys,
+    ...(await listDirectoryNames(paths.evosCasesDir)),
+  ]);
+}
+
+export async function listEvolutionKnowledgeRecords(input: {
+  homeDir: string;
+  projectKey?: string;
+}): Promise<EvolutionKnowledgeRecord[]> {
+  return (
+    await readEvolutionReviewSnapshot({
+      homeDir: input.homeDir,
+      projectKey: input.projectKey,
+    })
+  ).knowledgeRecords.sort((left, right) => left.id.localeCompare(right.id));
+}
+
+export async function listEvolutionKnowledgeReviewHistory(input: {
+  homeDir: string;
+  projectKey?: string;
+}): Promise<EvolutionKnowledgeReviewHistoryRecord[]> {
+  const paths = resolveEvoDevPaths(input.homeDir);
+  const projectKeys =
+    input.projectKey === undefined
+      ? await listDirectoryNames(join(paths.stateDir, "evolution"))
+      : [sanitizeStorageId("projectKey", input.projectKey)];
+  const records: EvolutionKnowledgeReviewHistoryRecord[] = [];
+
+  for (const projectKey of projectKeys) {
+    const historyPath = resolveEvolutionPaths({
+      homeDir: input.homeDir,
+      projectKey,
+      runId: "review",
+    }).knowledgeReviewHistoryPath;
+    if (!(await pathExists(historyPath))) continue;
+    for (const line of (await readFile(historyPath, "utf8")).split("\n")) {
+      if (line.trim() === "") continue;
+      records.push(parseKnowledgeReviewHistoryRecord(JSON.parse(line) as unknown));
+    }
+  }
+
+  return records.sort((left, right) => {
+    const changedAt = left.changedAt.localeCompare(right.changedAt);
+    if (changedAt !== 0) return changedAt;
+    return left.knowledgeId.localeCompare(right.knowledgeId);
+  });
+}
+
+export async function listEvolutionEvosCases(input: {
+  homeDir: string;
+  projectKey?: string;
+  roleId?: string;
+  reviewStates?: EvolutionReviewState[];
+}): Promise<EvolutionEvosCaseQueryResult> {
+  const paths = resolveEvoDevPaths(input.homeDir);
+  const projectKeys =
+    input.projectKey === undefined
+      ? await listDirectoryNames(paths.evosCasesDir)
+      : [sanitizeStorageId("projectKey", input.projectKey)];
+  const roleId = input.roleId === undefined ? null : sanitizeId(input.roleId);
+  const reviewStates = input.reviewStates ?? ["accepted", "auto-accepted"];
+  const cases: EvolutionEvosCase[] = [];
+  const warnings: string[] = [];
+
+  for (const projectKey of projectKeys) {
+    const projectDir = join(paths.evosCasesDir, projectKey);
+    if (!(await pathExists(projectDir))) continue;
+    const entries = await readdir(projectDir, { withFileTypes: true });
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+      if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+      const sourceLink = `cases/${projectKey}/${entry.name}`;
+      try {
+        const value = JSON.parse(await readFile(join(projectDir, entry.name), "utf8")) as unknown;
+        const evosCase = parseEvosCase(value);
+        if (!reviewStates.includes(evosCase.reviewState)) continue;
+        if (
+          roleId !== null &&
+          evosCase.roleTags.length > 0 &&
+          !evosCase.roleTags.includes(roleId)
+        ) {
+          continue;
+        }
+        cases.push(evosCase);
+      } catch {
+        warnings.push(
+          `Omitted unsafe or invalid evos case: ${sourceLink}. Run evodev knowledge lint.`,
+        );
+      }
+    }
+  }
+
+  return {
+    cases: cases.sort((left, right) => {
+      const project = left.projectKey.localeCompare(right.projectKey);
+      if (project !== 0) return project;
+      return left.id.localeCompare(right.id);
+    }),
+    warnings,
+  };
+}
+
+export async function readEvolutionKnowledgeRecordById(input: {
+  homeDir: string;
+  knowledgeId: string;
+  projectKey?: string;
+}): Promise<EvolutionKnowledgeRecord> {
+  const matches = (await listEvolutionKnowledgeRecords(input)).filter(
+    (record) => record.id === input.knowledgeId,
+  );
+  if (matches.length === 0) throw new Error(`Knowledge record not found: ${input.knowledgeId}`);
+  if (matches.length > 1) {
+    throw new Error(`Knowledge record id is ambiguous across projects: ${input.knowledgeId}`);
+  }
+  return matches[0] as EvolutionKnowledgeRecord;
+}
+
+export async function updateEvolutionKnowledgeReviewState(input: {
+  homeDir: string;
+  knowledgeId: string;
+  projectKey?: string;
+  reviewState: "accepted" | "rejected" | "deferred";
+  expectedReviewState?: EvolutionReviewState;
+  now?: string | Date;
+}): Promise<{ path: string; record: EvolutionKnowledgeRecord; changed: boolean }> {
+  return await withEvolutionReviewDecisionLock(
+    { homeDir: input.homeDir, kind: "knowledge", itemId: input.knowledgeId },
+    async () => {
+      const record = await readEvolutionKnowledgeRecordById(input);
+      if (
+        input.expectedReviewState !== undefined &&
+        record.reviewState !== input.expectedReviewState
+      ) {
+        throw new Error("Knowledge review state changed before the decision was applied.");
+      }
+      const paths = resolveEvolutionPaths({
+        homeDir: input.homeDir,
+        projectKey: record.projectKey,
+        runId: "review",
+      });
+      const path = join(paths.knowledgeRecordsDir, `${record.id}.json`);
+      if (record.reviewState === input.reviewState) return { path, record, changed: false };
+
+      const changedAt = normalizeTimestamp(input.now);
+      const next: EvolutionKnowledgeRecord = {
+        ...record,
+        reviewState: input.reviewState,
+        authority: input.reviewState === "accepted" ? "reviewed" : "contextual",
+        runtime: {
+          ...record.runtime,
+          // Legacy JSON review records are not active OKF concepts.
+          canLoad: false,
+          hardBlocking: false,
+        },
+      };
+      validateEvolutionKnowledgeRecord(next);
+      await writeJson(path, next, { overwrite: true });
+      const allProjectKnowledgeRecords = await readJsonFiles(
+        paths.knowledgeRecordsDir,
+        parseKnowledgeRecord,
+      );
+      await writeJson(
+        paths.knowledgeIndexPath,
+        {
+          version: 1,
+          kind: "evolution-knowledge-index",
+          projectKey: next.projectKey,
+          updatedAt: changedAt,
+          records: allProjectKnowledgeRecords.map((item) => ({
+            id: item.id,
+            kind: item.kind,
+            title: item.title,
+            roleTags: item.roleTags,
+            tags: item.tags,
+            reviewState: item.reviewState,
+            authority: item.authority,
+            confidence: item.confidence,
+            runtime: item.runtime,
+          })),
+        },
+        { overwrite: true },
+      );
+      const history: EvolutionKnowledgeReviewHistoryRecord = {
+        version: 1,
+        kind: "evolution-knowledge-review-state-changed",
+        knowledgeId: next.id,
+        projectKey: next.projectKey,
+        roleTags: uniqueSorted(next.roleTags),
+        artifactCreatedAt: next.provenance.createdAt,
+        previousReviewState: record.reviewState,
+        nextReviewState: next.reviewState,
+        changedAt,
+        metadataOnly: true,
+      };
+      await mkdir(dirname(paths.knowledgeReviewHistoryPath), { recursive: true });
+      await writeFile(paths.knowledgeReviewHistoryPath, `${JSON.stringify(history)}\n`, {
+        encoding: "utf8",
+        flag: "a",
+      });
+      return { path, record: next, changed: true };
+    },
+  );
+}
+
+export async function readEvolutionRepoProposalById(input: {
+  homeDir: string;
+  proposalId: string;
+  projectKey?: string;
+}): Promise<EvolutionRepoProposal> {
+  const matches = (
+    await readEvolutionReviewSnapshot({
+      homeDir: input.homeDir,
+      projectKey: input.projectKey,
+    })
+  ).repoProposals.filter((proposal) => proposal.id === input.proposalId);
+  if (matches.length === 0) throw new Error(`Repo proposal not found: ${input.proposalId}`);
+  if (matches.length > 1) {
+    throw new Error(`Repo proposal id is ambiguous across runs: ${input.proposalId}`);
+  }
+  return matches[0] as EvolutionRepoProposal;
+}
+
+export async function updateEvolutionRepoProposalReviewState(input: {
+  homeDir: string;
+  proposalId: string;
+  projectKey?: string;
+  reviewState: "accepted" | "rejected" | "deferred";
+  expectedReviewState?: EvolutionRepoProposal["reviewState"];
+  reason?: string;
+  now?: string | Date;
+}): Promise<{ path: string; record: EvolutionRepoProposal; changed: boolean }> {
+  return await withEvolutionReviewDecisionLock(
+    { homeDir: input.homeDir, kind: "repo-proposal", itemId: input.proposalId },
+    async () => {
+      const record = await readEvolutionRepoProposalById(input);
+      if (!hasConcreteRepoProposalChanges(record)) {
+        throw new Error("Repo proposal has no concrete repository changes to review.");
+      }
+      const reason = input.reason?.trim();
+      if (input.reviewState === "rejected" && reason === undefined) {
+        throw new Error("Rejecting a repo proposal requires a reason.");
+      }
+      if (reason !== undefined && (reason === "" || reason.length > 500)) {
+        throw new Error("Repo proposal review reason must be 1-500 characters.");
+      }
+      if (
+        input.expectedReviewState !== undefined &&
+        record.reviewState !== input.expectedReviewState
+      ) {
+        throw new Error("Repo proposal review state changed before the decision was applied.");
+      }
+      const paths = resolveEvolutionPaths({
+        homeDir: input.homeDir,
+        projectKey: record.projectKey,
+        runId: record.provenance.runId,
+      });
+      const path = join(paths.repoProposalsDir, `${record.id}.json`);
+      if (record.reviewState === input.reviewState) return { path, record, changed: false };
+
+      const changedAt = normalizeTimestamp(input.now);
+      const next: EvolutionRepoProposal = {
+        ...record,
+        reviewState: input.reviewState,
+        reviewStateChangedAt: changedAt,
+        lastDecision: {
+          state: input.reviewState,
+          reason: reason === undefined ? null : sanitizeText(reason),
+          decidedAt: changedAt,
+        },
+      };
+      validateEvolutionRepoProposal(next);
+      await writeJson(path, next, { overwrite: true });
+      const allRunProposals = await readJsonFiles(paths.repoProposalsDir, parseRepoProposal);
+      await writeJson(
+        paths.repoProposalsIndexPath,
+        {
+          schemaVersion: 1,
+          projectKey: next.projectKey,
+          runId: next.provenance.runId,
+          updatedAt: changedAt,
+          proposals: allRunProposals.map((proposal) => ({
+            id: proposal.id,
+            kind: proposal.kind,
+            title: proposal.title,
+            reviewState: proposal.reviewState,
+          })),
+        },
+        { overwrite: true },
+      );
+      return { path, record: next, changed: true };
+    },
+  );
+}
+
+function parseKnowledgeReviewHistoryRecord(value: unknown): EvolutionKnowledgeReviewHistoryRecord {
+  if (!isRecord(value)) throw new Error("Knowledge review history record must be an object.");
+  const allowedKeys = new Set([
+    "version",
+    "kind",
+    "knowledgeId",
+    "projectKey",
+    "roleTags",
+    "artifactCreatedAt",
+    "previousReviewState",
+    "nextReviewState",
+    "changedAt",
+    "metadataOnly",
+  ]);
+  if (Object.keys(value).some((key) => !allowedKeys.has(key))) {
+    throw new Error("Knowledge review history record contains unsupported fields.");
+  }
+  if (
+    value.version !== 1 ||
+    value.kind !== "evolution-knowledge-review-state-changed" ||
+    typeof value.knowledgeId !== "string" ||
+    typeof value.projectKey !== "string" ||
+    !Array.isArray(value.roleTags) ||
+    !value.roleTags.every((roleId) => typeof roleId === "string") ||
+    typeof value.artifactCreatedAt !== "string" ||
+    typeof value.previousReviewState !== "string" ||
+    !REVIEW_STATES.includes(value.previousReviewState as EvolutionReviewState) ||
+    typeof value.nextReviewState !== "string" ||
+    !REVIEW_STATES.includes(value.nextReviewState as EvolutionReviewState) ||
+    typeof value.changedAt !== "string" ||
+    value.metadataOnly !== true
+  ) {
+    throw new Error("Invalid knowledge review history record.");
+  }
+  normalizeTimestamp(value.artifactCreatedAt);
+  normalizeTimestamp(value.changedAt);
+  return {
+    version: 1,
+    kind: "evolution-knowledge-review-state-changed",
+    knowledgeId: sanitizeId(value.knowledgeId),
+    projectKey: sanitizeStorageId("projectKey", value.projectKey),
+    roleTags: uniqueSorted(value.roleTags.map(sanitizeId)),
+    artifactCreatedAt: value.artifactCreatedAt,
+    previousReviewState: value.previousReviewState as EvolutionReviewState,
+    nextReviewState: value.nextReviewState as EvolutionReviewState,
+    changedAt: value.changedAt,
+    metadataOnly: true,
+  };
+}
+
+function normalizeTimestamp(value: string | Date | undefined): string {
+  const date = value === undefined ? new Date() : value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) throw new Error("Invalid knowledge review history timestamp.");
+  return date.toISOString();
+}
+
+function isAlreadyExistsError(error: unknown): boolean {
+  return (
+    error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "EEXIST"
+  );
+}
+
+async function sleep(milliseconds: number): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/evolution/control/index.ts

@@ -0,0 +1,19 @@
+export {
+  formatEvolutionProcessResult,
+  formatEvolutionReviewSnapshot,
+} from "../formatters.ts";
+export { processEvolutionTriggers } from "../processor/index.ts";
+export { readEvolutionReviewSnapshot } from "../candidates/index.ts";
+export {
+  listEvolutionTriggers,
+  listSegmentEvolutionTriggers,
+} from "../triggers/index.ts";
+export type {
+  EvolutionProcessInput,
+  EvolutionProcessResult,
+  EvolutionReviewSnapshot,
+  EvolutionTriggerListInput,
+  EvolutionTriggerRecord,
+  SegmentEvolutionTriggerListInput,
+  SegmentEvolutionTriggerRecord,
+} from "../schema.ts";