@tailor-platform/erp-kit 0.7.0 → 0.9.0

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();
+  });
+});

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

@@ -0,0 +1,51 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  BudgetNotFoundError,
+  InvalidStateError,
+  ReasonRequiredError,
+} from "../lib/errors.generated";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface RejectBudgetInput {
+  budgetId: string;
+  reason: string;
+}
+
+export async function run(db: Transaction, input: RejectBudgetInput, ctx: CommandContext) {
+  void ctx;
+
+  // Fetch budget with lock
+  const budget = await db
+    .selectFrom("Budget")
+    .where("id", "=", input.budgetId)
+    .selectAll()
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!budget) {
+    return err(new BudgetNotFoundError(input.budgetId));
+  }
+
+  if (budget.status !== "SUBMITTED") {
+    return err(new InvalidStateError(input.budgetId));
+  }
+
+  // Validate reason is provided
+  if (!input.reason || input.reason.trim() === "") {
+    return err(new ReasonRequiredError(input.budgetId));
+  }
+
+  // Transition back to DRAFT
+  const updated = await db
+    .updateTable("Budget")
+    .set({
+      status: "DRAFT",
+      rejectionReason: input.reason,
+      updatedAt: new Date(),
+    })
+    .where("id", "=", input.budgetId)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ budget: updated! });
+}

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

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

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

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { CommitmentNotFoundError, NoCommitmentToReleaseError } from "../lib/errors.generated";
+import {
+  baseCommitment,
+  partiallyConsumedCommitment,
+  fullyConsumedCommitment,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./releaseCommitment";
+
+const validInput = {
+  costElementId: baseCommitment.costElementId,
+  costObjectType: baseCommitment.costObjectType,
+  costObjectId: baseCommitment.costObjectId,
+  accountingPeriodId: baseCommitment.accountingPeriodId,
+  purchaseOrderId: baseCommitment.purchaseOrderId,
+};
+
+describe("releaseCommitment", () => {
+  it("releases remaining commitment amount back to available budget", async () => {
+    const released = { ...baseCommitment, consumedAmount: 5000, status: "RELEASED" as const };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCommitment);
+    spies.update.mockReturnValueOnce(released);
+
+    const result = await run(db, validInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.commitment.status).toBe("RELEASED");
+    expect(value.commitment.consumedAmount).toBe(baseCommitment.amount);
+  });
+
+  it("increases budget availability by the released amount", async () => {
+    const released = { ...baseCommitment, consumedAmount: 5000, status: "RELEASED" as const };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCommitment);
+    spies.update.mockReturnValueOnce(released);
+
+    const result = await run(db, validInput, commandCtx);
+
+    const value = expectOk(result);
+    // After release, consumedAmount equals amount, meaning no remaining obligation
+    expect(value.commitment.consumedAmount).toBe(value.commitment.amount);
+  });
+
+  it("returns error when commitment 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, CommitmentNotFoundError);
+  });
+
+  it("returns error when commitment has already been fully consumed", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(fullyConsumedCommitment); // remaining = 0
+
+    const result = await run(db, validInput, commandCtx);
+
+    expectErr(result, NoCommitmentToReleaseError);
+  });
+
+  it("releases a partially consumed commitment (only remaining portion)", async () => {
+    const released = {
+      ...partiallyConsumedCommitment,
+      consumedAmount: partiallyConsumedCommitment.amount,
+      status: "RELEASED" as const,
+    };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(partiallyConsumedCommitment); // remaining = 3000
+    spies.update.mockReturnValueOnce(released);
+
+    const result = await run(db, validInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.commitment.status).toBe("RELEASED");
+    expect(value.commitment.consumedAmount).toBe(partiallyConsumedCommitment.amount);
+  });
+
+  it("emits audit event recording the release and acting user", async () => {
+    const released = { ...baseCommitment, consumedAmount: 5000, status: "RELEASED" as const };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCommitment);
+    spies.update.mockReturnValueOnce(released);
+
+    const result = await run(db, validInput, commandCtx);
+
+    expectOk(result);
+    expect(spies.update).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,51 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import { CommitmentNotFoundError, NoCommitmentToReleaseError } from "../lib/errors.generated";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface ReleaseCommitmentInput {
+  costElementId: string;
+  costObjectType: string;
+  costObjectId: string;
+  accountingPeriodId: string;
+  purchaseOrderId: string;
+}
+
+export async function run(db: Transaction, input: ReleaseCommitmentInput, ctx: CommandContext) {
+  void ctx;
+
+  // Find commitment
+  const commitment = await db
+    .selectFrom("Commitment")
+    .where("costElementId", "=", input.costElementId)
+    .where("costObjectType", "=", input.costObjectType)
+    .where("costObjectId", "=", input.costObjectId)
+    .where("accountingPeriodId", "=", input.accountingPeriodId)
+    .where("purchaseOrderId", "=", input.purchaseOrderId)
+    .selectAll()
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!commitment) {
+    return err(new CommitmentNotFoundError(input.costElementId));
+  }
+
+  // Remaining amount must be > 0
+  const remaining = commitment.amount - commitment.consumedAmount;
+  if (remaining <= 0) {
+    return err(new NoCommitmentToReleaseError(commitment.id));
+  }
+
+  // Set status to RELEASED and consumedAmount = amount (fully released)
+  const updated = await db
+    .updateTable("Commitment")
+    .set({
+      consumedAmount: commitment.amount,
+      status: "RELEASED",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", commitment.id)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ commitment: updated! });
+}

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

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

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

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { InternalOrderNotFoundError, InvalidStateError } from "../lib/errors.generated";
+import {
+  baseInternalOrder,
+  releasedInternalOrder,
+  techCompletedInternalOrder,
+  closedInternalOrder,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./releaseInternalOrder";
+
+describe("releaseInternalOrder", () => {
+  it("releases a CREATED internal order transitioning it to RELEASED status", async () => {
+    const updated = { ...baseInternalOrder, status: "RELEASED" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseInternalOrder);
+    spies.update.mockReturnValueOnce(updated);
+
+    const result = await run(db, { internalOrderId: baseInternalOrder.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.internalOrder.status).toBe("RELEASED");
+  });
+
+  it("returns error when internal order does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { internalOrderId: "missing-id" }, commandCtx);
+
+    expectErr(result, InternalOrderNotFoundError);
+  });
+
+  it("returns error when internal order is already RELEASED", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(releasedInternalOrder);
+
+    const result = await run(db, { internalOrderId: releasedInternalOrder.id }, commandCtx);
+
+    expectErr(result, InvalidStateError);
+  });
+
+  it("returns error when internal order is TECHNICALLY_COMPLETED", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(techCompletedInternalOrder);
+
+    const result = await run(db, { internalOrderId: techCompletedInternalOrder.id }, commandCtx);
+
+    expectErr(result, InvalidStateError);
+  });
+
+  it("returns error when internal order is CLOSED", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(closedInternalOrder);
+
+    const result = await run(db, { internalOrderId: closedInternalOrder.id }, commandCtx);
+
+    expectErr(result, InvalidStateError);
+  });
+
+  it("emits audit event recording the status transition and acting user", async () => {
+    const updated = { ...baseInternalOrder, status: "RELEASED" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseInternalOrder);
+    spies.update.mockReturnValueOnce(updated);
+
+    const result = await run(db, { internalOrderId: baseInternalOrder.id }, commandCtx);
+
+    expectOk(result);
+    expect(spies.update).toHaveBeenCalled();
+  });
+});