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

package/src/evolution/imports/apply.ts

@@ -0,0 +1,435 @@
+import { createStableId } from "../../utils/index.ts";
+import {
+  readSessionEvidenceSegment,
+  resolveSessionMemoryPaths,
+  writeHistoricalSessionEvidenceSegment,
+  writeHistoricalSessionStateAndIndex,
+} from "../evidence/session-memory/index.ts";
+import type { SegmentEvolutionTriggerRecord } from "../schema.ts";
+import {
+  enqueueSegmentEvolutionTrigger,
+  listSegmentEvolutionTriggers,
+  resolveSegmentEvolutionTriggerPath,
+} from "../triggers/index.ts";
+import {
+  type TrajectoryImportMaterializationPlan,
+  createHistoricalSessionEvidenceSegments,
+} from "./materialize.ts";
+import { resolveTrajectoryImportPaths, resolveTrajectoryImportSourcePaths } from "./paths.ts";
+import { stageTrajectoryImportWithLock } from "./stage.ts";
+import {
+  assertTrajectoryImportSourceLockOwned,
+  readTrajectoryImportMaterializationProgress,
+  readTrajectoryImportReceipt,
+  withTrajectoryImportSourceLock,
+  writeImmutableTrajectoryImportReceipt,
+  writeTrajectoryImportManifest,
+  writeTrajectoryImportMaterializationProgress,
+} from "./storage.ts";
+import type {
+  TrajectoryImportManifestV1,
+  TrajectoryImportMaterializationProgressV1,
+  TrajectoryImportReceiptV1,
+} from "./types.ts";
+
+export interface ApplyTrajectoryImportInput {
+  homeDir: string;
+  plan: TrajectoryImportMaterializationPlan;
+  expectedPreviewId: string;
+  now?: string;
+}
+
+export interface ApplyTrajectoryImportResult {
+  status: "applied" | "unchanged";
+  previewId: string;
+  generationId: string;
+  snapshotId: string;
+  segmentIds: string[];
+  triggerIds: string[];
+  materializationReceipt: TrajectoryImportReceiptV1;
+  stateWrites: string[];
+}
+
+export async function applyTrajectoryImport(
+  input: ApplyTrajectoryImportInput,
+): Promise<ApplyTrajectoryImportResult> {
+  validateApplyInput(input);
+  const projectKey = input.plan.preview.projectKey;
+  if (projectKey === null) {
+    throw new Error("Trajectory import apply requires a projectKey.");
+  }
+  const sourcePaths = resolveTrajectoryImportSourcePaths({
+    homeDir: input.homeDir,
+    projectKey,
+    sourceKey: input.plan.preview.sourceKey,
+  });
+
+  return withTrajectoryImportSourceLock(sourcePaths, async (lock) => {
+    const staged = await stageTrajectoryImportWithLock(
+      {
+        homeDir: input.homeDir,
+        preview: input.plan.preview,
+        comparisonSnapshot: input.plan.comparisonSnapshot,
+        now: input.now,
+      },
+      lock,
+    );
+    await assertTrajectoryImportSourceLockOwned(lock);
+
+    if (
+      staged.manifest.applyState === "completed" &&
+      staged.manifest.latestMaterializedSnapshotId === staged.manifest.currentSnapshotId
+    ) {
+      return readCompletedApplyResult(input, staged.manifest);
+    }
+    if (
+      staged.manifest.currentPreviewId !== input.plan.preview.id ||
+      staged.manifest.currentSnapshotId !== input.plan.preview.snapshotId
+    ) {
+      throw new Error("Trajectory import staged state does not match the apply preview.");
+    }
+
+    const paths = resolveTrajectoryImportPaths({
+      homeDir: input.homeDir,
+      projectKey,
+      sourceKey: input.plan.preview.sourceKey,
+      generationId: input.plan.preview.generationId,
+      snapshotId: input.plan.preview.snapshotId,
+      previewId: input.plan.preview.id,
+    });
+    const materializingManifest: TrajectoryImportManifestV1 = {
+      ...staged.manifest,
+      applyState: "materializing",
+    };
+    await writeTrajectoryImportManifest(sourcePaths, materializingManifest);
+    await assertTrajectoryImportSourceLockOwned(lock);
+
+    const segments = createHistoricalSessionEvidenceSegments({
+      plan: input.plan,
+      createdAt: staged.receipt.createdAt,
+    });
+    const sessionKey = `historical-${input.plan.preview.sourceKey}`;
+    const sessionPaths = resolveSessionMemoryPaths({
+      homeDir: input.homeDir,
+      projectKey,
+      sessionKey,
+    });
+    const expectedTriggerIds = segments.map((segment) =>
+      createStableId("segment-trigger", [projectKey, sessionKey, segment.id]),
+    );
+    let progress = await resolveMaterializationProgress({
+      path: paths.materializationPath,
+      previewId: input.plan.preview.id,
+      sourceKey: input.plan.preview.sourceKey,
+      generationId: input.plan.preview.generationId,
+      snapshotId: input.plan.preview.snapshotId,
+      expectedSegmentIds: segments.map((segment) => segment.id),
+      expectedTriggerIds,
+      updatedAt: staged.receipt.createdAt,
+    });
+    await writeTrajectoryImportMaterializationProgress(paths, progress);
+    const stateWrites = [
+      ...staged.stateWrites,
+      `materializations/${input.plan.preview.snapshotId}.json`,
+    ];
+
+    for (const segment of segments) {
+      const written = await writeHistoricalSessionEvidenceSegment({
+        homeDir: input.homeDir,
+        paths: sessionPaths,
+        segment,
+      });
+      if (written.created) stateWrites.push(sessionPaths.segmentPath(segment.id));
+      progress = addCompletedProgress(progress, "segment", segment.id);
+      await writeTrajectoryImportMaterializationProgress(paths, progress);
+      await assertTrajectoryImportSourceLockOwned(lock);
+    }
+
+    if (segments.length > 0) {
+      await writeHistoricalSessionStateAndIndex({
+        homeDir: input.homeDir,
+        paths: sessionPaths,
+        projectKey,
+        sessionKey,
+        target: segments[0]?.target ?? "unknown",
+        roleId: input.plan.preview.scope.roleId,
+        policy: input.plan.policy,
+        now: staged.receipt.createdAt,
+      });
+      stateWrites.push(sessionPaths.statePath, sessionPaths.indexPath);
+    }
+
+    const triggerIds: string[] = [];
+    for (const [index, segment] of segments.entries()) {
+      const trigger = await enqueueSegmentEvolutionTrigger({
+        homeDir: input.homeDir,
+        projectKey,
+        sessionKey,
+        runId: null,
+        roleId: input.plan.preview.scope.roleId,
+        segmentId: segment.id,
+        segmentPath: sessionPaths.segmentPath(segment.id),
+        strength: "normal",
+        reason: "historical-import",
+        summary: segment.normalized.summary,
+        now: staged.receipt.createdAt,
+      });
+      assertHistoricalTriggerCompatible(trigger, {
+        segmentId: segment.id,
+        expectedId: expectedTriggerIds[index] ?? "",
+        segmentPath: sessionPaths.segmentPath(segment.id),
+        summary: segment.normalized.summary,
+      });
+      triggerIds.push(trigger.id);
+      progress = addCompletedProgress(progress, "trigger", trigger.id);
+      await writeTrajectoryImportMaterializationProgress(paths, progress);
+      await assertTrajectoryImportSourceLockOwned(lock);
+      stateWrites.push(resolveSegmentEvolutionTriggerPath(input.homeDir, trigger));
+    }
+
+    await verifyMaterializedSegments({
+      homeDir: input.homeDir,
+      projectKey,
+      sessionKey,
+      segmentIds: progress.expectedSegmentIds,
+    });
+    if (
+      progress.completedSegmentIds.length !== progress.expectedSegmentIds.length ||
+      progress.completedTriggerIds.length !== progress.expectedTriggerIds.length
+    ) {
+      throw new Error("Trajectory import materialization did not complete all expected writes.");
+    }
+
+    const materializationReceipt: TrajectoryImportReceiptV1 = {
+      schemaVersion: 1,
+      kind: "trajectory-import-receipt",
+      previewId: input.plan.preview.id,
+      sourceKey: input.plan.preview.sourceKey,
+      generationId: input.plan.preview.generationId,
+      snapshotId: input.plan.preview.snapshotId,
+      operation: "materialize",
+      outcome: "completed",
+      counts: {
+        total: input.plan.preview.records.total,
+        new: input.plan.preview.records.new,
+        unchanged: input.plan.preview.records.unchanged,
+        changed: input.plan.preview.records.changed,
+        missing: input.plan.preview.records.missing,
+      },
+      createdAt: staged.receipt.createdAt,
+      rawContentStored: false,
+    };
+    const receiptWrite = await writeImmutableTrajectoryImportReceipt(
+      paths.materializeReceiptPath,
+      materializationReceipt,
+    );
+    if (receiptWrite.created) {
+      stateWrites.push(`receipts/${input.plan.preview.id}/materialize.json`);
+    }
+    await assertTrajectoryImportSourceLockOwned(lock);
+
+    const completedManifest: TrajectoryImportManifestV1 = {
+      ...materializingManifest,
+      applyState: "completed",
+      latestMaterializedSnapshotId: input.plan.preview.snapshotId,
+    };
+    await writeTrajectoryImportManifest(sourcePaths, completedManifest);
+    await assertTrajectoryImportSourceLockOwned(lock);
+    stateWrites.push("manifest.json");
+
+    return {
+      status: "applied",
+      previewId: input.plan.preview.id,
+      generationId: input.plan.preview.generationId,
+      snapshotId: input.plan.preview.snapshotId,
+      segmentIds: segments.map((segment) => segment.id),
+      triggerIds,
+      materializationReceipt,
+      stateWrites: [...new Set(stateWrites)],
+    };
+  });
+}
+
+async function readCompletedApplyResult(
+  input: ApplyTrajectoryImportInput,
+  manifest: TrajectoryImportManifestV1,
+): Promise<ApplyTrajectoryImportResult> {
+  const projectKey = input.plan.preview.projectKey;
+  if (projectKey === null) throw new Error("Trajectory import apply requires a projectKey.");
+  const paths = resolveTrajectoryImportPaths({
+    homeDir: input.homeDir,
+    projectKey,
+    sourceKey: manifest.sourceKey,
+    generationId: manifest.currentGenerationId,
+    snapshotId: manifest.currentSnapshotId,
+    previewId: manifest.currentPreviewId,
+  });
+  const receipt = await readTrajectoryImportReceipt(paths.materializeReceiptPath);
+  if (
+    receipt === null ||
+    receipt.operation !== "materialize" ||
+    receipt.outcome !== "completed" ||
+    receipt.snapshotId !== manifest.currentSnapshotId ||
+    receipt.previewId !== manifest.currentPreviewId
+  ) {
+    throw new Error("Completed trajectory import is missing its materialization receipt.");
+  }
+  const progress = await readTrajectoryImportMaterializationProgress(paths.materializationPath);
+  if (progress === null) {
+    throw new Error("Completed trajectory import is missing materialization progress.");
+  }
+  if (
+    progress.completedSegmentIds.length !== progress.expectedSegmentIds.length ||
+    progress.completedTriggerIds.length !== progress.expectedTriggerIds.length
+  ) {
+    throw new Error("Completed trajectory import has incomplete materialization progress.");
+  }
+  const sessionKey = `historical-${manifest.sourceKey}`;
+  await verifyMaterializedSegments({
+    homeDir: input.homeDir,
+    projectKey,
+    sessionKey,
+    segmentIds: progress.expectedSegmentIds,
+  });
+  const triggerIds = new Set(
+    (
+      await listSegmentEvolutionTriggers({
+        homeDir: input.homeDir,
+        projectKey,
+      })
+    )
+      .filter(
+        (trigger) =>
+          trigger.sessionKey === sessionKey &&
+          progress.expectedSegmentIds.includes(trigger.segmentId),
+      )
+      .map((trigger) => trigger.id),
+  );
+  if (progress.expectedTriggerIds.some((id) => !triggerIds.has(id))) {
+    throw new Error("Completed trajectory import is missing a materialized trigger.");
+  }
+  return {
+    status: "unchanged",
+    previewId: input.plan.preview.id,
+    generationId: manifest.currentGenerationId,
+    snapshotId: manifest.currentSnapshotId,
+    segmentIds: progress.expectedSegmentIds,
+    triggerIds: progress.expectedTriggerIds,
+    materializationReceipt: receipt,
+    stateWrites: [],
+  };
+}
+
+async function resolveMaterializationProgress(input: {
+  path: string;
+  previewId: string;
+  sourceKey: string;
+  generationId: string;
+  snapshotId: string;
+  expectedSegmentIds: string[];
+  expectedTriggerIds: string[];
+  updatedAt: string;
+}): Promise<TrajectoryImportMaterializationProgressV1> {
+  const existing = await readTrajectoryImportMaterializationProgress(input.path);
+  if (existing === null) {
+    return {
+      schemaVersion: 1,
+      kind: "trajectory-import-materialization-progress",
+      previewId: input.previewId,
+      sourceKey: input.sourceKey,
+      generationId: input.generationId,
+      snapshotId: input.snapshotId,
+      expectedSegmentIds: input.expectedSegmentIds,
+      completedSegmentIds: [],
+      expectedTriggerIds: input.expectedTriggerIds,
+      completedTriggerIds: [],
+      updatedAt: input.updatedAt,
+      rawContentStored: false,
+    };
+  }
+  if (
+    existing.previewId !== input.previewId ||
+    existing.sourceKey !== input.sourceKey ||
+    existing.generationId !== input.generationId ||
+    existing.snapshotId !== input.snapshotId ||
+    JSON.stringify(existing.expectedSegmentIds) !== JSON.stringify(input.expectedSegmentIds) ||
+    JSON.stringify(existing.expectedTriggerIds) !== JSON.stringify(input.expectedTriggerIds)
+  ) {
+    throw new Error("Trajectory import materialization progress conflicts with its preview.");
+  }
+  return existing;
+}
+
+function addCompletedProgress(
+  progress: TrajectoryImportMaterializationProgressV1,
+  kind: "segment" | "trigger",
+  id: string,
+): TrajectoryImportMaterializationProgressV1 {
+  return {
+    ...progress,
+    completedSegmentIds:
+      kind === "segment"
+        ? [...new Set([...progress.completedSegmentIds, id])]
+        : progress.completedSegmentIds,
+    completedTriggerIds:
+      kind === "trigger"
+        ? [...new Set([...progress.completedTriggerIds, id])]
+        : progress.completedTriggerIds,
+  };
+}
+
+async function verifyMaterializedSegments(input: {
+  homeDir: string;
+  projectKey: string;
+  sessionKey: string;
+  segmentIds: string[];
+}): Promise<void> {
+  for (const segmentId of input.segmentIds) {
+    const segment = await readSessionEvidenceSegment({ ...input, segmentId });
+    if (segment.origin?.kind !== "historical-import") {
+      throw new Error("Trajectory import materialized segment origin is invalid.");
+    }
+  }
+}
+
+function assertHistoricalTriggerCompatible(
+  trigger: SegmentEvolutionTriggerRecord,
+  expected: {
+    segmentId: string;
+    expectedId: string;
+    segmentPath: string;
+    summary: string;
+  },
+): void {
+  if (
+    trigger.id !== expected.expectedId ||
+    trigger.segmentId !== expected.segmentId ||
+    trigger.segmentPath !== expected.segmentPath ||
+    trigger.reason !== "historical-import" ||
+    trigger.strength !== "normal" ||
+    trigger.summary !== expected.summary
+  ) {
+    throw new Error("Historical segment trigger immutable content conflict.");
+  }
+}
+
+function validateApplyInput(input: ApplyTrajectoryImportInput): void {
+  if (input.expectedPreviewId !== input.plan.preview.id) {
+    throw new Error("Trajectory import preview changed; run --dry-run again.");
+  }
+  if (!input.plan.preview.canApply || input.plan.preview.blockers.length > 0) {
+    throw new Error(
+      `Trajectory import cannot apply${
+        input.plan.preview.blockers.length === 0
+          ? "."
+          : `: ${input.plan.preview.blockers.join(", ")}.`
+      }`,
+    );
+  }
+  if (
+    input.now !== undefined &&
+    (!Number.isFinite(Date.parse(input.now)) || new Date(input.now).toISOString() !== input.now)
+  ) {
+    throw new Error("Trajectory import apply now must be an ISO timestamp.");
+  }
+}