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

package/src/evolution/schema.ts

@@ -0,0 +1,639 @@
+import type { SessionEvidenceSegmentV1 } from "./evidence/session-memory/types.ts";
+import type { OkfKnowledgeActivationResult, OkfKnowledgePlan } from "./knowledge/index.ts";
+
+export type EvolutionEvidenceSourceKind =
+  | "evodev-execution-event"
+  | "team-agent-trace"
+  | "session-trace"
+  | "session-memory-segment"
+  | "verification"
+  | "review-summary"
+  | "user-feedback"
+  | "code-agent-trace-ref";
+
+export type EvolutionEvidenceEventKind =
+  | "trace"
+  | "tool-call"
+  | "skill-call"
+  | "subagent"
+  | "verification"
+  | "review"
+  | "user-feedback"
+  | "error"
+  | "run-state";
+
+export type EvolutionNormalizedEventType =
+  | "SessionStart"
+  | "UserPromptSubmit"
+  | "UserPromptExpansion"
+  | "PreToolUse"
+  | "PermissionRequest"
+  | "PostToolUse"
+  | "PostToolUseFailure"
+  | "PostToolBatch"
+  | "PermissionDenied"
+  | "SubagentStart"
+  | "Stop"
+  | "StopFailure"
+  | "TeammateIdle"
+  | "SubagentStop"
+  | "TaskCreated"
+  | "TaskCompleted"
+  | "PreCompact"
+  | "PostCompact"
+  | "SessionEnd"
+  | "ConfigChange"
+  | "CwdChanged"
+  | "FileChanged"
+  | "WorktreeCreate"
+  | "WorktreeRemove"
+  | "unknown";
+
+export type EvolutionTriggerStrength = "none" | "conditional" | "strong";
+export type EvolutionTriggerReason =
+  | "none"
+  | "turn-completed"
+  | "task-completed"
+  | "session-ended"
+  | "role-completed"
+  | "stop-failure"
+  | "tool-failure"
+  | "permission-denied"
+  | "explicit-command"
+  | "failure-signal";
+
+export type EvolutionEpisodeKind = "session" | "turn" | "task" | "role";
+export type EvolutionEpisodeStatus = "open" | "closed" | "failed";
+export type EvolutionTriggerStatus = "pending" | "processing" | "consumed" | "failed" | "skipped";
+export type SegmentEvolutionTriggerReason =
+  | "session-memory-init"
+  | "session-memory-threshold"
+  | "intent-refinement"
+  | "user-interruption"
+  | "failure-signal"
+  | "permission-denied"
+  | "verification-after-fix"
+  | "explicit-memory-intent"
+  | "historical-import";
+export type SegmentEvolutionTriggerStrength = "normal" | "strong";
+
+export type EvolutionKnowledgeKind =
+  | "run-summary"
+  | "lesson"
+  | "rule"
+  | "workflow-hint"
+  | "skill-gap"
+  | "role-note"
+  | "verification-pattern";
+
+export type EvolutionReviewState =
+  | "auto-accepted"
+  | "auto-stored/unreviewed"
+  | "needs-human"
+  | "accepted"
+  | "rejected"
+  | "deferred"
+  | "stale"
+  | "deprecated"
+  | "superseded"
+  | "revoked";
+
+export type EvolutionAuthority = "contextual" | "reviewed";
+export type EvolutionConfidence = "low" | "medium" | "high";
+
+export type EvolutionProposalKind =
+  | "skill"
+  | "rule"
+  | "role-agent"
+  | "team"
+  | "ci"
+  | "test"
+  | "docs"
+  | "engineering-practice";
+
+export type EvolutionImprovementEvalStatus =
+  | "not-requested"
+  | "awaiting-eval"
+  | "evaluating"
+  | "effective"
+  | "ineffective"
+  | "inconclusive";
+
+export interface EvolutionImprovementEvalResult {
+  targetImproved: boolean | null;
+  hardRegression: boolean | null;
+  summary: string;
+  assertions: Array<{
+    label: string;
+    status: "pass" | "fail" | "unknown";
+  }>;
+  evaluatedBy: "local-code-agent" | "local-eval-orchestrator";
+  metrics: {
+    durationMs: number;
+    modelCalls: number;
+    inputTokens: number | null;
+    outputTokens: number | null;
+    toolCalls: number | null;
+  };
+  retention: {
+    metadataOnly: true;
+    replayInputStored: false;
+    replayOutputStored: false;
+  };
+}
+
+export interface EvolutionImprovementEval {
+  recommended: boolean;
+  requested: boolean;
+  status: EvolutionImprovementEvalStatus;
+  requestedAt: string | null;
+  evaluatedAt: string | null;
+  evidenceRef: string | null;
+  result: EvolutionImprovementEvalResult | null;
+}
+
+export interface EvolutionPrivacyFields {
+  classification: "local-private";
+  rawPromptsStored: false;
+  rawLogsStored: false;
+  sourceDumpsStored: false;
+  rawCommandOutputStored: false;
+  secretsStored: false;
+  internalLinksStored: boolean;
+}
+
+export interface EvolutionEvidenceWindow {
+  schemaVersion: 1;
+  id: string;
+  kind: "evidence-window";
+  projectKey: string;
+  runId: string;
+  taskId: string | null;
+  createdAt: string;
+  sourceRefs: EvolutionEvidenceSourceRef[];
+  events: EvolutionEvidenceEvent[];
+  episodes: EvolutionEpisode[];
+  triggerPolicy: EvolutionTriggerPolicy;
+  privacy: EvolutionPrivacyFields;
+}
+
+export interface EvolutionEvidenceSourceRef {
+  id: string;
+  kind: EvolutionEvidenceSourceKind;
+  path: string;
+  roleId: string | null;
+  rawContentStored: false;
+  externalContentCopied: false;
+}
+
+export interface EvolutionEvidenceEvent {
+  id: string;
+  kind: EvolutionEvidenceEventKind;
+  eventType: EvolutionNormalizedEventType;
+  hookEventId: string | null;
+  occurredAt: string | null;
+  summary: string;
+  roleId: string | null;
+  taskId: string | null;
+  evidenceRef: string;
+  episodeIds: string[];
+  triggerStrength: EvolutionTriggerStrength;
+  triggerReason: EvolutionTriggerReason;
+  rawContentStored: false;
+}
+
+export interface EvolutionEpisode {
+  id: string;
+  kind: EvolutionEpisodeKind;
+  status: EvolutionEpisodeStatus;
+  roleId: string | null;
+  taskId: string | null;
+  startedAt: string | null;
+  endedAt: string | null;
+  eventIds: string[];
+  triggerStrength: EvolutionTriggerStrength;
+  triggerReason: EvolutionTriggerReason;
+  summary: string;
+  rawContentStored: false;
+}
+
+export interface EvolutionTriggerPolicy {
+  strongest: EvolutionTriggerStrength;
+  reasons: EvolutionTriggerReason[];
+  distillRecommended: boolean;
+  evidenceSignals: {
+    failures: number;
+    verifications: number;
+    roleLifecycle: number;
+    skillCalls: number;
+  };
+}
+
+export interface EvolutionTriggerRecord {
+  schemaVersion: 1;
+  id: string;
+  kind: "evolution-trigger";
+  projectKey: string;
+  runId: string;
+  roleId: string | null;
+  taskId: string | null;
+  eventType: EvolutionNormalizedEventType;
+  eventId: string | null;
+  evidenceRef: string | null;
+  summary: string;
+  triggerStrength: EvolutionTriggerStrength;
+  triggerReason: EvolutionTriggerReason;
+  status: EvolutionTriggerStatus;
+  attempts: number;
+  createdAt: string;
+  updatedAt: string;
+  processedBatchId: string | null;
+  lastError: string | null;
+  rawContentStored: false;
+  privacy: EvolutionPrivacyFields;
+}
+
+export interface SegmentEvolutionTriggerRecord {
+  schemaVersion: 1;
+  id: string;
+  kind: "segment-evolution-trigger";
+  projectKey: string;
+  sessionKey: string;
+  runId: string | null;
+  roleId: string | null;
+  segmentId: string;
+  segmentPath: string;
+  strength: SegmentEvolutionTriggerStrength;
+  reason: SegmentEvolutionTriggerReason;
+  summary: string;
+  status: EvolutionTriggerStatus;
+  attempts: number;
+  createdAt: string;
+  updatedAt: string;
+  processedBatchId: string | null;
+  lastError: string | null;
+  rawContentStored: false;
+}
+
+export interface EvolutionTriggerDecision {
+  eventType: EvolutionNormalizedEventType;
+  strength: EvolutionTriggerStrength;
+  reason: EvolutionTriggerReason;
+  shouldQueue: boolean;
+  summary: string;
+}
+
+export interface EvolutionKnowledgeRecord {
+  schemaVersion: 1;
+  id: string;
+  kind: EvolutionKnowledgeKind;
+  title: string;
+  projectKey: string;
+  summary: string;
+  body: string;
+  roleTags: string[];
+  tags: string[];
+  reviewState: EvolutionReviewState;
+  authority: EvolutionAuthority;
+  confidence: EvolutionConfidence;
+  provenance: {
+    runId: string;
+    taskId: string | null;
+    evidenceWindowId: string;
+    sourceRefs: string[];
+    createdAt: string;
+    createdBy: "evodev";
+    rawLogsStored: false;
+    rawPromptsStored: false;
+    sourceDumpsStored: false;
+    rawCommandOutputStored: false;
+  };
+  relations: {
+    relatedKnowledgeIds: string[];
+    evosCaseIds: string[];
+    proposalIds: string[];
+    supersedes: string[];
+  };
+  privacy: EvolutionPrivacyFields;
+  runtime: {
+    canLoad: boolean;
+    hardBlocking: false;
+  };
+}
+
+export interface EvolutionKnowledgeReviewHistoryRecord {
+  version: 1;
+  kind: "evolution-knowledge-review-state-changed";
+  knowledgeId: string;
+  projectKey: string;
+  roleTags: string[];
+  artifactCreatedAt: string;
+  previousReviewState: EvolutionReviewState;
+  nextReviewState: EvolutionReviewState;
+  changedAt: string;
+  metadataOnly: true;
+}
+
+export interface EvolutionEvosCase {
+  schemaVersion: 1;
+  id: string;
+  kind: "evos-case";
+  projectKey: string;
+  title: string;
+  roleTags: string[];
+  tags: string[];
+  reviewState: EvolutionReviewState;
+  confidence: EvolutionConfidence;
+  trigger: {
+    kind: "task-completion" | "plan-task-completion" | "session-completion" | "manual";
+    summary: string;
+  };
+  intervention: {
+    summary: string;
+    roleIds: string[];
+  };
+  result: {
+    summary: string;
+    verificationSignals: string[];
+  };
+  expectedFutureBehavior: string;
+  provenance: {
+    runId: string;
+    taskId: string | null;
+    evidenceWindowId: string;
+    sourceRefs: string[];
+    createdAt: string;
+    createdBy: "evodev";
+    rawLogsStored: false;
+    rawPromptsStored: false;
+    sourceDumpsStored: false;
+    rawCommandOutputStored: false;
+  };
+  privacy: EvolutionPrivacyFields;
+}
+
+export interface EvolutionRepoProposalCurrentState {
+  checkedAt: string;
+  headSha: string;
+  statusFingerprint: string;
+  verdict: "unresolved" | "resolved" | "unknown";
+  ownership: "governance" | "implementation" | "not-applicable";
+  explicitUserRequest: boolean;
+  checkedPaths: string[];
+  relatedCommits: string[];
+  summary: string;
+}
+
+export interface EvolutionRepoProposalRecurrence {
+  gapKey: string;
+  independentSessionCount: number;
+  sourceSessionKeys: string[];
+}
+
+export interface EvolutionRepoProposalSupersession {
+  policy: "session-proposal-v2";
+  reason: string;
+  supersededAt: string;
+}
+
+export interface EvolutionRepoProposal {
+  schemaVersion: 1;
+  id: string;
+  kind: EvolutionProposalKind;
+  projectKey: string;
+  title: string;
+  summary: string;
+  rationale: string;
+  roleTags: string[];
+  tags: string[];
+  reviewState: "pending" | "accepted" | "rejected" | "deferred" | "applied" | "superseded";
+  reviewStateChangedAt?: string;
+  confidence: EvolutionConfidence;
+  targetRepoPath: string | null;
+  currentState?: EvolutionRepoProposalCurrentState;
+  recurrence?: EvolutionRepoProposalRecurrence;
+  supersession?: EvolutionRepoProposalSupersession;
+  plannedFiles: Array<{
+    relativePath: string;
+    action: "create" | "update";
+    reason: string;
+    proposedChange?: string;
+  }>;
+  lastDecision?: {
+    state: "accepted" | "rejected" | "deferred";
+    reason: string | null;
+    decidedAt: string;
+  };
+  improvementEval?: EvolutionImprovementEval;
+  apply: {
+    autoApply: false;
+    requiresExplicitCommand: true;
+    rollbackPlan: string;
+  };
+  provenance: {
+    runId: string;
+    taskId: string | null;
+    evidenceWindowId: string;
+    sourceRefs: string[];
+    createdAt: string;
+    createdBy: "evodev";
+    rawLogsStored: false;
+    rawPromptsStored: false;
+    sourceDumpsStored: false;
+    rawCommandOutputStored: false;
+  };
+  privacy: EvolutionPrivacyFields;
+}
+
+export interface EvolutionReviewCandidate {
+  schemaVersion: 1;
+  kind: "evolution-review-candidate";
+  id: string;
+  projectKey: string;
+  runId: string;
+  createdAt: string;
+  candidateKind: string;
+  title: string;
+  targetStore: string;
+  targetPath: string;
+  stableKey: string;
+  reviewState: "needs-human" | "accepted" | "rejected" | "deferred";
+  reviewStateChangedAt?: string;
+  reasons: string[];
+  candidate: unknown;
+  provenance: {
+    runId: string;
+    evidenceWindowId: string;
+    evidenceRefs: string[];
+    createdBy: "evodev";
+    rawLogsStored: false;
+    rawPromptsStored: false;
+    sourceDumpsStored: false;
+    rawCommandOutputStored: false;
+  };
+  privacy: EvolutionPrivacyFields;
+}
+
+export interface EvolutionDistillationBatch {
+  schemaVersion: 1;
+  id: string;
+  projectKey: string;
+  runId: string;
+  createdAt: string;
+  evidenceWindow: EvolutionEvidenceWindow;
+  knowledgeRecords: EvolutionKnowledgeRecord[];
+  evosCases: EvolutionEvosCase[];
+  repoProposals: EvolutionRepoProposal[];
+  warnings: string[];
+}
+
+export interface EvolutionAnalyzeInput {
+  homeDir: string;
+  runId: string;
+  projectKey?: string;
+  projectDir?: string;
+  now?: string | Date;
+}
+
+export interface EvolutionAnalyzeResult {
+  evidenceWindow: EvolutionEvidenceWindow;
+  warnings: string[];
+}
+
+export interface EvolutionWriteResult {
+  evidenceWindowPath: string;
+  batchPath: string;
+  knowledgePaths: string[];
+  evosCasePaths: string[];
+  repoProposalPaths: string[];
+  knowledgeIndexPath: string;
+  evosIndexPath: string;
+}
+
+export interface EvolutionActivationResult {
+  evidenceWindowPath: string;
+  batchPath: string;
+  okf: OkfKnowledgeActivationResult;
+  evosCasePaths: string[];
+  repoProposalPaths: string[];
+  evosIndexPath: string;
+}
+
+export interface EvolutionReviewSnapshot {
+  projectKey: string | null;
+  knowledgeRecords: EvolutionKnowledgeRecord[];
+  evosCases: EvolutionEvosCase[];
+  repoProposals: EvolutionRepoProposal[];
+  reviewCandidates: EvolutionReviewCandidate[];
+  triggers: EvolutionTriggerRecord[];
+}
+
+export interface EvolutionEvosCaseQueryResult {
+  cases: EvolutionEvosCase[];
+  warnings: string[];
+}
+
+export interface EvolutionResolvedPaths {
+  projectKey: string;
+  runId: string;
+  evolutionStateDir: string;
+  runStateDir: string;
+  evidenceWindowPath: string;
+  batchPath: string;
+  triggersDir: string;
+  reviewCandidatesDir: string;
+  repoProposalsDir: string;
+  repoProposalsIndexPath: string;
+  knowledgeProjectDir: string;
+  knowledgeRecordsDir: string;
+  knowledgeIndexPath: string;
+  knowledgeReviewHistoryPath: string;
+  evosCasesProjectDir: string;
+  evosIndexPath: string;
+}
+
+export interface EvolutionTriggerInput {
+  homeDir: string;
+  projectKey: string;
+  runId: string;
+  roleId?: string | null;
+  taskId?: string | null;
+  eventType: string;
+  eventId?: string | null;
+  evidenceRef?: string | null;
+  summary?: string | null;
+  now?: string | Date;
+}
+
+export interface SegmentEvolutionTriggerInput {
+  homeDir: string;
+  projectKey: string;
+  sessionKey: string;
+  runId?: string | null;
+  roleId?: string | null;
+  segmentId: string;
+  segmentPath: string;
+  strength: SegmentEvolutionTriggerStrength;
+  reason: SegmentEvolutionTriggerReason;
+  summary: string;
+  now?: string | Date;
+}
+
+export interface EvolutionTriggerListInput {
+  homeDir: string;
+  projectKey?: string;
+  runId?: string;
+  status?: EvolutionTriggerStatus;
+}
+
+export interface SegmentEvolutionTriggerListInput {
+  homeDir: string;
+  projectKey?: string;
+  runId?: string;
+  status?: EvolutionTriggerStatus;
+}
+
+export interface EvolutionProcessInput {
+  homeDir: string;
+  projectKey?: string;
+  runId?: string;
+  limit?: number;
+  now?: string | Date;
+  dryRun?: boolean;
+  distillSessionKnowledge?: SessionKnowledgeDistiller;
+  onProgress?: (progress: EvolutionProcessProgress) => void | Promise<void>;
+}
+
+export interface SessionKnowledgeDistillerInput {
+  homeDir: string;
+  segment: SessionEvidenceSegmentV1;
+  evidenceWindow: EvolutionEvidenceWindow;
+  now: string;
+}
+
+export type SessionKnowledgeDistiller = (
+  input: SessionKnowledgeDistillerInput,
+) => Promise<OkfKnowledgePlan>;
+
+export interface EvolutionProcessProgress {
+  phase: "started" | "updated" | "completed";
+  total: number;
+  processed: number;
+  consumed: number;
+  skipped: number;
+  failed: number;
+  pending: number;
+}
+
+export interface EvolutionProcessResult {
+  processed: number;
+  consumed: number;
+  skipped: number;
+  failed: number;
+  pending: number;
+  triggerIds: string[];
+  batchIds: string[];
+  pendingChangeIds: string[];
+  warnings: string[];
+  dryRun: boolean;
+}