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

package/src/evolution/paths.ts

@@ -0,0 +1,44 @@
+import { join } from "node:path";
+import { resolveEvoDevPaths } from "../config/paths.ts";
+import type { EvolutionResolvedPaths } from "./schema.ts";
+import { assertPathDescendant, sanitizeStorageId } from "./shared.ts";
+
+export function resolveEvolutionPaths(input: {
+  homeDir: string;
+  projectKey: string;
+  runId: string;
+}): EvolutionResolvedPaths {
+  const paths = resolveEvoDevPaths(input.homeDir);
+  const projectKey = sanitizeStorageId("projectKey", input.projectKey);
+  const runId = sanitizeStorageId("runId", input.runId);
+  const evolutionStateDir = join(paths.stateDir, "evolution");
+  const projectStateDir = join(evolutionStateDir, projectKey);
+  const runStateDir = join(evolutionStateDir, projectKey, runId);
+  const repoProposalsDir = join(runStateDir, "proposals");
+  const reviewCandidatesDir = join(runStateDir, "review-candidates");
+  const knowledgeProjectDir = join(paths.knowledgeDir, projectKey);
+  const evosCasesProjectDir = join(paths.evosCasesDir, projectKey);
+  assertPathDescendant(evolutionStateDir, runStateDir, "runStateDir");
+  assertPathDescendant(evolutionStateDir, projectStateDir, "projectStateDir");
+  assertPathDescendant(evolutionStateDir, reviewCandidatesDir, "reviewCandidatesDir");
+  assertPathDescendant(paths.knowledgeDir, knowledgeProjectDir, "knowledgeProjectDir");
+  assertPathDescendant(paths.evosCasesDir, evosCasesProjectDir, "evosCasesProjectDir");
+  return {
+    projectKey,
+    runId,
+    evolutionStateDir,
+    runStateDir,
+    evidenceWindowPath: join(runStateDir, "evidence-window.json"),
+    batchPath: join(runStateDir, "distillation-batch.json"),
+    triggersDir: join(runStateDir, "triggers"),
+    reviewCandidatesDir,
+    repoProposalsDir,
+    repoProposalsIndexPath: join(runStateDir, "proposals.index.json"),
+    knowledgeProjectDir,
+    knowledgeRecordsDir: join(knowledgeProjectDir, "records"),
+    knowledgeIndexPath: join(knowledgeProjectDir, "index.json"),
+    knowledgeReviewHistoryPath: join(projectStateDir, "knowledge-review-history.jsonl"),
+    evosCasesProjectDir,
+    evosIndexPath: paths.evosIndexPath,
+  };
+}

package/src/evolution/processor/distillation.ts

@@ -0,0 +1,518 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { resolveEvoDevPaths } from "../../config/paths.ts";
+import {
+  createStableId,
+  normalizeTimestamp,
+  readJsonFiles,
+  writeJsonFile as writeJson,
+} from "../../utils/index.ts";
+import {
+  type OkfKnowledgePlan,
+  activateOkfKnowledgePlan,
+  createOkfKnowledgePlanFromDistillationBatch,
+} from "../knowledge/index.ts";
+import { resolveEvolutionPaths } from "../paths.ts";
+import type {
+  EvolutionActivationResult,
+  EvolutionConfidence,
+  EvolutionDistillationBatch,
+  EvolutionEvidenceWindow,
+  EvolutionEvosCase,
+  EvolutionKnowledgeRecord,
+  EvolutionRepoProposal,
+  EvolutionWriteResult,
+} from "../schema.ts";
+import {
+  collectRoleIds,
+  createEvolutionEvosCase,
+  createEvolutionKnowledgeRecord,
+  createPrivacyFields,
+  hasConcreteRepoProposalChanges,
+  listDirectoryNames,
+  parseEvosCase,
+  parseKnowledgeRecord,
+  parseRepoProposal,
+  sanitizeText,
+  validateEvolutionDistillationBatch,
+  validateEvolutionEvidenceWindow,
+  validateEvolutionEvosCase,
+  validateEvolutionRepoProposal,
+} from "../shared.ts";
+import { chooseEvosTriggerKind, createTriggerSummary } from "../triggers/classification.ts";
+
+export function createEvolutionDistillationBatch(input: {
+  evidenceWindow: EvolutionEvidenceWindow;
+  now?: string | Date;
+  warnings?: string[];
+}): EvolutionDistillationBatch {
+  validateEvolutionEvidenceWindow(input.evidenceWindow);
+  const createdAt = normalizeTimestamp(input.now);
+  const roleIds = collectRoleIds(input.evidenceWindow);
+  const sourceRefs = input.evidenceWindow.sourceRefs.map((sourceRef) => sourceRef.id);
+  const failedSignals = input.evidenceWindow.events.filter(
+    (event) =>
+      event.kind === "error" ||
+      event.triggerReason === "stop-failure" ||
+      event.triggerReason === "tool-failure" ||
+      event.triggerReason === "permission-denied" ||
+      /fail|failed|failure|error|issue/i.test(event.summary),
+  );
+  const verificationSignals = input.evidenceWindow.events
+    .filter(
+      (event) => event.kind === "verification" || /test|lint|typecheck|build/i.test(event.summary),
+    )
+    .slice(0, 8)
+    .map((event) => event.summary);
+  const autoKnowledgeEligible =
+    input.evidenceWindow.events.length > 0 &&
+    failedSignals.length === 0 &&
+    verificationSignals.length > 0 &&
+    input.evidenceWindow.triggerPolicy.distillRecommended &&
+    input.evidenceWindow.triggerPolicy.evidenceSignals.failures === 0;
+  const confidence: EvolutionConfidence = autoKnowledgeEligible
+    ? "high"
+    : failedSignals.length === 0
+      ? "medium"
+      : "low";
+
+  const knowledgeRecords = !autoKnowledgeEligible
+    ? []
+    : [
+        createEvolutionKnowledgeRecord({
+          id: createStableId("k", [input.evidenceWindow.id, "run-summary"]),
+          kind: "run-summary",
+          title: `Project run ${input.evidenceWindow.runId} evidence summary`,
+          projectKey: input.evidenceWindow.projectKey,
+          summary: createRunSummary(input.evidenceWindow, roleIds, failedSignals.length),
+          body: [
+            `Run ${input.evidenceWindow.runId} produced ${input.evidenceWindow.events.length} redacted metadata evidence event(s).`,
+            `Observed role(s): ${roleIds.length === 0 ? "none" : roleIds.join(", ")}.`,
+            "This record is derived from metadata-only evidence; active use depends on OKF plan review state.",
+          ].join("\n"),
+          roleTags: roleIds,
+          tags: ["project-run", "auto-stored", "unreviewed"],
+          reviewState: "auto-stored/unreviewed",
+          authority: "contextual",
+          confidence,
+          provenance: createProvenance(input.evidenceWindow, createdAt, sourceRefs),
+          relations: {
+            relatedKnowledgeIds: [],
+            evosCaseIds: [createStableId("evo", [input.evidenceWindow.id, "case"])],
+            proposalIds: [],
+            supersedes: [],
+          },
+          privacy: createPrivacyFields(),
+          runtime: { canLoad: true, hardBlocking: false },
+        }),
+      ];
+
+  const evosCases =
+    input.evidenceWindow.events.length === 0
+      ? []
+      : [
+          createEvolutionEvosCase({
+            id: createStableId("evo", [input.evidenceWindow.id, "case"]),
+            projectKey: input.evidenceWindow.projectKey,
+            title: `Run ${input.evidenceWindow.runId} evolution case`,
+            roleTags: roleIds,
+            tags: [
+              "project-run",
+              "evidence-window",
+              `trigger-${input.evidenceWindow.triggerPolicy.strongest}`,
+            ],
+            reviewState: "auto-stored/unreviewed",
+            confidence,
+            trigger: {
+              kind: chooseEvosTriggerKind(input.evidenceWindow),
+              summary: createTriggerSummary(input.evidenceWindow),
+            },
+            intervention: {
+              summary: `Collected ${input.evidenceWindow.events.length} metadata event(s) and ${input.evidenceWindow.episodes.length} episode(s) from EvoDev execution logs.`,
+              roleIds,
+            },
+            result: {
+              summary:
+                failedSignals.length === 0
+                  ? "No failure signal was detected in the redacted evidence summaries."
+                  : `${failedSignals.length} potential failure or issue signal(s) were detected.`,
+              verificationSignals,
+            },
+            expectedFutureBehavior:
+              "Future role agents should inspect accepted knowledge first and treat unreviewed cases as contextual evidence only.",
+            provenance: createProvenance(input.evidenceWindow, createdAt, sourceRefs),
+            privacy: createPrivacyFields(),
+          }),
+        ];
+
+  // Failure metadata is evidence, not a repository change proposal. A proposal is only valid
+  // after another stage supplies concrete target files and proposed changes.
+  const repoProposals: EvolutionRepoProposal[] = [];
+
+  const batch: EvolutionDistillationBatch = {
+    schemaVersion: 1,
+    id: createStableId("batch", [input.evidenceWindow.id, createdAt]),
+    projectKey: input.evidenceWindow.projectKey,
+    runId: input.evidenceWindow.runId,
+    createdAt,
+    evidenceWindow: input.evidenceWindow,
+    knowledgeRecords,
+    evosCases,
+    repoProposals,
+    warnings: (input.warnings ?? []).map(sanitizeText),
+  };
+  validateEvolutionDistillationBatch(batch);
+  return batch;
+}
+
+export async function writeEvolutionDistillationBatch(input: {
+  homeDir: string;
+  batch: EvolutionDistillationBatch;
+  overwrite?: boolean;
+}): Promise<EvolutionWriteResult> {
+  validateEvolutionDistillationBatch(input.batch);
+  const paths = resolveEvolutionPaths({
+    homeDir: input.homeDir,
+    projectKey: input.batch.projectKey,
+    runId: input.batch.runId,
+  });
+  const overwrite = input.overwrite === true;
+  await writeJson(paths.evidenceWindowPath, input.batch.evidenceWindow, { overwrite });
+  await writeJson(paths.batchPath, input.batch, { overwrite });
+
+  const knowledgePaths: string[] = [];
+  for (const record of input.batch.knowledgeRecords) {
+    const path = join(paths.knowledgeRecordsDir, `${record.id}.json`);
+    await writeJson(path, record, { overwrite });
+    knowledgePaths.push(path);
+  }
+
+  const evosCasePaths: string[] = [];
+  for (const evosCase of input.batch.evosCases) {
+    const path = join(paths.evosCasesProjectDir, `${evosCase.id}.json`);
+    await writeJson(path, evosCase, { overwrite });
+    evosCasePaths.push(path);
+  }
+
+  const repoProposalPaths: string[] = [];
+  for (const proposal of input.batch.repoProposals) {
+    const path = join(paths.repoProposalsDir, `${proposal.id}.json`);
+    await writeJson(path, proposal, { overwrite });
+    repoProposalPaths.push(path);
+  }
+
+  const allProjectKnowledgeRecords = await readJsonFiles(
+    paths.knowledgeRecordsDir,
+    parseKnowledgeRecord,
+  );
+  await writeJson(
+    paths.knowledgeIndexPath,
+    {
+      schemaVersion: 1,
+      projectKey: input.batch.projectKey,
+      updatedAt: input.batch.createdAt,
+      records: allProjectKnowledgeRecords.map((record) => ({
+        id: record.id,
+        kind: record.kind,
+        title: record.title,
+        reviewState: record.reviewState,
+        roleTags: record.roleTags,
+      })),
+    },
+    { overwrite: true },
+  );
+
+  const evosCasesRootDir = resolveEvoDevPaths(input.homeDir).evosCasesDir;
+  const evosProjectKeys = await listDirectoryNames(evosCasesRootDir);
+  const evosProjects = await Promise.all(
+    evosProjectKeys.map(async (projectKey) => {
+      const cases = await readJsonFiles(join(evosCasesRootDir, projectKey), parseEvosCase);
+      return {
+        projectKey,
+        cases: cases.map((evosCase) => ({
+          id: evosCase.id,
+          title: evosCase.title,
+          reviewState: evosCase.reviewState,
+        })),
+      };
+    }),
+  );
+  await writeJson(
+    paths.evosIndexPath,
+    {
+      schemaVersion: 1,
+      updatedAt: input.batch.createdAt,
+      projects: evosProjects,
+    },
+    { overwrite: true },
+  );
+
+  const allRunProposals = await readJsonFiles(paths.repoProposalsDir, parseRepoProposal);
+  await writeJson(
+    paths.repoProposalsIndexPath,
+    {
+      schemaVersion: 1,
+      projectKey: input.batch.projectKey,
+      runId: input.batch.runId,
+      updatedAt: input.batch.createdAt,
+      proposals: allRunProposals.map((proposal) => ({
+        id: proposal.id,
+        kind: proposal.kind,
+        title: proposal.title,
+        reviewState: proposal.reviewState,
+      })),
+    },
+    { overwrite: true },
+  );
+
+  return {
+    evidenceWindowPath: paths.evidenceWindowPath,
+    batchPath: paths.batchPath,
+    knowledgePaths,
+    evosCasePaths,
+    repoProposalPaths,
+    knowledgeIndexPath: paths.knowledgeIndexPath,
+    evosIndexPath: paths.evosIndexPath,
+  };
+}
+
+export async function writeEvolutionRepoProposal(input: {
+  homeDir: string;
+  proposal: EvolutionRepoProposal;
+}): Promise<{ proposalPath: string; indexPath: string }> {
+  validateEvolutionRepoProposal(input.proposal);
+  if (!hasConcreteRepoProposalChanges(input.proposal)) {
+    throw new Error("Repo proposal must include a target repository and concrete file changes.");
+  }
+  const paths = resolveEvolutionPaths({
+    homeDir: input.homeDir,
+    projectKey: input.proposal.projectKey,
+    runId: input.proposal.provenance.runId,
+  });
+  const proposalPath = join(paths.repoProposalsDir, `${input.proposal.id}.json`);
+  await writeJson(proposalPath, input.proposal, { overwrite: false });
+
+  const allRunProposals = await readJsonFiles(paths.repoProposalsDir, parseRepoProposal);
+  await writeJson(
+    paths.repoProposalsIndexPath,
+    {
+      schemaVersion: 1,
+      projectKey: input.proposal.projectKey,
+      runId: input.proposal.provenance.runId,
+      updatedAt: input.proposal.provenance.createdAt,
+      proposals: allRunProposals.map((proposal) => ({
+        id: proposal.id,
+        kind: proposal.kind,
+        title: proposal.title,
+        reviewState: proposal.reviewState,
+      })),
+    },
+    { overwrite: true },
+  );
+  return { proposalPath, indexPath: paths.repoProposalsIndexPath };
+}
+
+export async function activateEvolutionDistillationBatch(input: {
+  homeDir: string;
+  batch: EvolutionDistillationBatch;
+  overwrite?: boolean;
+}): Promise<EvolutionActivationResult> {
+  validateEvolutionDistillationBatch(input.batch);
+  const paths = resolveEvolutionPaths({
+    homeDir: input.homeDir,
+    projectKey: input.batch.projectKey,
+    runId: input.batch.runId,
+  });
+  const overwrite = input.overwrite === true;
+  await writeJson(paths.evidenceWindowPath, input.batch.evidenceWindow, { overwrite });
+  await writeJson(paths.batchPath, input.batch, { overwrite });
+
+  const plan = createOkfKnowledgePlanFromDistillationBatch(input.batch, {
+    homeDir: input.homeDir,
+  });
+  const okf = await activateOkfKnowledgePlan({
+    homeDir: input.homeDir,
+    plan,
+    overwrite,
+    evidenceWindowPath: paths.evidenceWindowPath,
+  });
+
+  const evosCasePaths: string[] = [];
+  for (const evosCase of input.batch.evosCases) {
+    const matchingCandidate = plan.candidates.find((candidate) => candidate.id === evosCase.id);
+    if (
+      matchingCandidate === undefined ||
+      matchingCandidate.decision === "no_write" ||
+      matchingCandidate.decision === "skip"
+    ) {
+      continue;
+    }
+    const persistedEvosCase =
+      matchingCandidate?.decision === "auto-accept"
+        ? { ...evosCase, reviewState: "auto-accepted" as const }
+        : matchingCandidate?.decision === "needs-human"
+          ? { ...evosCase, reviewState: "needs-human" as const }
+          : evosCase;
+    validateEvolutionEvosCase(persistedEvosCase);
+    const path = join(paths.evosCasesProjectDir, `${evosCase.id}.json`);
+    await writeJson(path, persistedEvosCase, { overwrite });
+    evosCasePaths.push(path);
+  }
+
+  const repoProposalPaths: string[] = [];
+  for (const proposal of input.batch.repoProposals) {
+    const path = join(paths.repoProposalsDir, `${proposal.id}.json`);
+    await writeJson(path, proposal, { overwrite });
+    repoProposalPaths.push(path);
+  }
+
+  const evosCasesRootDir = resolveEvoDevPaths(input.homeDir).evosCasesDir;
+  const evosProjectKeys = await listDirectoryNames(evosCasesRootDir);
+  const evosProjects = await Promise.all(
+    evosProjectKeys.map(async (projectKey) => {
+      const cases = await readJsonFiles(join(evosCasesRootDir, projectKey), parseEvosCase);
+      return {
+        projectKey,
+        cases: cases.map((evosCase) => ({
+          id: evosCase.id,
+          title: evosCase.title,
+          reviewState: evosCase.reviewState,
+        })),
+      };
+    }),
+  );
+  await writeJson(
+    paths.evosIndexPath,
+    {
+      schemaVersion: 1,
+      updatedAt: input.batch.createdAt,
+      projects: evosProjects,
+    },
+    { overwrite: true },
+  );
+
+  const allRunProposals = await readJsonFiles(paths.repoProposalsDir, parseRepoProposal);
+  await writeJson(
+    paths.repoProposalsIndexPath,
+    {
+      schemaVersion: 1,
+      projectKey: input.batch.projectKey,
+      runId: input.batch.runId,
+      updatedAt: input.batch.createdAt,
+      proposals: allRunProposals.map((proposal) => ({
+        id: proposal.id,
+        kind: proposal.kind,
+        title: proposal.title,
+        reviewState: proposal.reviewState,
+      })),
+    },
+    { overwrite: true },
+  );
+
+  return {
+    evidenceWindowPath: paths.evidenceWindowPath,
+    batchPath: paths.batchPath,
+    okf,
+    evosCasePaths,
+    repoProposalPaths,
+    evosIndexPath: paths.evosIndexPath,
+  };
+}
+
+/**
+ * Persists the minimized evidence/batch audit records and activates a curator-produced plan.
+ * The plan is required to describe the exact evidence window so a model cannot redirect a write to
+ * another project or run. Raw segment or transcript content is never accepted by this boundary.
+ */
+export async function activateCuratedSessionKnowledgePlan(input: {
+  homeDir: string;
+  evidenceWindow: EvolutionEvidenceWindow;
+  plan: OkfKnowledgePlan;
+  now?: string | Date;
+  warnings?: string[];
+  overwrite?: boolean;
+}): Promise<{ batch: EvolutionDistillationBatch; activation: EvolutionActivationResult }> {
+  validateEvolutionEvidenceWindow(input.evidenceWindow);
+  if (
+    input.plan.projectKey !== input.evidenceWindow.projectKey ||
+    input.plan.runId !== input.evidenceWindow.runId ||
+    input.plan.evidenceWindowId !== input.evidenceWindow.id
+  ) {
+    throw new Error("Curated knowledge plan identity does not match its evidence window.");
+  }
+
+  const createdAt = normalizeTimestamp(input.now ?? input.plan.createdAt);
+  const batch: EvolutionDistillationBatch = {
+    schemaVersion: 1,
+    id: createStableId("batch", [input.evidenceWindow.id, createdAt, "curated"]),
+    projectKey: input.evidenceWindow.projectKey,
+    runId: input.evidenceWindow.runId,
+    createdAt,
+    evidenceWindow: input.evidenceWindow,
+    knowledgeRecords: [],
+    evosCases: [],
+    repoProposals: [],
+    warnings: (input.warnings ?? []).map(sanitizeText),
+  };
+  validateEvolutionDistillationBatch(batch);
+
+  const paths = resolveEvolutionPaths({
+    homeDir: input.homeDir,
+    projectKey: batch.projectKey,
+    runId: batch.runId,
+  });
+  const overwrite = input.overwrite === true;
+  await writeJson(paths.evidenceWindowPath, batch.evidenceWindow, { overwrite });
+  await writeJson(paths.batchPath, batch, { overwrite });
+  const okf = await activateOkfKnowledgePlan({
+    homeDir: input.homeDir,
+    plan: input.plan,
+    overwrite,
+    evidenceWindowPath: paths.evidenceWindowPath,
+  });
+
+  return {
+    batch,
+    activation: {
+      evidenceWindowPath: paths.evidenceWindowPath,
+      batchPath: paths.batchPath,
+      okf,
+      evosCasePaths: [],
+      repoProposalPaths: [],
+      evosIndexPath: paths.evosIndexPath,
+    },
+  };
+}
+
+function createRunSummary(
+  evidenceWindow: EvolutionEvidenceWindow,
+  roleIds: string[],
+  failedSignalCount: number,
+): string {
+  const failureClause =
+    failedSignalCount === 0
+      ? "No failure signal was detected in metadata summaries."
+      : `${failedSignalCount} potential failure or issue signal(s) were detected.`;
+  return sanitizeText(
+    `Run ${evidenceWindow.runId} produced ${evidenceWindow.events.length} redacted event(s) across ${roleIds.length} role(s). ${failureClause}`,
+  );
+}
+
+function createProvenance(
+  evidenceWindow: EvolutionEvidenceWindow,
+  createdAt: string,
+  sourceRefs: string[],
+): EvolutionKnowledgeRecord["provenance"] {
+  return {
+    runId: evidenceWindow.runId,
+    taskId: evidenceWindow.taskId,
+    evidenceWindowId: evidenceWindow.id,
+    sourceRefs,
+    createdAt,
+    createdBy: "evodev",
+    rawLogsStored: false,
+    rawPromptsStored: false,
+    sourceDumpsStored: false,
+    rawCommandOutputStored: false,
+  };
+}

package/src/evolution/processor/index.ts

@@ -0,0 +1,3 @@
+export { analyzeEvolutionRun } from "../evidence/analysis.ts";
+export * from "./distillation.ts";
+export * from "./process.ts";