Restore named project snapshots

src/domain/errors/project-state-conflict.error.ts

@@ -0,0 +1,10 @@
+export class ProjectStateConflictError extends Error {
+  constructor(
+    public readonly projectId: string,
+    public readonly expectedSha256: string,
+    public readonly actualSha256: string
+  ) {
+    super(`Project ${projectId} changed outside the prepared restore state.`);
+    this.name = "ProjectStateConflictError";
+  }
+}

src/domain/models/project-state-restore-command.model.ts

@@ -0,0 +1,62 @@
+import {
+  parseProjectStateSnapshot,
+  type ProjectStateSnapshot,
+} from "./project-state-snapshot.model.js";
+import type { SerializedProjectCommand } from "./project-command.model.js";
+
+export const projectStateRestoreCommandType = "project.restore-state";
+export const projectStateRestoreCommandSchemaVersion = 1 as const;
+
+export interface ProjectStateRestoreCommandPayload {
+  expectedStateSha256: string;
+  targetState: ProjectStateSnapshot;
+}
+
+export type ProjectStateRestoreCommand = SerializedProjectCommand<
+  ProjectStateRestoreCommandPayload
+> & {
+  schemaVersion: typeof projectStateRestoreCommandSchemaVersion;
+  type: typeof projectStateRestoreCommandType;
+};
+
+export function createProjectStateRestoreCommand(
+  expectedStateSha256: string,
+  targetState: ProjectStateSnapshot
+): ProjectStateRestoreCommand {
+  const command: ProjectStateRestoreCommand = {
+    schemaVersion: projectStateRestoreCommandSchemaVersion,
+    type: projectStateRestoreCommandType,
+    payload: {
+      expectedStateSha256,
+      targetState: parseProjectStateSnapshot(targetState),
+    },
+  };
+  assertProjectStateRestoreCommand(command);
+  return command;
+}
+
+export function assertProjectStateRestoreCommand(
+  value: unknown
+): asserts value is ProjectStateRestoreCommand {
+  if (!value || typeof value !== "object") {
+    throw new Error("Project state restore command must be an object.");
+  }
+  const command = value as Partial<ProjectStateRestoreCommand>;
+  if (
+    command.type !== projectStateRestoreCommandType ||
+    command.schemaVersion !== projectStateRestoreCommandSchemaVersion
+  ) {
+    throw new Error("Unsupported project state restore command.");
+  }
+  if (!command.payload || typeof command.payload !== "object") {
+    throw new Error("Project state restore payload is required.");
+  }
+  const payload = command.payload as Partial<ProjectStateRestoreCommandPayload>;
+  if (
+    typeof payload.expectedStateSha256 !== "string" ||
+    !/^[a-f0-9]{64}$/.test(payload.expectedStateSha256)
+  ) {
+    throw new Error("Expected project state checksum is invalid.");
+  }
+  parseProjectStateSnapshot(payload.targetState);
+}

src/domain/ports/project-command.executor.ts

@@ -24,6 +24,9 @@ export interface ProjectCommandExecutor {
   executeUser(
     input: ExecuteUserProjectCommandInput
   ): ExecutedProjectCommand;
+  executeRestore(
+    input: ExecuteUserProjectCommandInput
+  ): ExecutedProjectCommand;
   undo(
     input: ExecuteProjectHistoryCommandInput
   ): ExecutedProjectCommand;

src/domain/ports/project-snapshot.store.ts

@@ -18,9 +18,19 @@ export interface CreateNamedProjectSnapshotInput {
   actorId?: string;
 }
 
+export interface PreparedProjectSnapshotRestore {
+  snapshot: ProjectSnapshotMetadata;
+  command: ProjectStateRestoreCommand;
+}
+
 export interface ProjectSnapshotStore {
   createNamed(
     input: CreateNamedProjectSnapshotInput
   ): ProjectSnapshotMetadata | null;
   listByProject(projectId: string): ProjectSnapshotMetadata[] | null;
+  prepareRestore(
+    projectId: string,
+    snapshotId: string
+  ): PreparedProjectSnapshotRestore | null;
 }
+import type { ProjectStateRestoreCommand } from "../models/project-state-restore-command.model.js";

src/domain/ports/project-state-restore-command.store.ts

@@ -0,0 +1,26 @@
+import type { ProjectStateRestoreCommand } from "../models/project-state-restore-command.model.js";
+import type {
+  AppendedProjectRevision,
+  ProjectRevisionSource,
+} from "./project-revision.store.js";
+
+export interface ExecuteProjectStateRestoreCommandInput {
+  projectId: string;
+  expectedRevision: number;
+  source: ProjectRevisionSource;
+  description?: string;
+  actorId?: string;
+  historyTargetChangeSetId?: string;
+  command: ProjectStateRestoreCommand;
+}
+
+export interface ExecutedProjectStateRestoreCommand {
+  revision: AppendedProjectRevision;
+  inverse: ProjectStateRestoreCommand;
+}
+
+export interface ProjectStateRestoreCommandStore {
+  execute(
+    input: ExecuteProjectStateRestoreCommandInput
+  ): ExecutedProjectStateRestoreCommand;
+}

src/domain/services/project-command.service.ts

@@ -41,6 +41,10 @@ import {
   assertSerializedProjectCommand,
   type SerializedProjectCommand,
 } from "../models/project-command.model.js";
+import {
+  assertProjectStateRestoreCommand,
+  projectStateRestoreCommandType,
+} from "../models/project-state-restore-command.model.js";
 import {
   assertProjectDeviceRowSyncProjectCommand,
   projectDeviceRowSyncCommandType,
@@ -76,6 +80,7 @@ import type { ProjectDeviceProjectCommandStore } from "../ports/project-device-p
 import type { ProjectDeviceRowSyncProjectCommandStore } from "../ports/project-device-row-sync-project-command.store.js";
 import type { ProjectDeviceStructureProjectCommandStore } from "../ports/project-device-structure-project-command.store.js";
 import type { ProjectRevisionSource } from "../ports/project-revision.store.js";
+import type { ProjectStateRestoreCommandStore } from "../ports/project-state-restore-command.store.js";
 
 interface DispatchProjectCommandInput {
   projectId: string;
@@ -84,7 +89,7 @@ interface DispatchProjectCommandInput {
   description?: string;
   actorId?: string;
   historyTargetChangeSetId?: string;
-  command: SerializedProjectCommand;
+  command: SerializedProjectCommand<unknown>;
 }
 
 export class ProjectCommandService implements ProjectCommandExecutor {
@@ -99,6 +104,7 @@ export class ProjectCommandService implements ProjectCommandExecutor {
     private readonly projectDeviceStructureStore: ProjectDeviceStructureProjectCommandStore,
     private readonly projectDeviceStore: ProjectDeviceProjectCommandStore,
     private readonly projectDeviceRowSyncStore: ProjectDeviceRowSyncProjectCommandStore,
+    private readonly projectStateRestoreStore: ProjectStateRestoreCommandStore,
     private readonly historyStore: ProjectHistoryStore
   ) {}
 
@@ -107,6 +113,11 @@ export class ProjectCommandService implements ProjectCommandExecutor {
   ): ExecutedProjectCommand {
     assertExpectedRevision(input.expectedRevision);
     assertSerializedProjectCommand(input.command);
+    if (input.command.type === projectStateRestoreCommandType) {
+      throw new Error(
+        "Project state restore commands require a stored server snapshot."
+      );
+    }
     return this.dispatch({
       ...input,
       source: "user",
@@ -114,6 +125,18 @@ export class ProjectCommandService implements ProjectCommandExecutor {
     });
   }
 
+  executeRestore(
+    input: ExecuteUserProjectCommandInput
+  ): ExecutedProjectCommand {
+    assertExpectedRevision(input.expectedRevision);
+    assertProjectStateRestoreCommand(input.command);
+    return this.dispatch({
+      ...input,
+      source: "restore",
+      command: input.command,
+    });
+  }
+
   undo(
     input: ExecuteProjectHistoryCommandInput
   ): ExecutedProjectCommand {
@@ -271,6 +294,13 @@ export class ProjectCommandService implements ProjectCommandExecutor {
           command: input.command,
         }).revision;
       }
+      case projectStateRestoreCommandType: {
+        assertProjectStateRestoreCommand(input.command);
+        return this.projectStateRestoreStore.execute({
+          ...input,
+          command: input.command,
+        }).revision;
+      }
       default:
         throw new Error(
           `Unsupported project command type: ${input.command.type}.`