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

package/package.json

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

package/src/evolution/candidates/index.ts

@@ -1,5 +1,6 @@
-import { readFile, readdir } from "node:fs/promises";
-import { join } from "node:path";
+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";
@@ -7,6 +8,7 @@ import type {
   EvolutionEvosCase,
   EvolutionEvosCaseQueryResult,
   EvolutionKnowledgeRecord,
+  EvolutionKnowledgeReviewHistoryRecord,
   EvolutionRepoProposal,
   EvolutionReviewCandidate,
   EvolutionReviewSnapshot,
@@ -14,6 +16,8 @@ import type {
   EvolutionTriggerRecord,
 } from "../schema.ts";
 import {
+  REVIEW_STATES,
+  hasConcreteRepoProposalChanges,
   listDirectoryNames,
   parseEvosCase,
   parseKnowledgeRecord,
@@ -22,10 +26,51 @@ import {
   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;
@@ -113,6 +158,37 @@ export async function listEvolutionKnowledgeRecords(input: {
   ).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;
@@ -186,50 +262,244 @@ export async function updateEvolutionKnowledgeReviewState(input: {
   knowledgeId: string;
   projectKey?: string;
   reviewState: "accepted" | "rejected" | "deferred";
-}): Promise<{ path: string; record: EvolutionKnowledgeRecord }> {
-  const record = await readEvolutionKnowledgeRecordById(input);
-  const next: EvolutionKnowledgeRecord = {
-    ...record,
-    reviewState: input.reviewState,
-    authority: input.reviewState === "accepted" ? "reviewed" : "contextual",
-    runtime: {
-      ...record.runtime,
-      canLoad: input.reviewState === "accepted",
-      hardBlocking: false,
+  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 };
     },
-  };
-  validateEvolutionKnowledgeRecord(next);
-  const paths = resolveEvolutionPaths({
-    homeDir: input.homeDir,
-    projectKey: next.projectKey,
-    runId: "review",
-  });
-  const path = join(paths.knowledgeRecordsDir, `${next.id}.json`);
-  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: new Date().toISOString(),
-      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,
-      })),
+}
+
+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 };
     },
-    { overwrite: true },
   );
-  return { path, record: next };
+}
+
+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/evidence/session-memory/index.ts

@@ -1,4 +1,5 @@
 export * from "./paths.ts";
 export * from "./policy.ts";
+export * from "./storage.ts";
 export * from "./types.ts";
 export * from "./updater.ts";

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

@@ -144,8 +144,8 @@ export async function createSegment(input: {
       externalUploadAllowed: false,
     },
     lifecycle: {
-      status: "pending-review",
-      reviewState: "unreviewed",
+      status: "captured",
+      reviewState: "not-required",
       consumedByBatchIds: [],
     },
   };

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

@@ -1,7 +1,9 @@
-import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
+import { appendFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { resolveEvoDevPaths } from "../../../config/paths.ts";
 import { isNotFoundError } from "../../../utils/index.ts";
 import { SENSITIVE_TEXT_PATTERN } from "./constants.ts";
+import { resolveSessionMemoryPaths } from "./paths.ts";
 import type {
   SessionEvidenceSegmentV1,
   SessionMemoryCursorV1,
@@ -11,6 +13,79 @@ import type {
   SessionMemoryStateV1,
 } from "./types.ts";
 
+export class SessionMemoryEvidenceError extends Error {
+  readonly code: "not-found" | "invalid";
+
+  constructor(code: "not-found" | "invalid", message: string) {
+    super(message);
+    this.name = "SessionMemoryEvidenceError";
+    this.code = code;
+  }
+}
+
+export async function listSessionEvidenceSegments(input: {
+  homeDir: string;
+  projectKey?: string;
+}): Promise<SessionEvidenceSegmentV1[]> {
+  const rootDir = join(resolveEvoDevPaths(input.homeDir).stateDir, "session-memory");
+  const projectDirs =
+    input.projectKey === undefined ? await listDirectoryNames(rootDir) : [input.projectKey];
+  const segments: SessionEvidenceSegmentV1[] = [];
+  for (const projectKey of projectDirs) {
+    const paths = resolveSessionMemoryPaths({
+      homeDir: input.homeDir,
+      projectKey,
+      sessionKey: "list",
+    });
+    for (const sessionKey of await listDirectoryNames(paths.projectDir)) {
+      const sessionPaths = resolveSessionMemoryPaths({
+        homeDir: input.homeDir,
+        projectKey,
+        sessionKey,
+      });
+      for (const entry of await listJsonFiles(sessionPaths.segmentsDir)) {
+        try {
+          segments.push(parseSessionEvidenceSegment(JSON.parse(await readFile(entry, "utf8"))));
+        } catch {
+          // Invalid local evidence is omitted from listings and remains available for diagnostics.
+        }
+      }
+    }
+  }
+  return segments.sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+}
+
+export async function readSessionEvidenceSegment(input: {
+  homeDir: string;
+  projectKey: string;
+  sessionKey: string;
+  segmentId: string;
+}): Promise<SessionEvidenceSegmentV1> {
+  const paths = resolveSessionMemoryPaths(input);
+  try {
+    const segment = parseSessionEvidenceSegment(
+      JSON.parse(await readFile(paths.segmentPath(input.segmentId), "utf8")) as unknown,
+    );
+    if (
+      segment.id !== input.segmentId ||
+      segment.projectKey !== input.projectKey ||
+      segment.sessionKey !== input.sessionKey
+    ) {
+      throw new SessionMemoryEvidenceError(
+        "invalid",
+        "Session evidence identity does not match its storage path.",
+      );
+    }
+    return segment;
+  } catch (error) {
+    if (error instanceof SessionMemoryEvidenceError) throw error;
+    if (isNotFoundError(error)) {
+      throw new SessionMemoryEvidenceError("not-found", "Session evidence segment was not found.");
+    }
+    throw new SessionMemoryEvidenceError("invalid", "Session evidence segment is invalid.");
+  }
+}
+
 export async function readSessionState(path: string): Promise<SessionMemoryStateV1 | null> {
   try {
     return JSON.parse(await readFile(path, "utf8")) as SessionMemoryStateV1;
@@ -143,3 +218,49 @@ function isSessionIndexSegment(value: unknown): value is SessionMemoryIndexSegme
     typeof item.reviewState === "string"
   );
 }
+
+function parseSessionEvidenceSegment(value: unknown): SessionEvidenceSegmentV1 {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new SessionMemoryEvidenceError("invalid", "Session evidence must be an object.");
+  }
+  const segment = value as Partial<SessionEvidenceSegmentV1>;
+  if (
+    segment.schemaVersion !== 1 ||
+    segment.kind !== "session-evidence-segment" ||
+    typeof segment.id !== "string" ||
+    typeof segment.projectKey !== "string" ||
+    typeof segment.sessionKey !== "string" ||
+    typeof segment.createdAt !== "string" ||
+    typeof segment.normalized !== "object" ||
+    segment.normalized === null ||
+    typeof segment.rawExcerpt !== "object" ||
+    segment.rawExcerpt === null
+  ) {
+    throw new SessionMemoryEvidenceError("invalid", "Session evidence fields are invalid.");
+  }
+  return segment as SessionEvidenceSegmentV1;
+}
+
+async function listDirectoryNames(path: string): Promise<string[]> {
+  try {
+    return (await readdir(path, { withFileTypes: true }))
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort();
+  } catch (error) {
+    if (isNotFoundError(error)) return [];
+    throw error;
+  }
+}
+
+async function listJsonFiles(path: string): Promise<string[]> {
+  try {
+    return (await readdir(path, { withFileTypes: true }))
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+      .map((entry) => join(path, entry.name))
+      .sort();
+  } catch (error) {
+    if (isNotFoundError(error)) return [];
+    throw error;
+  }
+}

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

@@ -133,8 +133,8 @@ export interface SessionEvidenceSegmentV1 {
     externalUploadAllowed: false;
   };
   lifecycle: {
-    status: "pending-review" | "reviewed" | "distilled" | "ignored" | "deleted";
-    reviewState: "unreviewed" | "accepted" | "rejected" | "deferred";
+    status: "captured" | "pending-review" | "reviewed" | "distilled" | "ignored" | "deleted";
+    reviewState: "not-required" | "unreviewed" | "accepted" | "rejected" | "deferred";
     consumedByBatchIds: string[];
   };
 }
@@ -203,5 +203,5 @@ export interface SessionMemoryIndexSegment {
   reason: SessionMemorySegmentReason;
   strength: SessionMemorySignalStrength;
   createdAt: string;
-  reviewState: "unreviewed" | "accepted" | "rejected" | "deferred";
+  reviewState: "not-required" | "unreviewed" | "accepted" | "rejected" | "deferred";
 }

package/src/evolution/index.ts

@@ -6,7 +6,11 @@ export * from "./candidates/index.ts";
 export * from "./triggers/index.ts";
 export * from "./formatters.ts";
 export {
+  createEvolutionRepoProposal,
+  hasConcreteRepoProposalChanges,
+  sanitizeProposedChange,
   validateEvolutionDistillationBatch,
   validateEvolutionEvidenceWindow,
   validateEvolutionKnowledgeRecord,
+  validateEvolutionRepoProposal,
 } from "./shared.ts";