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

package/src/evolution/imports/types.ts

@@ -0,0 +1,226 @@
+export const TRAJECTORY_IMPORT_PREVIEW_SCHEMA_VERSION = 1 as const;
+export const TRAJECTORY_IMPORT_DIAGNOSTIC_POLICY_VERSION = 1 as const;
+
+export type TrajectoryImportSource =
+  | "claude-code"
+  | "codex"
+  | "hermes"
+  | "letta-code"
+  | "openclaw"
+  | "openhands";
+
+export type CanonicalImportRecordType =
+  | "meta"
+  | "user"
+  | "reasoning"
+  | "assistant"
+  | "assistant-tool-call"
+  | "tool";
+
+export type CanonicalImportSourceIdentityKind = "native" | "location" | "content" | "synthetic";
+
+export interface CanonicalImportSnapshot {
+  source: TrajectoryImportSource;
+  explicitSourceId: string | null;
+  inputBytes: number;
+  inputFingerprint: string;
+  normalizer: {
+    package: "@letta-ai/trajectory";
+    version: string;
+    canonicalSchemaVersion: number;
+    canonicalConfigHash: string;
+  };
+  groups: Array<{
+    sourceGroupId: string;
+    records: Array<{
+      recordId: string;
+      contentHash: string;
+      sourceOrderId: string;
+      componentIndex: number;
+      sourceIdentityKind: CanonicalImportSourceIdentityKind;
+      recordType: CanonicalImportRecordType;
+      recordJson: string;
+    }>;
+  }>;
+  diagnostics: Array<{ code: string }>;
+}
+
+export type TrajectoryImportDiagnosticSeverity = "info" | "warning" | "blocker";
+
+export interface TrajectoryImportIndexRecordV1 {
+  schemaVersion: 1;
+  kind: "trajectory-import-index-record";
+  stableRecordKeyHash: string;
+  contentDigest: string;
+  ordinal: number;
+  sourceIdentityKind: CanonicalImportSourceIdentityKind;
+  recordType: CanonicalImportRecordType;
+}
+
+export interface TrajectoryImportGenerationContractV1 {
+  normalizerVersion: string;
+  canonicalSchemaVersion: number;
+  canonicalConfigHash: string;
+}
+
+export interface TrajectoryImportPreviousSnapshotV1 {
+  sourceKey: string;
+  generationId: string;
+  initialInputFingerprint: string;
+  generationContract: TrajectoryImportGenerationContractV1;
+  snapshotId: string;
+  records: TrajectoryImportIndexRecordV1[];
+}
+
+export interface TrajectoryImportMaterializationPreviewV1 {
+  selectedRecords: number;
+  estimatedSegments: number;
+  truncatedSegments: number;
+  credentialRedactions: number;
+  estimatedTriggers: number;
+  retentionDays: number;
+}
+
+export interface TrajectoryImportDownstreamPreviewV1 {
+  semanticProcessing: "queue-only" | "automation-eligible";
+  automationKnowledge: boolean;
+  automationSemanticKnowledge: boolean;
+  mayInvokeConfiguredProviderAfterApply: boolean;
+}
+
+export interface TrajectoryImportPreviewV1 {
+  schemaVersion: 1;
+  kind: "trajectory-import-preview";
+  id: string;
+  source: TrajectoryImportSource;
+  sourceKey: string;
+  projectKey: string | null;
+  scope: {
+    roleId: string | null;
+  };
+  input: {
+    bytes: number;
+    fingerprint: string;
+    pathHash: string;
+  };
+  normalizer: {
+    version: string;
+    canonicalSchemaVersion: number;
+    canonicalConfigHash: string;
+  };
+  contracts: {
+    diagnosticPolicyVersion: number;
+    materializerVersion: number;
+    materializerConfigHash: string;
+  };
+  generationId: string;
+  snapshotId: string;
+  previousSnapshotId: string | null;
+  records: {
+    total: number;
+    new: number;
+    unchanged: number;
+    changed: number;
+    missing: number;
+    recordTypes: Record<CanonicalImportRecordType, number>;
+    identityKinds: Record<CanonicalImportSourceIdentityKind, number>;
+  };
+  diagnostics: Array<{
+    code: string;
+    severity: TrajectoryImportDiagnosticSeverity;
+    count: number;
+  }>;
+  materialization: TrajectoryImportMaterializationPreviewV1 | null;
+  downstream: TrajectoryImportDownstreamPreviewV1;
+  blockers: string[];
+  canApply: boolean;
+  rawContentStored: false;
+}
+
+export interface CreateTrajectoryImportPreviewInput {
+  snapshot: CanonicalImportSnapshot;
+  projectKey?: string | null;
+  roleId?: string | null;
+  pathHash: string;
+  previous?: TrajectoryImportPreviousSnapshotV1 | null;
+}
+
+export interface TrajectoryImportPreviewBuildResult {
+  preview: TrajectoryImportPreviewV1;
+  comparisonSnapshot: TrajectoryImportPreviousSnapshotV1;
+}
+
+export type TrajectoryImportApplyState = "staged" | "materializing" | "completed";
+
+export interface TrajectoryImportManifestV1 {
+  schemaVersion: 1;
+  kind: "trajectory-import-manifest";
+  source: TrajectoryImportSource;
+  sourceKey: string;
+  projectKey: string;
+  scope: {
+    roleId: string | null;
+  };
+  currentGenerationId: string;
+  initialInputFingerprint: string;
+  generationContract: TrajectoryImportGenerationContractV1;
+  currentSnapshotId: string;
+  previousSnapshotId: string | null;
+  currentPreviewId: string;
+  currentInputFingerprint: string;
+  currentInputBytes: number;
+  currentIndexDigest: string;
+  stagedAt: string;
+  applyState: TrajectoryImportApplyState;
+  latestMaterializedSnapshotId: string | null;
+  rawContentStored: false;
+}
+
+export interface TrajectoryImportReceiptV1 {
+  schemaVersion: 1;
+  kind: "trajectory-import-receipt";
+  previewId: string;
+  sourceKey: string;
+  generationId: string;
+  snapshotId: string;
+  operation: "stage" | "materialize";
+  outcome: "staged" | "completed";
+  counts: {
+    total: number;
+    new: number;
+    unchanged: number;
+    changed: number;
+    missing: number;
+  };
+  createdAt: string;
+  rawContentStored: false;
+}
+
+export interface StageTrajectoryImportInput {
+  homeDir: string;
+  preview: TrajectoryImportPreviewV1;
+  comparisonSnapshot: TrajectoryImportPreviousSnapshotV1;
+  now?: string;
+}
+
+export interface StageTrajectoryImportResult {
+  status: "staged" | "unchanged";
+  manifest: TrajectoryImportManifestV1;
+  receipt: TrajectoryImportReceiptV1;
+  stateWrites: string[];
+}
+
+export interface TrajectoryImportMaterializationProgressV1 {
+  schemaVersion: 1;
+  kind: "trajectory-import-materialization-progress";
+  previewId: string;
+  sourceKey: string;
+  generationId: string;
+  snapshotId: string;
+  expectedSegmentIds: string[];
+  completedSegmentIds: string[];
+  expectedTriggerIds: string[];
+  completedTriggerIds: string[];
+  updatedAt: string;
+  rawContentStored: false;
+}

package/src/evolution/index.ts

@@ -1,13 +1,16 @@
 export * from "./schema.ts";
 export * from "./paths.ts";
+export * from "./imports/index.ts";
 export * from "./evidence/analysis.ts";
 export * from "./processor/index.ts";
 export * from "./candidates/index.ts";
 export * from "./triggers/index.ts";
 export * from "./formatters.ts";
 export {
+  createEvolutionImprovementEval,
   createEvolutionRepoProposal,
   hasConcreteRepoProposalChanges,
+  isEvolutionImprovementEvalRecommended,
   sanitizeProposedChange,
   validateEvolutionDistillationBatch,
   validateEvolutionEvidenceWindow,

package/src/evolution/schema.ts

@@ -73,7 +73,8 @@ export type SegmentEvolutionTriggerReason =
   | "failure-signal"
   | "permission-denied"
   | "verification-after-fix"
-  | "explicit-memory-intent";
+  | "explicit-memory-intent"
+  | "historical-import";
 export type SegmentEvolutionTriggerStrength = "normal" | "strong";
 
 export type EvolutionKnowledgeKind =
@@ -110,6 +111,47 @@ export type EvolutionProposalKind =
   | "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;
@@ -355,6 +397,7 @@ export interface EvolutionRepoProposal {
     reason: string | null;
     decidedAt: string;
   };
+  improvementEval?: EvolutionImprovementEval;
   apply: {
     autoApply: false;
     requiresExplicitCommand: true;

package/src/evolution/shared.ts

@@ -13,6 +13,8 @@ import type {
   EvolutionEvidenceSourceKind,
   EvolutionEvidenceWindow,
   EvolutionEvosCase,
+  EvolutionImprovementEval,
+  EvolutionImprovementEvalStatus,
   EvolutionKnowledgeKind,
   EvolutionKnowledgeRecord,
   EvolutionNormalizedEventType,
@@ -75,6 +77,14 @@ export const PROPOSAL_KINDS: readonly EvolutionProposalKind[] = [
   "docs",
   "engineering-practice",
 ];
+export const IMPROVEMENT_EVAL_STATUSES: readonly EvolutionImprovementEvalStatus[] = [
+  "not-requested",
+  "awaiting-eval",
+  "evaluating",
+  "effective",
+  "ineffective",
+  "inconclusive",
+];
 export const EVENT_KINDS: readonly EvolutionEvidenceEventKind[] = [
   "trace",
   "tool-call",
@@ -148,6 +158,7 @@ export const SEGMENT_TRIGGER_REASONS: readonly SegmentEvolutionTriggerReason[] =
   "permission-denied",
   "verification-after-fix",
   "explicit-memory-intent",
+  "historical-import",
 ];
 export const SEGMENT_TRIGGER_STRENGTHS: readonly SegmentEvolutionTriggerStrength[] = [
   "normal",
@@ -352,6 +363,9 @@ export function createEvolutionRepoProposal(
         ? {}
         : { proposedChange: sanitizeProposedChange(file.proposedChange) }),
     })),
+    ...(input.improvementEval === undefined
+      ? {}
+      : { improvementEval: sanitizeEvolutionImprovementEval(input.improvementEval) }),
     privacy: { ...input.privacy },
   };
   proposal.privacy.internalLinksStored =
@@ -408,6 +422,9 @@ export function validateEvolutionRepoProposal(proposal: EvolutionRepoProposal):
       throw new Error("Repo proposal decision timestamp must be valid.");
     }
   }
+  if (proposal.improvementEval !== undefined) {
+    validateEvolutionImprovementEval(proposal.improvementEval);
+  }
   if (proposal.apply.autoApply !== false || proposal.apply.requiresExplicitCommand !== true) {
     throw new Error("Repo proposal must require explicit apply.");
   }
@@ -416,6 +433,28 @@ export function validateEvolutionRepoProposal(proposal: EvolutionRepoProposal):
   assertNoForbiddenRawFields(proposal);
 }
 
+export function isEvolutionImprovementEvalRecommended(kind: EvolutionProposalKind): boolean {
+  return !["ci", "test", "docs"].includes(kind);
+}
+
+export function createEvolutionImprovementEval(input: {
+  kind: EvolutionProposalKind;
+  requested?: boolean;
+  now?: string | Date;
+}): EvolutionImprovementEval {
+  const requested = input.requested ?? false;
+  const requestedAt = requested ? normalizeTimestampValue(input.now) : null;
+  return {
+    recommended: isEvolutionImprovementEvalRecommended(input.kind),
+    requested,
+    status: requested ? "awaiting-eval" : "not-requested",
+    requestedAt,
+    evaluatedAt: null,
+    evidenceRef: null,
+    result: null,
+  };
+}
+
 export function hasConcreteRepoProposalChanges(proposal: EvolutionRepoProposal): boolean {
   return (
     proposal.targetRepoPath !== null &&
@@ -427,6 +466,154 @@ export function hasConcreteRepoProposalChanges(proposal: EvolutionRepoProposal):
   );
 }
 
+function validateEvolutionImprovementEval(value: EvolutionImprovementEval): void {
+  if (!isRecord(value)) throw new Error("Repo proposal improvementEval must be an object.");
+  if (typeof value.recommended !== "boolean" || typeof value.requested !== "boolean") {
+    throw new Error("Repo proposal improvementEval flags must be booleans.");
+  }
+  assertEnum("improvementEval.status", value.status, IMPROVEMENT_EVAL_STATUSES);
+  assertNullableTimestamp("improvementEval.requestedAt", value.requestedAt);
+  assertNullableTimestamp("improvementEval.evaluatedAt", value.evaluatedAt);
+  if (value.evidenceRef !== null) assertString("improvementEval.evidenceRef", value.evidenceRef);
+  if (!value.requested) {
+    if (
+      value.status !== "not-requested" ||
+      value.requestedAt !== null ||
+      value.evaluatedAt !== null ||
+      value.result !== null
+    ) {
+      throw new Error("A non-requested improvement eval cannot have evaluation state.");
+    }
+    return;
+  }
+  if (value.status === "not-requested" || value.requestedAt === null) {
+    throw new Error("A requested improvement eval must be awaiting or completed.");
+  }
+  const completed = ["effective", "ineffective", "inconclusive"].includes(value.status);
+  if (completed !== (value.result !== null && value.evaluatedAt !== null)) {
+    throw new Error("Completed improvement eval state and result must be stored together.");
+  }
+  if (value.result === null) return;
+  if (value.result.targetImproved !== null && typeof value.result.targetImproved !== "boolean") {
+    throw new Error("Improvement eval targetImproved must be boolean or null.");
+  }
+  if (value.result.hardRegression !== null && typeof value.result.hardRegression !== "boolean") {
+    throw new Error("Improvement eval hardRegression must be boolean or null.");
+  }
+  if (
+    value.status === "effective" &&
+    (value.result.targetImproved !== true || value.result.hardRegression !== false)
+  ) {
+    throw new Error("An effective improvement eval must improve the target without regression.");
+  }
+  if (
+    value.status === "ineffective" &&
+    value.result.targetImproved !== false &&
+    value.result.hardRegression !== true
+  ) {
+    throw new Error("An ineffective improvement eval must fail the target or a hard gate.");
+  }
+  if (
+    value.status === "inconclusive" &&
+    (value.result.targetImproved === false ||
+      value.result.hardRegression === true ||
+      (value.result.targetImproved === true && value.result.hardRegression === false))
+  ) {
+    throw new Error("An inconclusive improvement eval cannot contain a definitive gate result.");
+  }
+  assertString("improvementEval.result.summary", value.result.summary);
+  if (!Array.isArray(value.result.assertions) || value.result.assertions.length > 8) {
+    throw new Error("Improvement eval assertions must contain at most 8 items.");
+  }
+  for (const assertion of value.result.assertions) {
+    assertString("improvementEval.result.assertions.label", assertion.label);
+    assertEnum("improvementEval.result.assertions.status", assertion.status, [
+      "pass",
+      "fail",
+      "unknown",
+    ]);
+  }
+  if (
+    value.result.evaluatedBy !== "local-code-agent" &&
+    value.result.evaluatedBy !== "local-eval-orchestrator"
+  ) {
+    throw new Error("Improvement eval evaluatedBy is invalid.");
+  }
+  if (!isRecord(value.result.metrics)) {
+    throw new Error("Improvement eval metrics must be an object.");
+  }
+  if (
+    !isNonNegativeInteger(value.result.metrics.durationMs) ||
+    !isNonNegativeInteger(value.result.metrics.modelCalls)
+  ) {
+    throw new Error("Improvement eval duration and model call count are required.");
+  }
+  if (
+    (value.result.evaluatedBy === "local-code-agent" && value.result.metrics.modelCalls !== 1) ||
+    (value.result.evaluatedBy === "local-eval-orchestrator" &&
+      value.result.metrics.modelCalls !== 0)
+  ) {
+    throw new Error("Improvement eval model call metadata is inconsistent.");
+  }
+  for (const [field, metric] of [
+    ["inputTokens", value.result.metrics.inputTokens],
+    ["outputTokens", value.result.metrics.outputTokens],
+    ["toolCalls", value.result.metrics.toolCalls],
+  ] as const) {
+    if (metric !== null && !isNonNegativeInteger(metric)) {
+      throw new Error(`Improvement eval metric ${field} must be a non-negative integer or null.`);
+    }
+  }
+  if (
+    value.result.retention.metadataOnly !== true ||
+    value.result.retention.replayInputStored !== false ||
+    value.result.retention.replayOutputStored !== false
+  ) {
+    throw new Error("Improvement eval must retain metadata-only results.");
+  }
+}
+
+function sanitizeEvolutionImprovementEval(
+  value: EvolutionImprovementEval,
+): EvolutionImprovementEval {
+  return {
+    ...value,
+    evidenceRef: value.evidenceRef === null ? null : sanitizeId(value.evidenceRef),
+    result:
+      value.result === null
+        ? null
+        : {
+            ...value.result,
+            summary: sanitizeText(value.result.summary),
+            assertions: value.result.assertions.slice(0, 8).map((assertion) => ({
+              label: sanitizeText(assertion.label),
+              status: assertion.status,
+            })),
+            metrics: { ...value.result.metrics },
+            retention: { ...value.result.retention },
+          },
+  };
+}
+
+function assertNullableTimestamp(field: string, value: string | null): void {
+  if (value !== null && Number.isNaN(new Date(value).getTime())) {
+    throw new Error(`${field} must be null or a valid timestamp.`);
+  }
+}
+
+function isNonNegativeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+
+function normalizeTimestampValue(value: string | Date | undefined): string {
+  const timestamp =
+    value instanceof Date ? value.toISOString() : (value ?? new Date().toISOString());
+  if (Number.isNaN(new Date(timestamp).getTime())) {
+    throw new Error("Improvement eval timestamp must be valid.");
+  }
+  return timestamp;
+}
+
 export function validateEvolutionReviewCandidate(candidate: EvolutionReviewCandidate): void {
   if (!isRecord(candidate)) throw new Error("Review candidate must be an object.");
   if (candidate.schemaVersion !== 1) {