@evo-dev/core 0.0.1-alpha.11 → 0.0.1-alpha.13

package/package.json

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

package/src/evolution/candidates/index.ts

@@ -7,6 +7,8 @@ import { resolveEvolutionPaths } from "../paths.ts";
 import type {
   EvolutionEvosCase,
   EvolutionEvosCaseQueryResult,
+  EvolutionImprovementEvalResult,
+  EvolutionImprovementEvalStatus,
   EvolutionKnowledgeRecord,
   EvolutionKnowledgeReviewHistoryRecord,
   EvolutionRepoProposal,
@@ -17,7 +19,9 @@ import type {
 } from "../schema.ts";
 import {
   REVIEW_STATES,
+  createEvolutionImprovementEval,
   hasConcreteRepoProposalChanges,
+  isEvolutionImprovementEvalRecommended,
   listDirectoryNames,
   parseEvosCase,
   parseKnowledgeRecord,
@@ -368,6 +372,7 @@ export async function updateEvolutionRepoProposalReviewState(input: {
   projectKey?: string;
   reviewState: "accepted" | "rejected" | "deferred";
   expectedReviewState?: EvolutionRepoProposal["reviewState"];
+  improvementEvalRequested?: boolean;
   reason?: string;
   now?: string | Date;
 }): Promise<{ path: string; record: EvolutionRepoProposal; changed: boolean }> {
@@ -400,10 +405,25 @@ export async function updateEvolutionRepoProposalReviewState(input: {
       if (record.reviewState === input.reviewState) return { path, record, changed: false };
 
       const changedAt = normalizeTimestamp(input.now);
+      const improvementEval =
+        input.reviewState === "accepted"
+          ? createEvolutionImprovementEval({
+              kind: record.kind,
+              requested:
+                input.improvementEvalRequested ??
+                isEvolutionImprovementEvalRecommended(record.kind),
+              now: changedAt,
+            })
+          : createEvolutionImprovementEval({
+              kind: record.kind,
+              requested: false,
+              now: changedAt,
+            });
       const next: EvolutionRepoProposal = {
         ...record,
         reviewState: input.reviewState,
         reviewStateChangedAt: changedAt,
+        improvementEval,
         lastDecision: {
           state: input.reviewState,
           reason: reason === undefined ? null : sanitizeText(reason),
@@ -417,6 +437,101 @@ export async function updateEvolutionRepoProposalReviewState(input: {
   );
 }
 
+export async function updateEvolutionRepoProposalImprovementEval(input: {
+  homeDir: string;
+  proposalId: string;
+  projectKey?: string;
+  status: Exclude<EvolutionImprovementEvalStatus, "not-requested" | "awaiting-eval">;
+  expectedStatus?: EvolutionImprovementEvalStatus;
+  evidenceRef?: string | null;
+  result?: Omit<EvolutionImprovementEvalResult, "retention">;
+  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 (record.reviewState !== "accepted") {
+        throw new Error("Only accepted repo proposals can be evaluated.");
+      }
+      const current = record.improvementEval;
+      if (current === undefined || !current.requested) {
+        throw new Error("Repo proposal improvement evaluation was not requested.");
+      }
+      if (input.expectedStatus !== undefined && current.status !== input.expectedStatus) {
+        throw new Error("Repo proposal improvement evaluation state changed before update.");
+      }
+      if (
+        input.status !== "evaluating" &&
+        input.status !== "effective" &&
+        input.status !== "ineffective" &&
+        input.status !== "inconclusive"
+      ) {
+        throw new Error("Repo proposal improvement evaluation state is invalid.");
+      }
+      if (
+        input.status === "evaluating" &&
+        current.status !== "awaiting-eval" &&
+        current.status !== "evaluating"
+      ) {
+        throw new Error("Only an awaiting improvement evaluation can start.");
+      }
+      if (input.status !== "evaluating" && current.status !== "evaluating") {
+        throw new Error("Only a running improvement evaluation can complete.");
+      }
+      const completed = input.status !== "evaluating";
+      if (completed !== (input.result !== undefined)) {
+        throw new Error("Completed improvement evaluation requires a result.");
+      }
+      const changedAt = normalizeTimestamp(input.now);
+      const result: EvolutionImprovementEvalResult | null =
+        input.result === undefined
+          ? null
+          : {
+              targetImproved: input.result.targetImproved,
+              hardRegression: input.result.hardRegression,
+              summary: sanitizeText(input.result.summary),
+              assertions: input.result.assertions.slice(0, 8).map((assertion) => ({
+                label: sanitizeText(assertion.label),
+                status: assertion.status,
+              })),
+              evaluatedBy: input.result.evaluatedBy,
+              metrics: { ...input.result.metrics },
+              retention: {
+                metadataOnly: true,
+                replayInputStored: false,
+                replayOutputStored: false,
+              },
+            };
+      const evidenceRef =
+        input.evidenceRef === undefined
+          ? current.evidenceRef
+          : input.evidenceRef === null
+            ? null
+            : sanitizeId(input.evidenceRef);
+      const next: EvolutionRepoProposal = {
+        ...record,
+        improvementEval: {
+          ...current,
+          status: input.status,
+          evaluatedAt: completed ? changedAt : null,
+          evidenceRef,
+          result,
+        },
+      };
+      validateEvolutionRepoProposal(next);
+      const paths = resolveEvolutionPaths({
+        homeDir: input.homeDir,
+        projectKey: record.projectKey,
+        runId: record.provenance.runId,
+      });
+      const path = join(paths.repoProposalsDir, `${record.id}.json`);
+      await writeRepoProposalAndIndex({ homeDir: input.homeDir, proposal: next, changedAt });
+      return { path, record: next, changed: true };
+    },
+  );
+}
+
 export async function markEvolutionRepoProposalApplied(input: {
   homeDir: string;
   proposalId: string;
@@ -487,6 +602,7 @@ async function writeRepoProposalAndIndex(input: {
         kind: proposal.kind,
         title: proposal.title,
         reviewState: proposal.reviewState,
+        improvementEvalStatus: proposal.improvementEval?.status ?? "not-requested",
       })),
     },
     { overwrite: true },

package/src/evolution/evidence/session-memory/analysis.ts

@@ -34,6 +34,7 @@ import type {
 export type SessionSegmentDistillationSkipReason =
   | "sensitive-segment"
   | "segment-deleted"
+  | "segment-raw-expired"
   | "segment-ignored"
   | "segment-rejected"
   | "no-distillation-signal";
@@ -55,6 +56,7 @@ export function analyzeSessionEvidenceSegment(input: {
 }): SessionSegmentEvidenceAnalysis {
   const { segment } = input;
   if (segment.lifecycle.status === "deleted") return skipped("segment-deleted");
+  if (segment.lifecycle.status === "raw-expired") return skipped("segment-raw-expired");
   if (segment.lifecycle.status === "ignored") return skipped("segment-ignored");
   if (segment.lifecycle.reviewState === "rejected") return skipped("segment-rejected");
 
@@ -241,6 +243,9 @@ function classifySegmentTrigger(
 ): { strength: EvolutionTriggerStrength; reason: EvolutionTriggerReason } {
   if (reason === "failure-signal") return { strength: "strong", reason: "failure-signal" };
   if (reason === "permission-denied") return { strength: "strong", reason: "permission-denied" };
+  if (reason === "historical-import") {
+    return { strength: "strong", reason: "explicit-command" };
+  }
   if (reason === "session-memory-init") return { strength: "none", reason: "none" };
   return {
     strength: strength === "strong" ? "strong" : "conditional",
@@ -258,7 +263,8 @@ function isSegmentEligibleForDistillation(
     segment.reason === "failure-signal" ||
     segment.reason === "permission-denied" ||
     segment.reason === "verification-after-fix" ||
-    segment.reason === "explicit-memory-intent"
+    segment.reason === "explicit-memory-intent" ||
+    segment.reason === "historical-import"
   ) {
     return true;
   }

package/src/evolution/evidence/session-memory/index.ts

@@ -2,6 +2,8 @@ export * from "./analysis.ts";
 export * from "./paths.ts";
 export * from "./policy.ts";
 export * from "./sensitivity.ts";
+export * from "./semantic-packet.ts";
+export * from "./retention.ts";
 export * from "./storage.ts";
 export * from "./types.ts";
 export * from "./updater.ts";

package/src/evolution/evidence/session-memory/retention.ts

@@ -0,0 +1,361 @@
+import { createStableId, normalizeTimestamp, sha256Hex } from "../../../utils/index.ts";
+import { readEvolutionReviewSnapshot } from "../../candidates/index.ts";
+import type { EvolutionReviewSnapshot, SegmentEvolutionTriggerRecord } from "../../schema.ts";
+import { listSegmentEvolutionTriggers } from "../../triggers/index.ts";
+import {
+  listSessionEvidenceSegments,
+  readSessionEvidenceSegment,
+  writeSessionEvidenceSegmentAtomic,
+} from "./storage.ts";
+import type { SessionEvidenceSegmentV1 } from "./types.ts";
+
+const DEFAULT_RETENTION_LIMIT = 20;
+const MAX_RETENTION_LIMIT = 20;
+
+export type HistoricalSessionEvidenceRetentionProtectionReason =
+  | "trigger-missing"
+  | "trigger-not-terminal"
+  | "segment-review-pending"
+  | "derived-review-pending"
+  | "retention-invalid"
+  | "segment-changed";
+
+export interface PurgeExpiredHistoricalSessionEvidenceResult {
+  scanned: number;
+  due: number;
+  purged: number;
+  alreadyPurged: number;
+  protected: Array<{
+    projectKey: string;
+    segmentId: string;
+    reason: HistoricalSessionEvidenceRetentionProtectionReason;
+  }>;
+}
+
+export interface HistoricalSessionEvidenceRetentionInspection {
+  available: number;
+  purged: number;
+  overdue: number;
+  purgeEligible: number;
+  protected: number;
+  protectionReasons: Partial<Record<HistoricalSessionEvidenceRetentionProtectionReason, number>>;
+}
+
+export async function inspectHistoricalSessionEvidenceRetention(input: {
+  homeDir: string;
+  projectKey?: string;
+  now?: string | Date;
+}): Promise<HistoricalSessionEvidenceRetentionInspection> {
+  const now = normalizeTimestamp(input.now);
+  const historical = (
+    await listSessionEvidenceSegments({
+      homeDir: input.homeDir,
+      projectKey: input.projectKey,
+    })
+  ).filter(
+    (segment) => segment.origin?.kind === "historical-import" && segment.retention !== undefined,
+  );
+  const result: HistoricalSessionEvidenceRetentionInspection = {
+    available: 0,
+    purged: 0,
+    overdue: 0,
+    purgeEligible: 0,
+    protected: 0,
+    protectionReasons: {},
+  };
+  const reviewSnapshots = new Map<string, Promise<EvolutionReviewSnapshot>>();
+  for (const segment of historical) {
+    if (segment.retention?.rawState === "purged") {
+      result.purged += 1;
+      continue;
+    }
+    result.available += 1;
+    if (!hasValidAvailableRetention(segment)) {
+      result.overdue += 1;
+      result.protected += 1;
+      result.protectionReasons["retention-invalid"] =
+        (result.protectionReasons["retention-invalid"] ?? 0) + 1;
+      continue;
+    }
+    if (
+      segment.retention === undefined ||
+      Date.parse(segment.retention.expiresAt) > Date.parse(now)
+    ) {
+      continue;
+    }
+    result.overdue += 1;
+    const protection = await findRetentionProtection({
+      homeDir: input.homeDir,
+      segment,
+      reviewSnapshots,
+    });
+    if (protection === null) {
+      result.purgeEligible += 1;
+      continue;
+    }
+    result.protected += 1;
+    result.protectionReasons[protection] = (result.protectionReasons[protection] ?? 0) + 1;
+  }
+  return result;
+}
+
+export async function purgeExpiredHistoricalSessionEvidence(input: {
+  homeDir: string;
+  projectKey?: string;
+  now?: string | Date;
+  limit?: number;
+}): Promise<PurgeExpiredHistoricalSessionEvidenceResult> {
+  const now = normalizeTimestamp(input.now);
+  const limit = normalizeLimit(input.limit);
+  const historical = (
+    await listSessionEvidenceSegments({
+      homeDir: input.homeDir,
+      projectKey: input.projectKey,
+    })
+  )
+    .filter(
+      (segment) => segment.origin?.kind === "historical-import" && segment.retention !== undefined,
+    )
+    .sort(
+      (left, right) =>
+        (left.retention?.expiresAt ?? "").localeCompare(right.retention?.expiresAt ?? "") ||
+        left.id.localeCompare(right.id),
+    );
+  const result: PurgeExpiredHistoricalSessionEvidenceResult = {
+    scanned: 0,
+    due: 0,
+    purged: 0,
+    alreadyPurged: 0,
+    protected: [],
+  };
+  const reviewSnapshots = new Map<string, Promise<EvolutionReviewSnapshot>>();
+
+  result.alreadyPurged = historical.filter(
+    (segment) => segment.retention?.rawState === "purged",
+  ).length;
+  for (const segment of historical) {
+    if (result.scanned >= limit) break;
+    if (segment.retention === undefined || segment.retention.rawState === "purged") continue;
+    result.scanned += 1;
+    if (!hasValidAvailableRetention(segment)) {
+      result.due += 1;
+      result.protected.push({
+        projectKey: segment.projectKey,
+        segmentId: segment.id,
+        reason: "retention-invalid",
+      });
+      continue;
+    }
+    if (Date.parse(segment.retention.expiresAt) > Date.parse(now)) continue;
+    result.due += 1;
+
+    const protection = await findRetentionProtection({
+      homeDir: input.homeDir,
+      segment,
+      reviewSnapshots,
+    });
+    if (protection !== null) {
+      result.protected.push({
+        projectKey: segment.projectKey,
+        segmentId: segment.id,
+        reason: protection,
+      });
+      continue;
+    }
+
+    const current = await readSessionEvidenceSegment({
+      homeDir: input.homeDir,
+      projectKey: segment.projectKey,
+      sessionKey: segment.sessionKey,
+      segmentId: segment.id,
+    });
+    const currentTrigger = await findSegmentTrigger(input.homeDir, current);
+    if (
+      !hasValidAvailableRetention(current) ||
+      current.retention?.rawState !== "available" ||
+      current.retention.expiresAt !== segment.retention.expiresAt ||
+      !current.rawExcerpt.stored ||
+      current.rawExcerpt.sha256 !== segment.rawExcerpt.sha256 ||
+      current.lifecycle.reviewState !== segment.lifecycle.reviewState ||
+      currentTrigger === null ||
+      !isTerminalTrigger(currentTrigger)
+    ) {
+      result.protected.push({
+        projectKey: segment.projectKey,
+        segmentId: segment.id,
+        reason: "segment-changed",
+      });
+      continue;
+    }
+    const freshSnapshot = await readEvolutionReviewSnapshot({
+      homeDir: input.homeDir,
+      projectKey: current.projectKey,
+    });
+    if (hasPendingDerivedReview(freshSnapshot, current)) {
+      result.protected.push({
+        projectKey: segment.projectKey,
+        segmentId: segment.id,
+        reason: "derived-review-pending",
+      });
+      continue;
+    }
+
+    await writeSessionEvidenceSegmentAtomic({
+      homeDir: input.homeDir,
+      segment: createPurgedHistoricalSegment(current, now),
+    });
+    result.purged += 1;
+  }
+
+  return result;
+}
+
+function normalizeLimit(value: number | undefined): number {
+  const limit = value ?? DEFAULT_RETENTION_LIMIT;
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_RETENTION_LIMIT) {
+    throw new Error(
+      `Historical Session Evidence retention limit must be between 1 and ${MAX_RETENTION_LIMIT}.`,
+    );
+  }
+  return limit;
+}
+
+function hasValidAvailableRetention(segment: SessionEvidenceSegmentV1): boolean {
+  const retention = segment.retention;
+  return (
+    retention !== undefined &&
+    retention.rawState === "available" &&
+    retention.rawPurgedAt === null &&
+    Number.isFinite(Date.parse(retention.expiresAt)) &&
+    /^[a-f0-9]{64}$/u.test(retention.originalRawSha256) &&
+    segment.rawExcerpt.stored &&
+    segment.rawExcerpt.byteLength === Buffer.byteLength(segment.rawExcerpt.content, "utf8") &&
+    segment.rawExcerpt.sha256 === sha256Hex(segment.rawExcerpt.content) &&
+    retention.originalRawSha256 === segment.rawExcerpt.sha256
+  );
+}
+
+async function findRetentionProtection(input: {
+  homeDir: string;
+  segment: SessionEvidenceSegmentV1;
+  reviewSnapshots: Map<string, Promise<EvolutionReviewSnapshot>>;
+}): Promise<HistoricalSessionEvidenceRetentionProtectionReason | null> {
+  if (
+    input.segment.lifecycle.reviewState === "unreviewed" ||
+    input.segment.lifecycle.reviewState === "deferred"
+  ) {
+    return "segment-review-pending";
+  }
+  const trigger = await findSegmentTrigger(input.homeDir, input.segment);
+  if (trigger === null) return "trigger-missing";
+  if (!isTerminalTrigger(trigger)) return "trigger-not-terminal";
+
+  let snapshot = input.reviewSnapshots.get(input.segment.projectKey);
+  if (snapshot === undefined) {
+    snapshot = readEvolutionReviewSnapshot({
+      homeDir: input.homeDir,
+      projectKey: input.segment.projectKey,
+    });
+    input.reviewSnapshots.set(input.segment.projectKey, snapshot);
+  }
+  return hasPendingDerivedReview(await snapshot, input.segment) ? "derived-review-pending" : null;
+}
+
+async function findSegmentTrigger(
+  homeDir: string,
+  segment: SessionEvidenceSegmentV1,
+): Promise<SegmentEvolutionTriggerRecord | null> {
+  const matches = (
+    await listSegmentEvolutionTriggers({
+      homeDir,
+      projectKey: segment.projectKey,
+    })
+  ).filter(
+    (trigger) => trigger.segmentId === segment.id && trigger.sessionKey === segment.sessionKey,
+  );
+  return matches.length === 1 ? (matches[0] ?? null) : null;
+}
+
+function isTerminalTrigger(trigger: SegmentEvolutionTriggerRecord): boolean {
+  return trigger.status === "consumed" || trigger.status === "skipped";
+}
+
+function hasPendingDerivedReview(
+  snapshot: EvolutionReviewSnapshot,
+  segment: SessionEvidenceSegmentV1,
+): boolean {
+  const runId = createStableId("segment-run", [segment.projectKey, segment.sessionKey, segment.id]);
+  if (
+    snapshot.knowledgeRecords.some(
+      (record) =>
+        record.provenance.runId === runId &&
+        !["auto-accepted", "accepted", "rejected", "deprecated", "superseded", "revoked"].includes(
+          record.reviewState,
+        ),
+    )
+  ) {
+    return true;
+  }
+  if (
+    snapshot.evosCases.some(
+      (record) =>
+        record.provenance.runId === runId &&
+        !["auto-accepted", "accepted", "rejected", "deprecated", "superseded", "revoked"].includes(
+          record.reviewState,
+        ),
+    )
+  ) {
+    return true;
+  }
+  if (
+    snapshot.repoProposals.some(
+      (proposal) =>
+        proposal.provenance.runId === runId &&
+        proposal.reviewState !== "rejected" &&
+        proposal.reviewState !== "applied",
+    )
+  ) {
+    return true;
+  }
+  return snapshot.reviewCandidates.some(
+    (candidate) =>
+      candidate.runId === runId &&
+      candidate.reviewState !== "accepted" &&
+      candidate.reviewState !== "rejected",
+  );
+}
+
+function createPurgedHistoricalSegment(
+  segment: SessionEvidenceSegmentV1,
+  now: string,
+): SessionEvidenceSegmentV1 {
+  const retention = segment.retention;
+  if (retention === undefined || retention.rawState !== "available") {
+    throw new Error("Historical Session Evidence raw body is not available for purge.");
+  }
+  return {
+    ...segment,
+    retention: {
+      ...retention,
+      rawState: "purged",
+      rawPurgedAt: now,
+    },
+    rawExcerpt: {
+      ...segment.rawExcerpt,
+      stored: false,
+      content: "",
+      byteLength: 0,
+      sha256: sha256Hex(""),
+    },
+    privacy: {
+      ...segment.privacy,
+      rawPromptStored: false,
+      rawOutputStored: false,
+      sourceContentStored: false,
+    },
+    lifecycle: {
+      ...segment.lifecycle,
+      status: "raw-expired",
+    },
+  };
+}