@evo-dev/core 0.0.1-alpha.2 → 0.0.1-alpha.20

package/src/evolution/knowledge/review.ts

@@ -0,0 +1,446 @@
+import { detectSessionMemorySensitivity } from "../evidence/session-memory/sensitivity.ts";
+import {
+  type OkfKnowledgeChangeCandidateV1,
+  readOkfKnowledgeChangeCandidate,
+  replaceOkfKnowledgeChangeCandidate,
+  withOkfKnowledgeChangeLock,
+} from "./change-store.ts";
+import {
+  type OkfKnowledgeChangeState,
+  createOkfKnowledgeRevision,
+  createOkfKnowledgeRuntimeProjectionFromConcept,
+} from "./changes.ts";
+import {
+  type OkfKnowledgeActivationResult,
+  type OkfKnowledgePlan,
+  activateOkfKnowledgePlan,
+  listOkfKnowledgeConcepts,
+  readOkfKnowledgeConcept,
+  revokeOkfKnowledgeConcept,
+  supersedeOkfKnowledgeConcept,
+} from "./index.ts";
+
+export type OkfKnowledgeChangeReviewDecision = "accept" | "reject" | "defer";
+
+export interface OkfKnowledgeChangeDecisionPreview {
+  changeId: string;
+  operation: OkfKnowledgeChangeCandidateV1["operation"];
+  currentState: OkfKnowledgeChangeState;
+  decision: OkfKnowledgeChangeReviewDecision;
+  baseRevision: string | null;
+  candidateRevision: string;
+  runtimeFields: string[];
+  willMutateActiveKnowledge: boolean;
+}
+
+export interface OkfKnowledgeChangeDecisionResult extends OkfKnowledgeChangeDecisionPreview {
+  state: OkfKnowledgeChangeState;
+  activation: OkfKnowledgeActivationResult | null;
+  conceptPaths: string[];
+}
+
+export async function previewOkfKnowledgeChangeDecision(input: {
+  homeDir: string;
+  changeId: string;
+  decision: OkfKnowledgeChangeReviewDecision;
+  expectedState: OkfKnowledgeChangeState;
+  expectedBaseRevision: string | null;
+}): Promise<OkfKnowledgeChangeDecisionPreview> {
+  const { change } = await readOkfKnowledgeChangeCandidate({
+    homeDir: input.homeDir,
+    changeId: input.changeId,
+  });
+  await assertReviewPreconditions({
+    homeDir: input.homeDir,
+    change,
+    expectedState: input.expectedState,
+    expectedBaseRevision: input.expectedBaseRevision,
+  });
+  return toPreview(change, input.decision);
+}
+
+export async function decideOkfKnowledgeChange(input: {
+  homeDir: string;
+  changeId: string;
+  decision: OkfKnowledgeChangeReviewDecision;
+  expectedState: OkfKnowledgeChangeState;
+  expectedBaseRevision: string | null;
+  reason?: string | null;
+  now?: string | Date;
+}): Promise<OkfKnowledgeChangeDecisionResult> {
+  const initial = await readOkfKnowledgeChangeCandidate({
+    homeDir: input.homeDir,
+    changeId: input.changeId,
+  });
+  return await withOkfKnowledgeChangeLock({
+    homeDir: input.homeDir,
+    projectKey: initial.change.projectKey,
+    stableKey: initial.change.stableKey,
+    conceptId: initial.change.base?.conceptId ?? null,
+    run: async () => {
+      const { change } = await readOkfKnowledgeChangeCandidate({
+        homeDir: input.homeDir,
+        changeId: input.changeId,
+        projectKey: initial.change.projectKey,
+      });
+      assertReviewInputPreconditions({
+        change,
+        expectedState: input.expectedState,
+        expectedBaseRevision: input.expectedBaseRevision,
+      });
+      if (change.state === "accepted" && input.decision !== "accept") {
+        throw new Error(
+          "Knowledge change state conflict: an accepted change can only resume acceptance.",
+        );
+      }
+      if (change.state === "accepted" && input.decision === "accept") {
+        const recovered = await readAlreadyAppliedKnowledgeChange({
+          homeDir: input.homeDir,
+          change,
+        });
+        if (recovered !== null) {
+          const completed: OkfKnowledgeChangeCandidateV1 = {
+            ...change,
+            state: "applied",
+            updatedAt: resolveNow(input.now),
+          };
+          await replaceOkfKnowledgeChangeCandidate({
+            homeDir: input.homeDir,
+            previous: change,
+            next: completed,
+            reason: input.reason ?? null,
+          });
+          return {
+            ...toPreview(change, input.decision),
+            state: "applied",
+            activation: null,
+            conceptPaths: recovered.conceptPaths,
+          };
+        }
+      }
+      try {
+        await assertReviewPreconditions({
+          homeDir: input.homeDir,
+          change,
+          expectedState: input.expectedState,
+          expectedBaseRevision: input.expectedBaseRevision,
+        });
+      } catch (error) {
+        if (isBaseRevisionConflict(error) && change.state !== "superseded") {
+          const superseded = {
+            ...change,
+            state: "superseded" as const,
+            updatedAt: resolveNow(input.now),
+          };
+          await replaceOkfKnowledgeChangeCandidate({
+            homeDir: input.homeDir,
+            previous: change,
+            next: superseded,
+            reason: "Base revision changed before review.",
+          });
+        }
+        throw error;
+      }
+
+      const reason = normalizeDecisionReason(input.reason);
+      const decidedAt = resolveNow(input.now);
+      const decisionState =
+        input.decision === "accept"
+          ? ("accepted" as const)
+          : input.decision === "reject"
+            ? ("rejected" as const)
+            : ("deferred" as const);
+      const decided =
+        change.state === "accepted" && input.decision === "accept"
+          ? change
+          : {
+              ...change,
+              state: decisionState,
+              decision: {
+                state: decisionState,
+                reason,
+                decidedAt,
+              },
+              updatedAt: decidedAt,
+            };
+      if (decided !== change) {
+        await replaceOkfKnowledgeChangeCandidate({
+          homeDir: input.homeDir,
+          previous: change,
+          next: decided,
+          reason,
+        });
+      }
+      const preview = toPreview(change, input.decision);
+      if (input.decision !== "accept") {
+        return {
+          ...preview,
+          state: decided.state,
+          activation: null,
+          conceptPaths: [],
+        };
+      }
+
+      const applied = await applyAcceptedChange({
+        homeDir: input.homeDir,
+        change: decided,
+        now: decidedAt,
+        reason,
+      });
+      const current = (
+        await readOkfKnowledgeChangeCandidate({
+          homeDir: input.homeDir,
+          changeId: input.changeId,
+          projectKey: change.projectKey,
+        })
+      ).change;
+      const completed: OkfKnowledgeChangeCandidateV1 = {
+        ...current,
+        state: "applied",
+        updatedAt: resolveNow(input.now),
+      };
+      await replaceOkfKnowledgeChangeCandidate({
+        homeDir: input.homeDir,
+        previous: current,
+        next: completed,
+        reason,
+      });
+      return {
+        ...preview,
+        state: "applied",
+        activation: applied.activation,
+        conceptPaths: applied.conceptPaths,
+      };
+    },
+  });
+}
+
+async function assertReviewPreconditions(input: {
+  homeDir: string;
+  change: OkfKnowledgeChangeCandidateV1;
+  expectedState: OkfKnowledgeChangeState;
+  expectedBaseRevision: string | null;
+}): Promise<void> {
+  assertReviewInputPreconditions(input);
+  if (input.change.base === null) {
+    const concepts = await listOkfKnowledgeConcepts({ homeDir: input.homeDir });
+    if (
+      concepts.some(
+        (concept) =>
+          concept.stableKey === input.change.stableKey ||
+          concept.id === conceptIdFromTargetPath(input.change.targetPath),
+      )
+    ) {
+      throw createBaseRevisionConflict(
+        "Knowledge change base revision conflict: a concept now uses this stable key or target path.",
+      );
+    }
+    return;
+  }
+  const current = await readOkfKnowledgeConcept({
+    homeDir: input.homeDir,
+    conceptId: input.change.base.conceptId,
+  });
+  const currentRevision = createOkfKnowledgeRevision(
+    createOkfKnowledgeRuntimeProjectionFromConcept(current),
+  );
+  if (currentRevision !== input.change.base.revision) {
+    throw createBaseRevisionConflict(
+      `Knowledge change base revision conflict: expected ${input.change.base.revision}, found ${currentRevision}.`,
+    );
+  }
+}
+
+function assertReviewInputPreconditions(input: {
+  change: OkfKnowledgeChangeCandidateV1;
+  expectedState: OkfKnowledgeChangeState;
+  expectedBaseRevision: string | null;
+}): void {
+  if (input.change.state !== input.expectedState) {
+    throw new Error(
+      `Knowledge change state conflict: expected ${input.expectedState}, found ${input.change.state}.`,
+    );
+  }
+  const storedBaseRevision = input.change.base?.revision ?? null;
+  if (storedBaseRevision !== input.expectedBaseRevision) {
+    throw new Error(
+      `Knowledge change base revision input does not match candidate: expected ${storedBaseRevision ?? "none"}.`,
+    );
+  }
+}
+
+async function readAlreadyAppliedKnowledgeChange(input: {
+  homeDir: string;
+  change: OkfKnowledgeChangeCandidateV1;
+}): Promise<{ conceptPaths: string[] } | null> {
+  if (input.change.operation === "supersede") {
+    if (input.change.base === null) return null;
+    const replacement = await readConceptIfPresent(
+      input.homeDir,
+      conceptIdFromTargetPath(input.change.targetPath),
+    );
+    const previous = await readConceptIfPresent(input.homeDir, input.change.base.conceptId);
+    if (
+      replacement === null ||
+      previous === null ||
+      replacement.stableKey !== input.change.stableKey ||
+      previous.lifecycle.status !== "superseded" ||
+      previous.lifecycle.supersededBy !== replacement.id ||
+      !replacement.lifecycle.supersedes.includes(previous.id)
+    ) {
+      return null;
+    }
+    return { conceptPaths: [previous.path, replacement.path] };
+  }
+
+  const conceptId =
+    input.change.operation === "create"
+      ? conceptIdFromTargetPath(input.change.targetPath)
+      : input.change.base?.conceptId;
+  if (conceptId === undefined) return null;
+  const concept = await readConceptIfPresent(input.homeDir, conceptId);
+  if (concept === null || concept.stableKey !== input.change.stableKey) return null;
+  const revision = createOkfKnowledgeRevision(
+    createOkfKnowledgeRuntimeProjectionFromConcept(concept),
+  );
+  return revision === input.change.candidate.revision ? { conceptPaths: [concept.path] } : null;
+}
+
+async function readConceptIfPresent(
+  homeDir: string,
+  conceptId: string,
+): Promise<Awaited<ReturnType<typeof readOkfKnowledgeConcept>> | null> {
+  try {
+    return await readOkfKnowledgeConcept({ homeDir, conceptId });
+  } catch (error) {
+    if (error instanceof Error && /not found/iu.test(error.message)) return null;
+    throw error;
+  }
+}
+
+function conceptIdFromTargetPath(targetPath: string): string {
+  return targetPath.replace(/^\/+/u, "").replace(/\.md$/u, "");
+}
+
+function createBaseRevisionConflict(message: string): Error {
+  return Object.assign(new Error(message), {
+    code: "KNOWLEDGE_BASE_REVISION_CONFLICT",
+  });
+}
+
+async function applyAcceptedChange(input: {
+  homeDir: string;
+  change: OkfKnowledgeChangeCandidateV1;
+  now: string;
+  reason: string | null;
+}): Promise<{ activation: OkfKnowledgeActivationResult | null; conceptPaths: string[] }> {
+  if (input.change.operation === "revoke") {
+    if (input.change.base === null) throw new Error("Knowledge revoke requires an active base.");
+    const result = await revokeOkfKnowledgeConcept({
+      homeDir: input.homeDir,
+      conceptId: input.change.base.conceptId,
+      reason: input.reason ?? input.change.candidate.planCandidate.decisionReason.slice(0, 500),
+      now: input.now,
+    });
+    return { activation: null, conceptPaths: result.conceptPaths };
+  }
+
+  const planCandidate = {
+    ...input.change.candidate.planCandidate,
+    decision: input.change.operation === "update" ? ("update" as const) : ("create" as const),
+    reviewState: "accepted" as const,
+    targetPath:
+      input.change.operation === "update" && input.change.base !== null
+        ? input.change.base.sourceLink.replace(/^\/+/u, "")
+        : input.change.targetPath,
+  };
+  const plan: OkfKnowledgePlan = {
+    schemaVersion: 1,
+    kind: "evodev-knowledge-plan",
+    projectKey: input.change.projectKey,
+    runId: input.change.runId,
+    createdAt: input.now,
+    evidenceWindowId: input.change.provenance.evidenceWindowId,
+    summary: `Apply reviewed knowledge change ${input.change.id}.`,
+    evidenceRefs: input.change.provenance.evidenceRefs.map((id) => ({
+      id,
+      kind: "knowledge-change-evidence",
+      source: `knowledge-change:${input.change.id}`,
+      rawContentStored: false,
+      externalContentCopied: false,
+    })),
+    evoEvalSets: input.change.candidate.evalSets,
+    candidates: [planCandidate],
+    droppedSignals: [],
+    conflicts: [],
+    privacyCheck: planCandidate.privacyCheck,
+  };
+  const activation = await activateOkfKnowledgePlan({
+    homeDir: input.homeDir,
+    plan,
+    overwrite: input.change.operation === "update",
+    reviewedChangeId: input.change.id,
+  });
+  const conceptPaths = [...activation.conceptPaths];
+  if (input.change.operation === "supersede") {
+    if (input.change.base === null) throw new Error("Knowledge supersede requires an active base.");
+    const replacementId = input.change.targetPath.replace(/^\/+/u, "").replace(/\.md$/u, "");
+    const lifecycle = await supersedeOkfKnowledgeConcept({
+      homeDir: input.homeDir,
+      oldConceptId: input.change.base.conceptId,
+      newConceptId: replacementId,
+      now: input.now,
+    });
+    conceptPaths.push(...lifecycle.conceptPaths);
+  }
+  return { activation, conceptPaths: [...new Set(conceptPaths)] };
+}
+
+function toPreview(
+  change: OkfKnowledgeChangeCandidateV1,
+  decision: OkfKnowledgeChangeReviewDecision,
+): OkfKnowledgeChangeDecisionPreview {
+  return {
+    changeId: change.id,
+    operation: change.operation,
+    currentState: change.state,
+    decision,
+    baseRevision: change.base?.revision ?? null,
+    candidateRevision: change.candidate.revision,
+    runtimeFields: change.diff.runtimeFields,
+    willMutateActiveKnowledge: decision === "accept",
+  };
+}
+
+function normalizeDecisionReason(value: string | null | undefined): string | null {
+  if (value === undefined || value === null || value.trim() === "") return null;
+  const reason = [...value]
+    .filter((character) => {
+      const code = character.charCodeAt(0);
+      return code === 9 || code === 10 || code === 13 || (code >= 32 && code !== 127);
+    })
+    .join("")
+    .trim();
+  if (reason.length > 500)
+    throw new Error("Knowledge review reason must be 500 characters or less.");
+  if (detectSessionMemorySensitivity(reason).classification === "credential") {
+    throw new Error("Knowledge review reason contains a credential.");
+  }
+  return reason;
+}
+
+function resolveNow(value: string | Date | undefined): string {
+  const date =
+    value instanceof Date ? value : typeof value === "string" ? new Date(value) : new Date();
+  if (!Number.isFinite(date.getTime())) throw new Error("Invalid knowledge review timestamp.");
+  return date.toISOString();
+}
+
+function isBaseRevisionConflict(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === "KNOWLEDGE_BASE_REVISION_CONFLICT"
+  );
+}

package/src/evolution/knowledge/support.ts

@@ -0,0 +1,135 @@
+export type OkfKnowledgeSupportKind =
+  | "user-declaration"
+  | "repo-policy"
+  | "state-observation"
+  | "verified-outcome"
+  | "semantic-inference";
+
+export interface OkfKnowledgeSupportRef {
+  id: string;
+  kind: OkfKnowledgeSupportKind;
+  sourceRefId: string;
+  subjectFingerprint: string | null;
+  observedAt: string;
+}
+
+export type OkfKnowledgeDelivery = "inline" | "reference" | "blocked";
+export type OkfKnowledgeSourceStatus = "current" | "changed" | "unknown";
+
+export interface OkfKnowledgeRuntimeEligibility {
+  delivery: OkfKnowledgeDelivery;
+  freshness: "verified" | "review-due" | "unknown" | "stale";
+  reason: string;
+}
+
+export function resolveOkfKnowledgeRuntimeEligibility(input: {
+  reviewState: string;
+  lifecycle: {
+    status: string;
+    reviewAfter: string;
+    staleAfter: string;
+  };
+  supportRef: OkfKnowledgeSupportRef | null;
+  now?: string | Date;
+  sourceStatus?: OkfKnowledgeSourceStatus;
+  verifiedContradiction?: boolean;
+}): OkfKnowledgeRuntimeEligibility {
+  const now = normalizeNow(input.now);
+  if (
+    input.verifiedContradiction === true ||
+    input.lifecycle.status === "stale" ||
+    input.lifecycle.status === "deprecated" ||
+    input.lifecycle.status === "revoked" ||
+    input.lifecycle.status === "superseded" ||
+    input.reviewState === "stale" ||
+    input.reviewState === "deprecated" ||
+    input.reviewState === "revoked" ||
+    input.reviewState === "superseded" ||
+    isDue(input.lifecycle.staleAfter, now)
+  ) {
+    return {
+      delivery: "blocked",
+      freshness: "stale",
+      reason:
+        input.verifiedContradiction === true
+          ? "Verified evidence contradicts the active claim."
+          : "Lifecycle state excludes this knowledge from runtime context.",
+    };
+  }
+  if (input.reviewState !== "accepted" && input.reviewState !== "auto-accepted") {
+    return {
+      delivery: "blocked",
+      freshness: "unknown",
+      reason: "Knowledge has not passed an active-compatible review state.",
+    };
+  }
+  if (input.sourceStatus === "changed") {
+    return {
+      delivery: "blocked",
+      freshness: "review-due",
+      reason: "The supporting source changed and requires revalidation.",
+    };
+  }
+  if (isDue(input.lifecycle.reviewAfter, now)) {
+    return {
+      delivery: "reference",
+      freshness: "review-due",
+      reason: `Review was due at ${input.lifecycle.reviewAfter}.`,
+    };
+  }
+  if (input.supportRef === null) {
+    return {
+      delivery: "reference",
+      freshness: "unknown",
+      reason: "Legacy knowledge has no structured support reference.",
+    };
+  }
+  if (input.supportRef.kind === "semantic-inference") {
+    if (input.reviewState === "accepted") {
+      return {
+        delivery: "inline",
+        freshness: "verified",
+        reason: "A human-accepted inference is runtime-eligible as an explicit decision.",
+      };
+    }
+    return {
+      delivery: "reference",
+      freshness: "unknown",
+      reason: "Model-inferred knowledge remains on-demand until supported by a direct source.",
+    };
+  }
+  if (
+    (input.supportRef.kind === "repo-policy" || input.supportRef.kind === "state-observation") &&
+    input.sourceStatus !== "current"
+  ) {
+    return {
+      delivery: "reference",
+      freshness: "unknown",
+      reason: "The supporting repository source has not been revalidated for this query.",
+    };
+  }
+  return {
+    delivery: "inline",
+    freshness: "verified",
+    reason: `Runtime-eligible through ${input.supportRef.kind}.`,
+  };
+}
+
+export function isDirectKnowledgeSupport(
+  supportRef: OkfKnowledgeSupportRef | null | undefined,
+): boolean {
+  return (
+    supportRef !== undefined && supportRef !== null && supportRef.kind !== "semantic-inference"
+  );
+}
+
+function normalizeNow(value: string | Date | undefined): Date {
+  if (value instanceof Date && Number.isFinite(value.getTime())) return value;
+  if (typeof value === "string" && Number.isFinite(Date.parse(value))) return new Date(value);
+  return new Date();
+}
+
+function isDue(value: string, now: Date): boolean {
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) && timestamp <= now.getTime();
+}

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,
+  };
+}