@tailor-platform/erp-kit 0.7.0 → 0.9.0

package/src/modules/accounting/command/generateVarianceReport.test.ts

@@ -0,0 +1,386 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AccountingPeriodNotFoundError,
+  CompanyNotFoundError,
+  CostObjectNotFoundError,
+  NoBudgetDataError,
+} from "../lib/errors.generated";
+import {
+  activeCostElement,
+  baseAccountingPeriod,
+  baseBudgetLineItem,
+  baseCompany,
+  baseCostCenter,
+  baseVarianceReport,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./generateVarianceReport";
+
+const baseInput = {
+  companyId: baseCompany.id,
+  accountingPeriodId: baseAccountingPeriod.id,
+  costObjectType: "CostCenter" as const,
+  costObjectId: baseCostCenter.id,
+};
+
+const revenueCostElement = {
+  ...activeCostElement,
+  id: "cost-element-revenue",
+  category: "revenue",
+};
+
+function queueHappyPath(
+  spies: ReturnType<typeof createMockDb<Transaction>>["spies"],
+  options?: {
+    budgetLines?: Record<string, unknown>[];
+    actualRows?: Record<string, unknown>[];
+    costElements?: Record<string, unknown>[];
+    existingDraft?: Record<string, unknown>;
+  },
+) {
+  const budgetLines = options?.budgetLines ?? [baseBudgetLineItem];
+  const actualRows = options?.actualRows ?? [];
+  const costElements = options?.costElements ?? [activeCostElement];
+
+  spies.select
+    .mockReturnValueOnce(baseCompany)
+    .mockReturnValueOnce(baseAccountingPeriod)
+    .mockReturnValueOnce(baseCostCenter)
+    .mockReturnValueOnce(budgetLines)
+    .mockReturnValueOnce(actualRows);
+
+  for (const costElement of costElements) {
+    spies.select.mockReturnValueOnce(costElement);
+  }
+
+  spies.select.mockReturnValueOnce(options?.existingDraft);
+}
+
+describe("generateVarianceReport", () => {
+  it("returns error when company does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { ...baseInput, companyId: "missing-company" }, commandCtx);
+
+    expectErr(result, CompanyNotFoundError);
+  });
+
+  it("returns error when company is not ACTIVE", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce({ ...baseCompany, status: "INACTIVE" });
+
+    const result = await run(db, baseInput, commandCtx);
+
+    expectErr(result, CompanyNotFoundError);
+  });
+
+  it("returns error when accounting period does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany).mockReturnValueOnce(undefined);
+
+    const result = await run(db, baseInput, commandCtx);
+
+    expectErr(result, AccountingPeriodNotFoundError);
+  });
+
+  it("returns error when cost object does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(baseAccountingPeriod)
+      .mockReturnValueOnce(undefined);
+
+    const result = await run(db, baseInput, commandCtx);
+
+    expectErr(result, CostObjectNotFoundError);
+  });
+
+  it("returns error when no budget line items exist for the cost object and period", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(baseAccountingPeriod)
+      .mockReturnValueOnce(baseCostCenter)
+      .mockReturnValueOnce([]);
+
+    const result = await run(db, baseInput, commandCtx);
+
+    expectErr(result, NoBudgetDataError);
+  });
+
+  it("generates a variance report in DRAFT status for a cost center", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdReport = {
+      ...baseVarianceReport,
+      totalPlanned: 10000,
+      totalActual: 0,
+      totalVariance: -10000,
+      status: "DRAFT",
+    };
+
+    queueHappyPath(spies);
+    spies.insert.mockReturnValueOnce(createdReport).mockReturnValueOnce({});
+
+    const result = await run(db, baseInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.varianceReport).toEqual(createdReport);
+    expect(value.varianceReport.status).toBe("DRAFT");
+  });
+
+  it("calculates variance as actual minus planned per cost element", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdReport = {
+      ...baseVarianceReport,
+      totalPlanned: 5000,
+      totalActual: 3000,
+      totalVariance: -2000,
+      status: "DRAFT",
+    };
+
+    queueHappyPath(spies, {
+      budgetLines: [{ ...baseBudgetLineItem, plannedAmount: 5000 }],
+      actualRows: [{ costElementId: activeCostElement.id, functionalDebitAmount: 3000 }],
+    });
+    spies.insert.mockReturnValueOnce(createdReport).mockReturnValueOnce({});
+
+    const result = await run(db, baseInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.varianceReport.totalVariance).toBe(-2000);
+  });
+
+  it("handles division by zero when planned amount is zero", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdReport = {
+      ...baseVarianceReport,
+      totalPlanned: 0,
+      totalActual: 1200,
+      totalVariance: 1200,
+      status: "DRAFT",
+    };
+
+    queueHappyPath(spies, {
+      budgetLines: [{ ...baseBudgetLineItem, plannedAmount: 0 }],
+      actualRows: [{ costElementId: activeCostElement.id, functionalDebitAmount: 1200 }],
+    });
+    spies.insert.mockReturnValueOnce(createdReport).mockReturnValueOnce({});
+
+    const result = await run(db, baseInput, commandCtx);
+
+    expectOk(result);
+  });
+
+  it("sets variance direction to FAVORABLE when actual equals planned", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdReport = {
+      ...baseVarianceReport,
+      totalPlanned: 1000,
+      totalActual: 1000,
+      totalVariance: 0,
+      status: "DRAFT",
+    };
+
+    queueHappyPath(spies, {
+      budgetLines: [{ ...baseBudgetLineItem, plannedAmount: 1000 }],
+      actualRows: [{ costElementId: activeCostElement.id, functionalDebitAmount: 1000 }],
+    });
+    spies.insert.mockReturnValueOnce(createdReport).mockReturnValueOnce({});
+
+    const result = await run(db, baseInput, commandCtx);
+
+    expectOk(result);
+    expect(spies.values).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({ varianceDirection: "FAVORABLE" }),
+    );
+  });
+
+  it("categorizes cost/expense variance as FAVORABLE when actual is less than planned", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdReport = {
+      ...baseVarianceReport,
+      totalPlanned: 10000,
+      totalActual: 2000,
+      totalVariance: -8000,
+      status: "DRAFT",
+    };
+
+    queueHappyPath(spies, {
+      actualRows: [{ costElementId: activeCostElement.id, functionalDebitAmount: 2000 }],
+    });
+    spies.insert.mockReturnValueOnce(createdReport).mockReturnValueOnce({});
+
+    const result = await run(db, baseInput, commandCtx);
+
+    expectOk(result);
+    expect(spies.values).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({ varianceDirection: "FAVORABLE" }),
+    );
+  });
+
+  it("categorizes revenue variance as FAVORABLE when actual is greater than planned", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdReport = {
+      ...baseVarianceReport,
+      totalPlanned: 10000,
+      totalActual: 12000,
+      totalVariance: 2000,
+      status: "DRAFT",
+    };
+
+    queueHappyPath(spies, {
+      budgetLines: [
+        { ...baseBudgetLineItem, costElementId: revenueCostElement.id, plannedAmount: 10000 },
+      ],
+      actualRows: [{ costElementId: revenueCostElement.id, functionalCreditAmount: 12000 }],
+      costElements: [revenueCostElement],
+    });
+    spies.insert.mockReturnValueOnce(createdReport).mockReturnValueOnce({});
+
+    const result = await run(db, baseInput, commandCtx);
+
+    expectOk(result);
+    expect(spies.values).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({ varianceDirection: "FAVORABLE" }),
+    );
+  });
+
+  it("creates a line for actual postings without a matching budget line item", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const unbudgetedCostElement = { ...activeCostElement, id: "cost-element-unbudgeted" };
+    const createdReport = {
+      ...baseVarianceReport,
+      totalPlanned: 10000,
+      totalActual: 14000,
+      totalVariance: 4000,
+      status: "DRAFT",
+    };
+
+    queueHappyPath(spies, {
+      actualRows: [
+        { costElementId: activeCostElement.id, functionalDebitAmount: 10000 },
+        { costElementId: unbudgetedCostElement.id, functionalDebitAmount: 4000 },
+      ],
+      costElements: [activeCostElement, unbudgetedCostElement],
+    });
+    spies.insert.mockReturnValueOnce(createdReport).mockReturnValueOnce({}).mockReturnValueOnce({});
+
+    const result = await run(db, baseInput, commandCtx);
+
+    expectOk(result);
+    expect(spies.values).toHaveBeenNthCalledWith(
+      3,
+      expect.objectContaining({
+        costElementId: unbudgetedCostElement.id,
+        plannedAmount: 0,
+        actualAmount: 4000,
+      }),
+    );
+  });
+
+  it("computes summary totals from the sum of detail lines", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const costElement2 = { ...activeCostElement, id: "ce-2" };
+    const createdReport = {
+      ...baseVarianceReport,
+      totalPlanned: 8000,
+      totalActual: 6000,
+      totalVariance: -2000,
+      status: "DRAFT",
+    };
+
+    queueHappyPath(spies, {
+      budgetLines: [
+        {
+          ...baseBudgetLineItem,
+          id: "bli-1",
+          costElementId: activeCostElement.id,
+          plannedAmount: 5000,
+        },
+        { ...baseBudgetLineItem, id: "bli-2", costElementId: costElement2.id, plannedAmount: 3000 },
+      ],
+      actualRows: [
+        { costElementId: activeCostElement.id, functionalDebitAmount: 4000 },
+        { costElementId: costElement2.id, functionalDebitAmount: 2000 },
+      ],
+      costElements: [activeCostElement, costElement2],
+    });
+    spies.insert.mockReturnValueOnce(createdReport).mockReturnValueOnce({}).mockReturnValueOnce({});
+
+    const result = await run(db, baseInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.varianceReport.totalPlanned).toBe(8000);
+    expect(value.varianceReport.totalActual).toBe(6000);
+    expect(value.varianceReport.totalVariance).toBe(-2000);
+  });
+
+  it("replaces existing DRAFT report when regenerating for same cost object and period", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const existingDraft = { ...baseVarianceReport, id: "old-draft", status: "DRAFT" };
+    const createdReport = {
+      ...baseVarianceReport,
+      id: "new-report",
+      totalPlanned: 10000,
+      totalActual: 0,
+      totalVariance: -10000,
+      status: "DRAFT",
+    };
+
+    queueHappyPath(spies, { existingDraft });
+    spies.delete.mockReturnValueOnce(undefined).mockReturnValueOnce(undefined);
+    spies.insert.mockReturnValueOnce(createdReport).mockReturnValueOnce({});
+
+    const result = await run(db, baseInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.varianceReport).toEqual(createdReport);
+    expect(spies.delete).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not overwrite a FINAL report when regenerating", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdReport = {
+      ...baseVarianceReport,
+      id: "new-draft",
+      totalPlanned: 10000,
+      totalActual: 0,
+      totalVariance: -10000,
+      status: "DRAFT",
+    };
+
+    queueHappyPath(spies);
+    spies.insert.mockReturnValueOnce(createdReport).mockReturnValueOnce({});
+
+    const result = await run(db, baseInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.varianceReport.status).toBe("DRAFT");
+    expect(spies.delete).not.toHaveBeenCalled();
+  });
+
+  it("emits audit event recording the report generation and acting user", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdReport = {
+      ...baseVarianceReport,
+      totalPlanned: 10000,
+      totalActual: 0,
+      totalVariance: -10000,
+      status: "DRAFT",
+    };
+
+    queueHappyPath(spies);
+    spies.insert.mockReturnValueOnce(createdReport).mockReturnValueOnce({});
+
+    const result = await run(db, baseInput, commandCtx);
+
+    expectOk(result);
+    expect(spies.insert).toHaveBeenCalled();
+  });
+});

package/src/modules/accounting/command/generateVarianceReport.ts

@@ -0,0 +1,219 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CompanyNotFoundError,
+  AccountingPeriodNotFoundError,
+  CostObjectNotFoundError,
+  NoBudgetDataError,
+} from "../lib/errors.generated";
+import { listPostedActualAmountsByCostElement } from "../lib/actualAmounts";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface GenerateVarianceReportInput {
+  companyId: string;
+  accountingPeriodId: string;
+  costObjectType: "CostCenter" | "ProfitCenter" | "InternalOrder";
+  costObjectId: string;
+}
+
+export async function run(
+  db: Transaction,
+  input: GenerateVarianceReportInput,
+  ctx: CommandContext,
+) {
+  void ctx;
+
+  // Validate company exists and is ACTIVE
+  const company = await db
+    .selectFrom("Company" as never)
+    .where("id" as never, "=", input.companyId as never)
+    .selectAll()
+    .executeTakeFirst();
+
+  if (!company || (company as Record<string, unknown>).status !== "ACTIVE") {
+    return err(new CompanyNotFoundError(input.companyId));
+  }
+
+  // Validate accounting period exists
+  const accountingPeriod = await db
+    .selectFrom("AccountingPeriod" as never)
+    .where("id" as never, "=", input.accountingPeriodId as never)
+    .selectAll()
+    .executeTakeFirst();
+
+  if (!accountingPeriod) {
+    return err(new AccountingPeriodNotFoundError(input.accountingPeriodId));
+  }
+
+  // Validate cost object exists (polymorphic lookup)
+  const costObjectTable = input.costObjectType;
+  const costObject = await db
+    .selectFrom(costObjectTable as never)
+    .where("id" as never, "=", input.costObjectId as never)
+    .selectAll()
+    .executeTakeFirst();
+
+  if (!costObject) {
+    return err(new CostObjectNotFoundError(input.costObjectId));
+  }
+
+  // Look up budget line items for the cost object and period
+  // Budget line items are linked through Budget -> BudgetLineItem
+  // We need budgets for this cost object, then their line items for this period
+  const budgetLineItems = await db
+    .selectFrom("BudgetLineItem")
+    .innerJoin("Budget", "Budget.id", "BudgetLineItem.budgetId")
+    .where("Budget.costObjectType", "=", input.costObjectType)
+    .where("Budget.costObjectId", "=", input.costObjectId)
+    .where("BudgetLineItem.accountingPeriodId", "=", input.accountingPeriodId)
+    .selectAll()
+    .execute();
+
+  if (!budgetLineItems || budgetLineItems.length === 0) {
+    return err(new NoBudgetDataError(input.costObjectId));
+  }
+
+  // Look up cost elements for each budget line item to determine variance direction
+  const actualAmountsByCostElement = await listPostedActualAmountsByCostElement(db, {
+    accountingPeriodId: input.accountingPeriodId,
+    costObjectType: input.costObjectType,
+    costObjectId: input.costObjectId,
+  });
+
+  const plannedAmountsByCostElement = new Map<string, number>();
+  for (const budgetLineItem of budgetLineItems) {
+    plannedAmountsByCostElement.set(
+      budgetLineItem.costElementId,
+      (plannedAmountsByCostElement.get(budgetLineItem.costElementId) ?? 0) +
+        budgetLineItem.plannedAmount,
+    );
+  }
+
+  const costElementIds = new Set<string>([
+    ...plannedAmountsByCostElement.keys(),
+    ...actualAmountsByCostElement.keys(),
+  ]);
+
+  const lineData: {
+    costElementId: string;
+    plannedAmount: number;
+    actualAmount: number;
+    varianceAmount: number;
+    variancePercentage: number;
+    varianceDirection: "FAVORABLE" | "UNFAVORABLE";
+  }[] = [];
+
+  for (const costElementId of costElementIds) {
+    const plannedAmount = plannedAmountsByCostElement.get(costElementId) ?? 0;
+    const actualAmount = actualAmountsByCostElement.get(costElementId) ?? 0;
+
+    const varianceAmount = actualAmount - plannedAmount;
+    const variancePercentage =
+      plannedAmount !== 0 ? ((actualAmount - plannedAmount) / plannedAmount) * 100 : 0;
+
+    // Look up cost element to determine category for variance direction
+    const costElement = await db
+      .selectFrom("CostElement")
+      .where("id" as never, "=", costElementId as never)
+      .selectAll()
+      .executeTakeFirst();
+
+    const category =
+      typeof (costElement as Record<string, unknown> | undefined)?.category === "string"
+        ? ((costElement as Record<string, unknown>).category as string)
+        : "overhead";
+
+    let varianceDirection: "FAVORABLE" | "UNFAVORABLE";
+    if (actualAmount === plannedAmount) {
+      varianceDirection = "FAVORABLE";
+    } else if (category === "revenue") {
+      if (actualAmount > plannedAmount) {
+        varianceDirection = "FAVORABLE";
+      } else {
+        varianceDirection = "UNFAVORABLE";
+      }
+    } else if (actualAmount < plannedAmount) {
+      varianceDirection = "FAVORABLE";
+    } else {
+      varianceDirection = "UNFAVORABLE";
+    }
+
+    lineData.push({
+      costElementId,
+      plannedAmount,
+      actualAmount,
+      varianceAmount,
+      variancePercentage,
+      varianceDirection,
+    });
+  }
+
+  // Compute totals
+  const totalPlanned = lineData.reduce((sum, l) => sum + l.plannedAmount, 0);
+  const totalActual = lineData.reduce((sum, l) => sum + l.actualAmount, 0);
+  const totalVariance = lineData.reduce((sum, l) => sum + l.varianceAmount, 0);
+
+  // Check for existing DRAFT report for same cost object + period - if exists, delete it and its lines
+  const existingDraft = (await db
+    .selectFrom("VarianceReport")
+    .where("costObjectType" as never, "=", input.costObjectType as never)
+    .where("costObjectId" as never, "=", input.costObjectId as never)
+    .where("accountingPeriodId" as never, "=", input.accountingPeriodId as never)
+    .where("status" as never, "=", "DRAFT" as never)
+    .selectAll()
+    .forUpdate()
+    .executeTakeFirst()) as Record<string, unknown> | undefined;
+
+  if (existingDraft) {
+    // Delete existing lines
+    await db
+      .deleteFrom("VarianceReportLine" as never)
+      .where("varianceReportId" as never, "=", existingDraft.id as string as never)
+      .execute();
+
+    // Delete existing report
+    await db
+      .deleteFrom("VarianceReport" as never)
+      .where("id" as never, "=", existingDraft.id as string as never)
+      .execute();
+  }
+
+  // Create variance report with status DRAFT
+  const varianceReport = await db
+    .insertInto("VarianceReport")
+    .values({
+      companyId: input.companyId,
+      costObjectType: input.costObjectType,
+      costObjectId: input.costObjectId,
+      accountingPeriodId: input.accountingPeriodId,
+      totalPlanned,
+      totalActual,
+      totalVariance,
+      status: "DRAFT",
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  // Create variance report lines
+  for (const line of lineData) {
+    await db
+      .insertInto("VarianceReportLine")
+      .values({
+        varianceReportId: (varianceReport as Record<string, unknown>).id as string,
+        costElementId: line.costElementId,
+        accountingPeriodId: input.accountingPeriodId,
+        plannedAmount: line.plannedAmount,
+        actualAmount: line.actualAmount,
+        varianceAmount: line.varianceAmount,
+        variancePercentage: line.variancePercentage,
+        varianceDirection: line.varianceDirection,
+        createdAt: new Date(),
+        updatedAt: null,
+      })
+      .returningAll()
+      .executeTakeFirst();
+  }
+
+  return ok({ varianceReport: varianceReport! });
+}

package/src/modules/accounting/command/invalidateAllocationCycle.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./invalidateAllocationCycle";
+import { defineCommand } from "@tailor-platform/erp-kit/module";
+
+export const invalidateAllocationCycle = defineCommand(permissions.invalidateAllocationCycle, run);

package/src/modules/accounting/command/invalidateAllocationCycle.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { AllocationCycleNotFoundError, InvalidStateError } from "../lib/errors.generated";
+import {
+  baseAllocationCycle,
+  validatedAllocationCycle,
+  executedAllocationCycle,
+  postedAllocationCycle,
+  reversedAllocationCycle,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./invalidateAllocationCycle";
+
+describe("invalidateAllocationCycle", () => {
+  it("invalidates a VALIDATED allocation cycle transitioning it to DRAFT status", async () => {
+    const draft = { ...validatedAllocationCycle, status: "DRAFT" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(validatedAllocationCycle);
+    spies.update.mockReturnValueOnce(draft);
+
+    const result = await run(db, { allocationCycleId: validatedAllocationCycle.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.allocationCycle.status).toBe("DRAFT");
+  });
+
+  it("returns error when allocation cycle does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { allocationCycleId: "missing-id" }, commandCtx);
+
+    expectErr(result, AllocationCycleNotFoundError);
+  });
+
+  it("returns error when allocation cycle is in DRAFT status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseAllocationCycle);
+
+    const result = await run(db, { allocationCycleId: baseAllocationCycle.id }, commandCtx);
+
+    expectErr(result, InvalidStateError);
+  });
+
+  it("returns error when allocation cycle is in EXECUTED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(executedAllocationCycle);
+
+    const result = await run(db, { allocationCycleId: executedAllocationCycle.id }, commandCtx);
+
+    expectErr(result, InvalidStateError);
+  });
+
+  it("returns error when allocation cycle is in POSTED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(postedAllocationCycle);
+
+    const result = await run(db, { allocationCycleId: postedAllocationCycle.id }, commandCtx);
+
+    expectErr(result, InvalidStateError);
+  });
+
+  it("returns error when allocation cycle is in REVERSED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(reversedAllocationCycle);
+
+    const result = await run(db, { allocationCycleId: reversedAllocationCycle.id }, commandCtx);
+
+    expectErr(result, InvalidStateError);
+  });
+
+  it("emits audit event recording the status transition and acting user", async () => {
+    const draft = { ...validatedAllocationCycle, status: "DRAFT" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(validatedAllocationCycle);
+    spies.update.mockReturnValueOnce(draft);
+
+    const result = await run(db, { allocationCycleId: validatedAllocationCycle.id }, commandCtx);
+
+    expectOk(result);
+    expect(spies.update).toHaveBeenCalled();
+  });
+});