Add atomic circuit update commands

src/db/repositories/circuit-project-command.repository.ts

@@ -0,0 +1,163 @@
+import { and, eq, ne } from "drizzle-orm";
+import {
+  assertCircuitUpdateProjectCommand,
+  createCircuitUpdateProjectCommand,
+  type CircuitUpdateField,
+  type CircuitUpdatePatch,
+  type CircuitUpdateValues,
+} from "../../domain/models/circuit-project-command.model.js";
+import type {
+  CircuitProjectCommandStore,
+  ExecuteCircuitUpdateCommandInput,
+} from "../../domain/ports/circuit-project-command.store.js";
+import type { AppDatabase } from "../database-context.js";
+import { circuitLists } from "../schema/circuit-lists.js";
+import { circuitSections } from "../schema/circuit-sections.js";
+import { circuits } from "../schema/circuits.js";
+import {
+  toCircuitPatchValues,
+  type CircuitPatchPersistenceInput,
+} from "./circuit.persistence.js";
+import { appendProjectRevision } from "./project-revision.persistence.js";
+
+type CircuitRow = typeof circuits.$inferSelect;
+
+export class CircuitProjectCommandRepository
+  implements CircuitProjectCommandStore
+{
+  constructor(private readonly database: AppDatabase) {}
+
+  executeUpdate(input: ExecuteCircuitUpdateCommandInput) {
+    assertCircuitUpdateProjectCommand(input.command);
+
+    return this.database.transaction((tx) => {
+      const current = tx
+        .select()
+        .from(circuits)
+        .where(eq(circuits.id, input.command.payload.circuitId))
+        .get();
+      if (!current) {
+        throw new Error("Invalid circuit id.");
+      }
+
+      const owningList = tx
+        .select({ id: circuitLists.id })
+        .from(circuitLists)
+        .where(
+          and(
+            eq(circuitLists.id, current.circuitListId),
+            eq(circuitLists.projectId, input.projectId)
+          )
+        )
+        .get();
+      if (!owningList) {
+        throw new Error("Circuit does not belong to project.");
+      }
+
+      const patch = Object.fromEntries(
+        input.command.payload.changes.map((change) => [
+          change.field,
+          change.value,
+        ])
+      ) as CircuitPatchPersistenceInput;
+      this.assertSectionInCircuitList(tx, current, patch.sectionId);
+      this.assertUniqueEquipmentIdentifier(
+        tx,
+        current,
+        patch.equipmentIdentifier
+      );
+
+      const inversePatch = Object.fromEntries(
+        input.command.payload.changes.map((change) => [
+          change.field,
+          getCircuitFieldValue(current, change.field),
+        ])
+      ) as CircuitUpdatePatch;
+      const inverse = createCircuitUpdateProjectCommand(
+        current.id,
+        inversePatch
+      );
+
+      const update = tx
+        .update(circuits)
+        .set(toCircuitPatchValues(patch))
+        .where(eq(circuits.id, current.id))
+        .run();
+      if (update.changes !== 1) {
+        throw new Error("Circuit changed before command execution.");
+      }
+
+      const revision = appendProjectRevision(tx, {
+        projectId: input.projectId,
+        expectedRevision: input.expectedRevision,
+        source: input.source,
+        description: input.description,
+        actorId: input.actorId,
+        forward: input.command,
+        inverse,
+      });
+
+      return { revision, inverse };
+    });
+  }
+
+  private assertSectionInCircuitList(
+    database: AppDatabase,
+    circuit: CircuitRow,
+    sectionId: string | undefined
+  ) {
+    if (sectionId === undefined || sectionId === circuit.sectionId) {
+      return;
+    }
+    const section = database
+      .select({ id: circuitSections.id })
+      .from(circuitSections)
+      .where(
+        and(
+          eq(circuitSections.id, sectionId),
+          eq(circuitSections.circuitListId, circuit.circuitListId)
+        )
+      )
+      .get();
+    if (!section) {
+      throw new Error("Section does not belong to circuit list.");
+    }
+  }
+
+  private assertUniqueEquipmentIdentifier(
+    database: AppDatabase,
+    circuit: CircuitRow,
+    equipmentIdentifier: string | undefined
+  ) {
+    if (
+      equipmentIdentifier === undefined ||
+      equipmentIdentifier === circuit.equipmentIdentifier
+    ) {
+      return;
+    }
+    const duplicate = database
+      .select({ id: circuits.id })
+      .from(circuits)
+      .where(
+        and(
+          eq(circuits.circuitListId, circuit.circuitListId),
+          eq(circuits.equipmentIdentifier, equipmentIdentifier),
+          ne(circuits.id, circuit.id)
+        )
+      )
+      .get();
+    if (duplicate) {
+      throw new Error("Duplicate equipmentIdentifier in circuit list.");
+    }
+  }
+}
+
+function getCircuitFieldValue<TField extends CircuitUpdateField>(
+  circuit: CircuitRow,
+  field: TField
+): CircuitUpdateValues[TField] {
+  if (field === "isReserve") {
+    return Boolean(circuit.isReserve) as CircuitUpdateValues[TField];
+  }
+  return circuit[field] as unknown as CircuitUpdateValues[TField];
+}

src/db/repositories/circuit.persistence.ts

@@ -19,6 +19,26 @@ export interface CircuitCreatePersistenceInput {
   isReserve?: boolean;
 }
 
+export interface CircuitPatchPersistenceInput {
+  sectionId?: string;
+  equipmentIdentifier?: string;
+  displayName?: string | null;
+  sortOrder?: number;
+  protectionType?: string | null;
+  protectionRatedCurrent?: number | null;
+  protectionCharacteristic?: string | null;
+  cableType?: string | null;
+  cableCrossSection?: string | null;
+  cableLength?: number | null;
+  voltage?: number | null;
+  controlRequirement?: string | null;
+  remark?: string | null;
+  rcdAssignment?: string | null;
+  terminalDesignation?: string | null;
+  status?: string | null;
+  isReserve?: boolean;
+}
+
 export function toCircuitCreateValues(id: string, input: CircuitCreatePersistenceInput) {
   return {
     id,
@@ -42,3 +62,41 @@ export function toCircuitCreateValues(id: string, input: CircuitCreatePersistenc
     remark: input.remark ?? null,
   };
 }
+
+export function toCircuitPatchValues(input: CircuitPatchPersistenceInput) {
+  const values: Partial<ReturnType<typeof toCircuitCreateValues>> = {};
+  const has = (field: keyof CircuitPatchPersistenceInput) =>
+    Object.prototype.hasOwnProperty.call(input, field);
+
+  if (input.sectionId !== undefined) values.sectionId = input.sectionId;
+  if (input.equipmentIdentifier !== undefined) {
+    values.equipmentIdentifier = input.equipmentIdentifier;
+  }
+  if (has("displayName")) values.displayName = input.displayName ?? null;
+  if (input.sortOrder !== undefined) values.sortOrder = input.sortOrder;
+  if (has("protectionType")) values.protectionType = input.protectionType ?? null;
+  if (has("protectionRatedCurrent")) {
+    values.protectionRatedCurrent = input.protectionRatedCurrent ?? null;
+  }
+  if (has("protectionCharacteristic")) {
+    values.protectionCharacteristic = input.protectionCharacteristic ?? null;
+  }
+  if (has("cableType")) values.cableType = input.cableType ?? null;
+  if (has("cableCrossSection")) {
+    values.cableCrossSection = input.cableCrossSection ?? null;
+  }
+  if (has("cableLength")) values.cableLength = input.cableLength ?? null;
+  if (has("rcdAssignment")) values.rcdAssignment = input.rcdAssignment ?? null;
+  if (has("terminalDesignation")) {
+    values.terminalDesignation = input.terminalDesignation ?? null;
+  }
+  if (has("voltage")) values.voltage = input.voltage ?? null;
+  if (has("controlRequirement")) {
+    values.controlRequirement = input.controlRequirement ?? null;
+  }
+  if (has("status")) values.status = input.status ?? null;
+  if (input.isReserve !== undefined) values.isReserve = input.isReserve ? 1 : 0;
+  if (has("remark")) values.remark = input.remark ?? null;
+
+  return values;
+}

src/db/repositories/circuit.repository.ts

@@ -4,67 +4,19 @@ import { db } from "../client.js";
 import { circuits } from "../schema/circuits.js";
 import {
   toCircuitCreateValues,
+  toCircuitPatchValues,
   type CircuitCreatePersistenceInput,
+  type CircuitPatchPersistenceInput,
 } from "./circuit.persistence.js";
 
-export type { CircuitCreatePersistenceInput } from "./circuit.persistence.js";
-export { toCircuitCreateValues } from "./circuit.persistence.js";
-
-export interface CircuitPatchPersistenceInput {
-  sectionId?: string;
-  equipmentIdentifier?: string;
-  displayName?: string;
-  sortOrder?: number;
-  protectionType?: string;
-  protectionRatedCurrent?: number;
-  protectionCharacteristic?: string;
-  cableType?: string;
-  cableCrossSection?: string;
-  cableLength?: number;
-  voltage?: number;
-  controlRequirement?: string;
-  remark?: string;
-  rcdAssignment?: string;
-  terminalDesignation?: string;
-  status?: string;
-  isReserve?: boolean;
-}
-
-function toCircuitPatchValues(input: CircuitPatchPersistenceInput) {
-  const values: Partial<typeof circuits.$inferInsert> = {};
-  const has = (field: keyof CircuitPatchPersistenceInput) =>
-    Object.prototype.hasOwnProperty.call(input, field);
-
-  if (input.sectionId !== undefined) values.sectionId = input.sectionId;
-  if (input.equipmentIdentifier !== undefined) {
-    values.equipmentIdentifier = input.equipmentIdentifier;
-  }
-  if (has("displayName")) values.displayName = input.displayName ?? null;
-  if (input.sortOrder !== undefined) values.sortOrder = input.sortOrder;
-  if (has("protectionType")) values.protectionType = input.protectionType ?? null;
-  if (has("protectionRatedCurrent")) {
-    values.protectionRatedCurrent = input.protectionRatedCurrent ?? null;
-  }
-  if (has("protectionCharacteristic")) {
-    values.protectionCharacteristic = input.protectionCharacteristic ?? null;
-  }
-  if (has("cableType")) values.cableType = input.cableType ?? null;
-  if (has("cableCrossSection")) values.cableCrossSection = input.cableCrossSection ?? null;
-  if (has("cableLength")) values.cableLength = input.cableLength ?? null;
-  if (has("rcdAssignment")) values.rcdAssignment = input.rcdAssignment ?? null;
-  if (has("terminalDesignation")) {
-    values.terminalDesignation = input.terminalDesignation ?? null;
-  }
-  if (has("voltage")) values.voltage = input.voltage ?? null;
-  if (has("controlRequirement")) {
-    values.controlRequirement = input.controlRequirement ?? null;
-  }
-  if (has("status")) values.status = input.status ?? null;
-  if (input.isReserve !== undefined) values.isReserve = input.isReserve ? 1 : 0;
-  if (has("remark")) values.remark = input.remark ?? null;
-
-  return values;
-}
+export type {
+  CircuitCreatePersistenceInput,
+  CircuitPatchPersistenceInput,
+} from "./circuit.persistence.js";
+export {
+  toCircuitCreateValues,
+  toCircuitPatchValues,
+} from "./circuit.persistence.js";
 
 export class CircuitRepository {
   async findById(circuitId: string) {

src/db/repositories/project-revision.persistence.ts

@@ -0,0 +1,94 @@
+import crypto from "node:crypto";
+import { and, eq } from "drizzle-orm";
+import { ProjectRevisionConflictError } from "../../domain/errors/project-revision-conflict.error.js";
+import { serializeProjectCommand } from "../../domain/models/project-command.model.js";
+import type {
+  AppendProjectRevisionInput,
+  AppendedProjectRevision,
+} from "../../domain/ports/project-revision.store.js";
+import type { AppDatabase } from "../database-context.js";
+import { projectChangeSets } from "../schema/project-change-sets.js";
+import { projectRevisions } from "../schema/project-revisions.js";
+import { projects } from "../schema/projects.js";
+
+export function appendProjectRevision(
+  database: AppDatabase,
+  input: AppendProjectRevisionInput
+): AppendedProjectRevision {
+  validateInput(input);
+
+  const forwardPayloadJson = serializeProjectCommand(input.forward);
+  const inversePayloadJson = serializeProjectCommand(input.inverse);
+  const revisionId = crypto.randomUUID();
+  const changeSetId = crypto.randomUUID();
+  const revisionNumber = input.expectedRevision + 1;
+  const createdAtIso = new Date().toISOString();
+
+  const revisionUpdate = database
+    .update(projects)
+    .set({ currentRevision: revisionNumber })
+    .where(
+      and(
+        eq(projects.id, input.projectId),
+        eq(projects.currentRevision, input.expectedRevision)
+      )
+    )
+    .run();
+
+  if (revisionUpdate.changes !== 1) {
+    const current = database
+      .select({ currentRevision: projects.currentRevision })
+      .from(projects)
+      .where(eq(projects.id, input.projectId))
+      .get();
+    throw new ProjectRevisionConflictError(
+      input.projectId,
+      input.expectedRevision,
+      current?.currentRevision ?? null
+    );
+  }
+
+  database
+    .insert(projectRevisions)
+    .values({
+      id: revisionId,
+      projectId: input.projectId,
+      revisionNumber,
+      createdAtIso,
+      actorId: input.actorId,
+      source: input.source,
+      description: input.description,
+    })
+    .run();
+
+  database
+    .insert(projectChangeSets)
+    .values({
+      id: changeSetId,
+      projectRevisionId: revisionId,
+      commandType: input.forward.type,
+      payloadSchemaVersion: input.forward.schemaVersion,
+      forwardPayloadJson,
+      inversePayloadJson,
+    })
+    .run();
+
+  return {
+    revisionId,
+    changeSetId,
+    projectId: input.projectId,
+    revisionNumber,
+    createdAtIso,
+  };
+}
+
+function validateInput(input: AppendProjectRevisionInput) {
+  if (!Number.isSafeInteger(input.expectedRevision) || input.expectedRevision < 0) {
+    throw new Error("Expected project revision must be a non-negative integer.");
+  }
+  if (input.forward.schemaVersion !== input.inverse.schemaVersion) {
+    throw new Error(
+      "Forward and inverse project commands require the same schema version."
+    );
+  }
+}

src/db/repositories/project-revision.repository.ts

@@ -1,30 +1,15 @@
-import crypto from "node:crypto";
-import { and, eq } from "drizzle-orm";
-import { serializeProjectCommand } from "../../domain/models/project-command.model.js";
+import { eq } from "drizzle-orm";
+import { ProjectRevisionConflictError } from "../../domain/errors/project-revision-conflict.error.js";
 import type {
   AppendProjectRevisionInput,
   AppendedProjectRevision,
   ProjectRevisionStore,
 } from "../../domain/ports/project-revision.store.js";
 import type { AppDatabase } from "../database-context.js";
-import { projectChangeSets } from "../schema/project-change-sets.js";
-import { projectRevisions } from "../schema/project-revisions.js";
 import { projects } from "../schema/projects.js";
+import { appendProjectRevision } from "./project-revision.persistence.js";
 
-export class ProjectRevisionConflictError extends Error {
-  constructor(
-    readonly projectId: string,
-    readonly expectedRevision: number,
-    readonly actualRevision: number | null
-  ) {
-    super(
-      actualRevision === null
-        ? `Project ${projectId} does not exist.`
-        : `Project ${projectId} is at revision ${actualRevision}, expected ${expectedRevision}.`
-    );
-    this.name = "ProjectRevisionConflictError";
-  }
-}
+export { ProjectRevisionConflictError };
 
 export class ProjectRevisionRepository implements ProjectRevisionStore {
   constructor(private readonly database: AppDatabase) {}
@@ -39,83 +24,8 @@ export class ProjectRevisionRepository implements ProjectRevisionStore {
   }
 
   append(input: AppendProjectRevisionInput): AppendedProjectRevision {
-    this.validateInput(input);
-
-    const forwardPayloadJson = serializeProjectCommand(input.forward);
-    const inversePayloadJson = serializeProjectCommand(input.inverse);
-    const revisionId = crypto.randomUUID();
-    const changeSetId = crypto.randomUUID();
-    const revisionNumber = input.expectedRevision + 1;
-    const createdAtIso = new Date().toISOString();
-
-    return this.database.transaction((tx) => {
-      const revisionUpdate = tx
-        .update(projects)
-        .set({ currentRevision: revisionNumber })
-        .where(
-          and(
-            eq(projects.id, input.projectId),
-            eq(projects.currentRevision, input.expectedRevision)
-          )
-        )
-        .run();
-
-      if (revisionUpdate.changes !== 1) {
-        const current = tx
-          .select({ currentRevision: projects.currentRevision })
-          .from(projects)
-          .where(eq(projects.id, input.projectId))
-          .get();
-        throw new ProjectRevisionConflictError(
-          input.projectId,
-          input.expectedRevision,
-          current?.currentRevision ?? null
-        );
-      }
-
-      tx.insert(projectRevisions)
-        .values({
-          id: revisionId,
-          projectId: input.projectId,
-          revisionNumber,
-          createdAtIso,
-          actorId: input.actorId,
-          source: input.source,
-          description: input.description,
-        })
-        .run();
-
-      tx.insert(projectChangeSets)
-        .values({
-          id: changeSetId,
-          projectRevisionId: revisionId,
-          commandType: input.forward.type,
-          payloadSchemaVersion: input.forward.schemaVersion,
-          forwardPayloadJson,
-          inversePayloadJson,
-        })
-        .run();
-
-      return {
-        revisionId,
-        changeSetId,
-        projectId: input.projectId,
-        revisionNumber,
-        createdAtIso,
-      };
-    });
-  }
-
-  private validateInput(input: AppendProjectRevisionInput) {
-    if (!Number.isSafeInteger(input.expectedRevision) || input.expectedRevision < 0) {
-      throw new Error("Expected project revision must be a non-negative integer.");
-    }
-    if (
-      input.forward.schemaVersion !== input.inverse.schemaVersion
-    ) {
-      throw new Error(
-        "Forward and inverse project commands require the same schema version."
-      );
-    }
+    return this.database.transaction((tx) =>
+      appendProjectRevision(tx, input)
+    );
   }
 }

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

@@ -0,0 +1,14 @@
+export class ProjectRevisionConflictError extends Error {
+  constructor(
+    readonly projectId: string,
+    readonly expectedRevision: number,
+    readonly actualRevision: number | null
+  ) {
+    super(
+      actualRevision === null
+        ? `Project ${projectId} does not exist.`
+        : `Project ${projectId} is at revision ${actualRevision}, expected ${expectedRevision}.`
+    );
+    this.name = "ProjectRevisionConflictError";
+  }
+}

src/domain/models/circuit-project-command.model.ts

@@ -0,0 +1,168 @@
+import type { SerializedProjectCommand } from "./project-command.model.js";
+
+export const circuitUpdateCommandType = "circuit.update" as const;
+export const circuitUpdateCommandSchemaVersion = 1 as const;
+
+export interface CircuitUpdateValues {
+  sectionId: string;
+  equipmentIdentifier: string;
+  displayName: string | null;
+  sortOrder: number;
+  protectionType: string | null;
+  protectionRatedCurrent: number | null;
+  protectionCharacteristic: string | null;
+  cableType: string | null;
+  cableCrossSection: string | null;
+  cableLength: number | null;
+  rcdAssignment: string | null;
+  terminalDesignation: string | null;
+  voltage: number | null;
+  controlRequirement: string | null;
+  status: string | null;
+  isReserve: boolean;
+  remark: string | null;
+}
+
+export type CircuitUpdateField = keyof CircuitUpdateValues;
+export type CircuitUpdatePatch = Partial<CircuitUpdateValues>;
+
+export interface CircuitUpdateFieldChange<
+  TField extends CircuitUpdateField = CircuitUpdateField,
+> {
+  field: TField;
+  value: CircuitUpdateValues[TField];
+}
+
+export interface CircuitUpdateCommandPayload {
+  circuitId: string;
+  changes: CircuitUpdateFieldChange[];
+}
+
+export interface CircuitUpdateProjectCommand
+  extends SerializedProjectCommand<CircuitUpdateCommandPayload> {
+  schemaVersion: typeof circuitUpdateCommandSchemaVersion;
+  type: typeof circuitUpdateCommandType;
+}
+
+export function createCircuitUpdateProjectCommand(
+  circuitId: string,
+  patch: CircuitUpdatePatch
+): CircuitUpdateProjectCommand {
+  const changes = Object.entries(patch).map(([field, value]) => ({
+    field: field as CircuitUpdateField,
+    value,
+  })) as CircuitUpdateFieldChange[];
+  const command: CircuitUpdateProjectCommand = {
+    schemaVersion: circuitUpdateCommandSchemaVersion,
+    type: circuitUpdateCommandType,
+    payload: { circuitId, changes },
+  };
+  assertCircuitUpdateProjectCommand(command);
+  return command;
+}
+
+export function assertCircuitUpdateProjectCommand(
+  command: SerializedProjectCommand<unknown>
+): asserts command is CircuitUpdateProjectCommand {
+  if (
+    command.schemaVersion !== circuitUpdateCommandSchemaVersion ||
+    command.type !== circuitUpdateCommandType
+  ) {
+    throw new Error("Unsupported circuit update command.");
+  }
+  if (!isPlainObject(command.payload)) {
+    throw new Error("Circuit update payload must be an object.");
+  }
+  const circuitId = command.payload.circuitId;
+  const changes = command.payload.changes;
+  if (typeof circuitId !== "string" || !circuitId.trim()) {
+    throw new Error("Circuit update command requires a circuit id.");
+  }
+  if (!Array.isArray(changes) || changes.length === 0) {
+    throw new Error("Circuit update command requires at least one change.");
+  }
+
+  const seenFields = new Set<string>();
+  for (const change of changes) {
+    if (!isPlainObject(change) || typeof change.field !== "string") {
+      throw new Error("Circuit update command contains an invalid change.");
+    }
+    if (!isCircuitUpdateField(change.field) || seenFields.has(change.field)) {
+      throw new Error("Circuit update command contains an invalid or duplicate field.");
+    }
+    assertCircuitUpdateFieldValue(change.field, change.value);
+    seenFields.add(change.field);
+  }
+}
+
+function assertCircuitUpdateFieldValue(
+  field: CircuitUpdateField,
+  value: unknown
+) {
+  if (field === "sectionId" || field === "equipmentIdentifier") {
+    if (typeof value !== "string" || !value.trim()) {
+      throw new Error(`${field} must be a non-empty string.`);
+    }
+    return;
+  }
+  if (field === "sortOrder") {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+      throw new Error("sortOrder must be a finite number.");
+    }
+    return;
+  }
+  if (field === "isReserve") {
+    if (typeof value !== "boolean") {
+      throw new Error("isReserve must be a boolean.");
+    }
+    return;
+  }
+  if (
+    field === "protectionRatedCurrent" ||
+    field === "cableLength" ||
+    field === "voltage"
+  ) {
+    if (value === null) {
+      return;
+    }
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+      throw new Error(`${field} must be a finite number or null.`);
+    }
+    if (
+      (field === "voltage" && value <= 0) ||
+      (field !== "voltage" && value < 0)
+    ) {
+      throw new Error(`${field} is outside its allowed range.`);
+    }
+    return;
+  }
+  if (value !== null && typeof value !== "string") {
+    throw new Error(`${field} must be a string or null.`);
+  }
+}
+
+function isCircuitUpdateField(value: string): value is CircuitUpdateField {
+  return [
+    "sectionId",
+    "equipmentIdentifier",
+    "displayName",
+    "sortOrder",
+    "protectionType",
+    "protectionRatedCurrent",
+    "protectionCharacteristic",
+    "cableType",
+    "cableCrossSection",
+    "cableLength",
+    "rcdAssignment",
+    "terminalDesignation",
+    "voltage",
+    "controlRequirement",
+    "status",
+    "isReserve",
+    "remark",
+  ].includes(value);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

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

@@ -6,18 +6,22 @@ export type ProjectCommandJsonValue =
   | ProjectCommandJsonValue[]
   | { [key: string]: ProjectCommandJsonValue };
 
-export interface SerializedProjectCommand {
+export interface SerializedProjectCommand<TPayload = ProjectCommandJsonValue> {
   schemaVersion: number;
   type: string;
-  payload: ProjectCommandJsonValue;
+  payload: TPayload;
 }
 
-export function serializeProjectCommand(command: SerializedProjectCommand): string {
+export function serializeProjectCommand(
+  command: SerializedProjectCommand<unknown>
+): string {
   assertSerializedProjectCommand(command);
   return JSON.stringify(command);
 }
 
-export function deserializeProjectCommand(serialized: string): SerializedProjectCommand {
+export function deserializeProjectCommand(
+  serialized: string
+): SerializedProjectCommand<ProjectCommandJsonValue> {
   const parsed: unknown = JSON.parse(serialized);
   assertSerializedProjectCommand(parsed);
   return parsed;

src/domain/ports/circuit-project-command.store.ts

@@ -0,0 +1,25 @@
+import type { CircuitUpdateProjectCommand } from "../models/circuit-project-command.model.js";
+import type {
+  AppendedProjectRevision,
+  ProjectRevisionSource,
+} from "./project-revision.store.js";
+
+export interface ExecuteCircuitUpdateCommandInput {
+  projectId: string;
+  expectedRevision: number;
+  source: ProjectRevisionSource;
+  description?: string;
+  actorId?: string;
+  command: CircuitUpdateProjectCommand;
+}
+
+export interface ExecutedCircuitUpdateCommand {
+  revision: AppendedProjectRevision;
+  inverse: CircuitUpdateProjectCommand;
+}
+
+export interface CircuitProjectCommandStore {
+  executeUpdate(
+    input: ExecuteCircuitUpdateCommandInput
+  ): ExecutedCircuitUpdateCommand;
+}

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

@@ -13,8 +13,8 @@ export interface AppendProjectRevisionInput {
   source: ProjectRevisionSource;
   description?: string;
   actorId?: string;
-  forward: SerializedProjectCommand;
-  inverse: SerializedProjectCommand;
+  forward: SerializedProjectCommand<unknown>;
+  inverse: SerializedProjectCommand<unknown>;
 }
 
 export interface AppendedProjectRevision {

src/server/composition/project-command-stores.ts

@@ -0,0 +1,4 @@
+import { db } from "../../db/client.js";
+import { CircuitProjectCommandRepository } from "../../db/repositories/circuit-project-command.repository.js";
+
+export const circuitProjectCommandStore = new CircuitProjectCommandRepository(db);