@tailor-platform/erp-kit 0.7.0 → 0.8.0

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

@@ -0,0 +1,65 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AllocationCycleNotFoundError,
+  InvalidStateError,
+  PeriodNotOpenError,
+} from "../lib/errors.generated";
+import { createAllocationPostingEntries } from "../lib/allocationPosting";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface PostAllocationCycleInput {
+  allocationCycleId: string;
+}
+
+export async function run(db: Transaction, input: PostAllocationCycleInput, ctx: CommandContext) {
+  void ctx;
+
+  // Validate allocation cycle exists
+  const cycle = await db
+    .selectFrom("AllocationCycle")
+    .where("id", "=", input.allocationCycleId)
+    .selectAll()
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!cycle) {
+    return err(new AllocationCycleNotFoundError(input.allocationCycleId));
+  }
+
+  // Validate status is EXECUTED
+  if (cycle.status !== "EXECUTED") {
+    return err(new InvalidStateError(input.allocationCycleId));
+  }
+
+  // Validate accounting period is OPEN or FUTURE_ENTERABLE
+  const accountingPeriod = await db
+    .selectFrom("AccountingPeriod" as never)
+    .where("id" as never, "=", cycle.accountingPeriodId as never)
+    .selectAll()
+    .executeTakeFirst();
+
+  const periodStatus = (accountingPeriod as Record<string, unknown>)?.status;
+  if (periodStatus !== "OPEN" && periodStatus !== "FUTURE_ENTERABLE") {
+    return err(new PeriodNotOpenError(input.allocationCycleId));
+  }
+
+  const allocationResults = await db
+    .selectFrom("AllocationResult")
+    .selectAll()
+    .where("allocationCycleId", "=", cycle.id)
+    .execute();
+
+  await createAllocationPostingEntries(db, cycle, allocationResults);
+
+  const allocationCycle = await db
+    .updateTable("AllocationCycle")
+    .set({
+      status: "POSTED",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", input.allocationCycleId)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ allocationCycle: allocationCycle! });
+}

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

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

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

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { CostElementNotFoundError, InvalidStateError } from "../lib/errors.generated";
+import { baseCostElement, activeCostElement, inactiveCostElement } from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./reactivateCostElement";
+
+describe("reactivateCostElement", () => {
+  it("reactivates an INACTIVE cost element transitioning it to ACTIVE status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(inactiveCostElement);
+    const updated = { ...inactiveCostElement, status: "ACTIVE" };
+    spies.update.mockReturnValueOnce(updated);
+
+    const result = await run(db, { costElementId: inactiveCostElement.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.costElement.status).toBe("ACTIVE");
+  });
+
+  it("returns error when cost element does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { costElementId: "missing" }, commandCtx);
+
+    expectErr(result, CostElementNotFoundError);
+  });
+
+  it("returns error when cost element is in DRAFT status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCostElement);
+
+    const result = await run(db, { costElementId: baseCostElement.id }, commandCtx);
+
+    expectErr(result, InvalidStateError);
+  });
+
+  it("returns error when cost element is already ACTIVE", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(activeCostElement);
+
+    const result = await run(db, { costElementId: activeCostElement.id }, commandCtx);
+
+    expectErr(result, InvalidStateError);
+  });
+
+  it("emits audit event recording the status transition and acting user", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(inactiveCostElement);
+    spies.update.mockReturnValueOnce({ ...inactiveCostElement, status: "ACTIVE" });
+
+    const result = await run(db, { costElementId: inactiveCostElement.id }, commandCtx);
+
+    expectOk(result);
+    expect(spies.update).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,41 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import { CostElementNotFoundError, InvalidStateError } from "../lib/errors.generated";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface ReactivateCostElementInput {
+  costElementId: string;
+  from?: string[];
+}
+
+/** Command: reactivateCostElement
+ * Transitions a cost element from INACTIVE status back to ACTIVE status.
+ */
+export async function run(db: Transaction, input: ReactivateCostElementInput, ctx: CommandContext) {
+  void ctx;
+
+  const validFromStatuses = input.from ?? ["INACTIVE"];
+
+  const costElement = await db
+    .selectFrom("CostElement")
+    .selectAll()
+    .where("id", "=", input.costElementId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!costElement) {
+    return err(new CostElementNotFoundError(input.costElementId));
+  }
+
+  if (!validFromStatuses.includes(costElement.status)) {
+    return err(new InvalidStateError(input.costElementId));
+  }
+
+  const updated = await db
+    .updateTable("CostElement")
+    .set({ status: "ACTIVE", updatedAt: new Date() })
+    .where("id", "=", input.costElementId)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ costElement: updated! });
+}

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

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

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

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { ProfitCenterNotFoundError, InvalidStateError } from "../lib/errors.generated";
+import { baseProfitCenter, activeProfitCenter, inactiveProfitCenter } from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./reactivateProfitCenter";
+
+describe("reactivateProfitCenter", () => {
+  it("reactivates an INACTIVE profit center transitioning it to ACTIVE status", async () => {
+    const reactivated = { ...inactiveProfitCenter, status: "ACTIVE" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(inactiveProfitCenter);
+    spies.update.mockReturnValueOnce(reactivated);
+
+    const result = await run(db, { profitCenterId: inactiveProfitCenter.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.profitCenter.status).toBe("ACTIVE");
+  });
+
+  it("returns error when profit center does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { profitCenterId: "missing-id" }, commandCtx);
+
+    expectErr(result, ProfitCenterNotFoundError);
+  });
+
+  it("returns error when profit center is in DRAFT status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseProfitCenter);
+
+    const result = await run(db, { profitCenterId: baseProfitCenter.id }, commandCtx);
+
+    expectErr(result, InvalidStateError);
+  });
+
+  it("returns error when profit center is already ACTIVE", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(activeProfitCenter);
+
+    const result = await run(db, { profitCenterId: activeProfitCenter.id }, commandCtx);
+
+    expectErr(result, InvalidStateError);
+  });
+
+  it("emits audit event recording the status transition and acting user", async () => {
+    const reactivated = { ...inactiveProfitCenter, status: "ACTIVE" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(inactiveProfitCenter);
+    spies.update.mockReturnValueOnce(reactivated);
+
+    const result = await run(db, { profitCenterId: inactiveProfitCenter.id }, commandCtx);
+
+    expectOk(result);
+    expect(spies.update).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,42 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import { ProfitCenterNotFoundError, InvalidStateError } from "../lib/errors.generated";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface ReactivateProfitCenterInput {
+  profitCenterId: string;
+  from?: string[];
+}
+
+export async function run(
+  db: Transaction,
+  input: ReactivateProfitCenterInput,
+  ctx: CommandContext,
+) {
+  void ctx;
+
+  const validFromStatuses = input.from ?? ["INACTIVE"];
+
+  const profitCenter = await db
+    .selectFrom("ProfitCenter")
+    .selectAll()
+    .where("id", "=", input.profitCenterId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!profitCenter) {
+    return err(new ProfitCenterNotFoundError(input.profitCenterId));
+  }
+
+  if (!validFromStatuses.includes(profitCenter.status)) {
+    return err(new InvalidStateError(input.profitCenterId));
+  }
+
+  const updated = await db
+    .updateTable("ProfitCenter")
+    .set({ status: "ACTIVE", updatedAt: new Date() })
+    .where("id", "=", input.profitCenterId)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ profitCenter: updated! });
+}

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

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

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

@@ -0,0 +1,157 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CostElementNotFoundError,
+  CostObjectNotFoundError,
+  AccountingPeriodNotFoundError,
+  InvalidCommitmentAmountError,
+  NoActiveBudgetError,
+} from "../lib/errors.generated";
+import {
+  baseCompany,
+  activeCostElement,
+  baseCostCenter,
+  baseAccountingPeriod,
+  activeBudget,
+  baseCommitment,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./recordCommitment";
+
+const validInput = {
+  costElementId: activeCostElement.id,
+  costObjectType: "CostCenter",
+  costObjectId: baseCostCenter.id,
+  accountingPeriodId: baseAccountingPeriod.id,
+  amount: 5000,
+  purchaseOrderId: "purchase-order-1",
+  companyId: baseCompany.id,
+};
+
+describe("recordCommitment", () => {
+  it("records a commitment against a cost element, cost object, and period", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(activeCostElement) // cost element
+      .mockReturnValueOnce(baseCostCenter) // cost object
+      .mockReturnValueOnce(baseAccountingPeriod) // accounting period
+      .mockReturnValueOnce(activeBudget); // active budget
+    spies.insert.mockReturnValueOnce(baseCommitment);
+
+    const result = await run(db, validInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.commitment).toEqual(baseCommitment);
+  });
+
+  it("reduces budget availability by the commitment amount", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(activeCostElement)
+      .mockReturnValueOnce(baseCostCenter)
+      .mockReturnValueOnce(baseAccountingPeriod)
+      .mockReturnValueOnce(activeBudget);
+    spies.insert.mockReturnValueOnce(baseCommitment);
+
+    const result = await run(db, validInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.commitment.status).toBe("OPEN");
+    expect(value.commitment.consumedAmount).toBe(0);
+    expect(value.commitment.amount).toBe(5000);
+  });
+
+  it("returns error when cost element does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { ...validInput, costElementId: "missing-element" }, commandCtx);
+
+    expectErr(result, CostElementNotFoundError);
+  });
+
+  it("returns error when cost object does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(activeCostElement).mockReturnValueOnce(undefined); // cost object not found
+
+    const result = await run(
+      db,
+      { ...validInput, costObjectId: "missing-cost-object" },
+      commandCtx,
+    );
+
+    expectErr(result, CostObjectNotFoundError);
+  });
+
+  it("returns error when accounting period does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(activeCostElement)
+      .mockReturnValueOnce(baseCostCenter)
+      .mockReturnValueOnce(undefined); // accounting period not found
+
+    const result = await run(
+      db,
+      { ...validInput, accountingPeriodId: "missing-period" },
+      commandCtx,
+    );
+
+    expectErr(result, AccountingPeriodNotFoundError);
+  });
+
+  it("returns error when commitment amount is zero or negative", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(activeCostElement)
+      .mockReturnValueOnce(baseCostCenter)
+      .mockReturnValueOnce(baseAccountingPeriod);
+
+    const result = await run(db, { ...validInput, amount: 0 }, commandCtx);
+
+    expectErr(result, InvalidCommitmentAmountError);
+  });
+
+  it("returns error when no active budget exists for the cost object", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(activeCostElement)
+      .mockReturnValueOnce(baseCostCenter)
+      .mockReturnValueOnce(baseAccountingPeriod)
+      .mockReturnValueOnce(undefined); // no active budget
+
+    const result = await run(db, validInput, commandCtx);
+
+    expectErr(result, NoActiveBudgetError);
+  });
+
+  it("associates commitment with purchase order reference", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(activeCostElement)
+      .mockReturnValueOnce(baseCostCenter)
+      .mockReturnValueOnce(baseAccountingPeriod)
+      .mockReturnValueOnce(activeBudget);
+    spies.insert.mockReturnValueOnce(baseCommitment);
+
+    const result = await run(db, validInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.commitment.purchaseOrderId).toBe("purchase-order-1");
+  });
+
+  it("emits audit event recording the commitment and acting user", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(activeCostElement)
+      .mockReturnValueOnce(baseCostCenter)
+      .mockReturnValueOnce(baseAccountingPeriod)
+      .mockReturnValueOnce(activeBudget);
+    spies.insert.mockReturnValueOnce(baseCommitment);
+
+    const result = await run(db, validInput, commandCtx);
+
+    expectOk(result);
+    expect(spies.insert).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,113 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CostElementNotFoundError,
+  CostObjectNotFoundError,
+  AccountingPeriodNotFoundError,
+  InvalidCommitmentAmountError,
+  NoActiveBudgetError,
+} from "../lib/errors.generated";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface RecordCommitmentInput {
+  costElementId: string;
+  costObjectType: string;
+  costObjectId: string;
+  accountingPeriodId: string;
+  amount: number;
+  purchaseOrderId: string;
+  companyId: string;
+}
+
+export async function run(db: Transaction, input: RecordCommitmentInput, ctx: CommandContext) {
+  void ctx;
+
+  // Validate cost element exists
+  const costElement = await db
+    .selectFrom("CostElement")
+    .where("id", "=", input.costElementId)
+    .selectAll()
+    .executeTakeFirst();
+
+  if (!costElement) {
+    return err(new CostElementNotFoundError(input.costElementId));
+  }
+
+  // Validate cost object exists (polymorphic: CostCenter, ProfitCenter, or InternalOrder)
+  let costObject: unknown;
+  if (input.costObjectType === "CostCenter") {
+    costObject = await db
+      .selectFrom("CostCenter")
+      .where("id", "=", input.costObjectId)
+      .selectAll()
+      .executeTakeFirst();
+  } else if (input.costObjectType === "ProfitCenter") {
+    costObject = await db
+      .selectFrom("ProfitCenter")
+      .where("id", "=", input.costObjectId)
+      .selectAll()
+      .executeTakeFirst();
+  } else if (input.costObjectType === "InternalOrder") {
+    costObject = await db
+      .selectFrom("InternalOrder")
+      .where("id", "=", input.costObjectId)
+      .selectAll()
+      .executeTakeFirst();
+  }
+
+  if (!costObject) {
+    return err(new CostObjectNotFoundError(input.costObjectId));
+  }
+
+  // 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 positive amount
+  if (input.amount <= 0) {
+    return err(new InvalidCommitmentAmountError(String(input.amount)));
+  }
+
+  // Validate active budget exists for the cost object
+  const activeBudget = await db
+    .selectFrom("Budget")
+    .where("costObjectId", "=", input.costObjectId)
+    .where("costObjectType", "=", input.costObjectType)
+    .where("status", "=", "ACTIVE")
+    .selectAll()
+    .executeTakeFirst();
+
+  if (!activeBudget) {
+    return err(new NoActiveBudgetError(input.costObjectId));
+  }
+
+  // Budget availability is calculated dynamically (Budget - Actual - Commitments - Encumbrances)
+  // Creating this commitment automatically reduces future budget availability calculations
+
+  // Create commitment with status OPEN and consumedAmount 0
+  const commitment = await db
+    .insertInto("Commitment")
+    .values({
+      costElementId: input.costElementId,
+      costObjectType: input.costObjectType,
+      costObjectId: input.costObjectId,
+      accountingPeriodId: input.accountingPeriodId,
+      amount: input.amount,
+      consumedAmount: 0,
+      purchaseOrderId: input.purchaseOrderId,
+      companyId: input.companyId,
+      status: "OPEN",
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ commitment: commitment! });
+}

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

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

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

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  BudgetNotFoundError,
+  InvalidStateError,
+  ReasonRequiredError,
+} from "../lib/errors.generated";
+import { submittedBudget, baseBudget } from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./rejectBudget";
+
+describe("rejectBudget", () => {
+  it("rejects a SUBMITTED budget transitioning it to DRAFT status with reason", async () => {
+    const rejectedBudget = { ...submittedBudget, status: "DRAFT" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(submittedBudget);
+    spies.update.mockReturnValueOnce(rejectedBudget);
+
+    const result = await run(
+      db,
+      { budgetId: submittedBudget.id, reason: "Needs revision" },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.budget.status).toBe("DRAFT");
+  });
+
+  it("returns error when budget does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { budgetId: "missing", reason: "Reason" }, commandCtx);
+
+    expectErr(result, BudgetNotFoundError);
+  });
+
+  it("returns error when budget is not in SUBMITTED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseBudget); // DRAFT
+
+    const result = await run(db, { budgetId: baseBudget.id, reason: "Reason" }, commandCtx);
+
+    expectErr(result, InvalidStateError);
+  });
+
+  it("returns error when reason text is missing", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(submittedBudget);
+
+    const result = await run(db, { budgetId: submittedBudget.id, reason: "" }, commandCtx);
+
+    expectErr(result, ReasonRequiredError);
+  });
+
+  it("reason is persisted to the budget", async () => {
+    const rejectionReason = "Needs revision";
+    const rejectedBudget = { ...submittedBudget, status: "DRAFT", rejectionReason };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(submittedBudget);
+    spies.update.mockReturnValueOnce(rejectedBudget);
+
+    const result = await run(
+      db,
+      { budgetId: submittedBudget.id, reason: rejectionReason },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.budget.rejectionReason).toBe(rejectionReason);
+  });
+
+  it("rejected budget can be updated and resubmitted", async () => {
+    const rejectedBudget = { ...submittedBudget, status: "DRAFT" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(submittedBudget);
+    spies.update.mockReturnValueOnce(rejectedBudget);
+
+    const result = await run(
+      db,
+      { budgetId: submittedBudget.id, reason: "Revise amounts" },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.budget.status).toBe("DRAFT");
+  });
+
+  it("emits audit event recording the status transition, reason, and acting user", async () => {
+    const rejectedBudget = { ...submittedBudget, status: "DRAFT" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(submittedBudget);
+    spies.update.mockReturnValueOnce(rejectedBudget);
+
+    const result = await run(
+      db,
+      { budgetId: submittedBudget.id, reason: "Audit reason" },
+      commandCtx,
+    );
+
+    expectOk(result);
+    expect(spies.update).toHaveBeenCalled();
+  });
+});