@tailor-platform/erp-kit 0.5.1 → 0.7.0

package/src/modules/finance-ledger/command/initiatePeriodClose.generated.ts

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

package/src/modules/finance-ledger/command/initiatePeriodClose.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AccountingPeriodNotFoundError,
+  InvalidPeriodStatusError,
+  CloseAlreadyInProgressError,
+  ConcurrentCloseConflictError,
+} from "../lib/errors.generated";
+import {
+  baseAccountingPeriod,
+  neverOpenedPeriod,
+  closedPeriod,
+  permanentlyClosedPeriod,
+  basePeriodClose,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./initiatePeriodClose";
+
+describe("initiatePeriodClose", () => {
+  it("returns error when accounting period does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined); // period lookup
+
+    const result = await run(db, { accountingPeriodId: "nonexistent" }, commandCtx);
+
+    expectErr(result, AccountingPeriodNotFoundError);
+  });
+
+  it("returns error when accounting period is in NEVER_OPENED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(neverOpenedPeriod); // period lookup
+
+    const result = await run(db, { accountingPeriodId: neverOpenedPeriod.id }, commandCtx);
+
+    expectErr(result, InvalidPeriodStatusError);
+  });
+
+  it("returns error when accounting period is in CLOSED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(closedPeriod); // period lookup
+
+    const result = await run(db, { accountingPeriodId: closedPeriod.id }, commandCtx);
+
+    expectErr(result, InvalidPeriodStatusError);
+  });
+
+  it("returns error when accounting period is in PERMANENTLY_CLOSED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(permanentlyClosedPeriod); // period lookup
+
+    const result = await run(db, { accountingPeriodId: permanentlyClosedPeriod.id }, commandCtx);
+
+    expectErr(result, InvalidPeriodStatusError);
+  });
+
+  it("returns error when period already has an active close in progress", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseAccountingPeriod) // period lookup
+      .mockReturnValueOnce(basePeriodClose); // existing active PeriodClose
+
+    const result = await run(db, { accountingPeriodId: baseAccountingPeriod.id }, commandCtx);
+
+    expectErr(result, CloseAlreadyInProgressError);
+  });
+
+  it("returns error on concurrent close attempt for the same period", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseAccountingPeriod) // period lookup
+      .mockReturnValueOnce(undefined); // no existing PeriodClose
+    spies.insert.mockImplementationOnce(() => {
+      throw new Error("unique constraint violation");
+    });
+
+    const result = await run(db, { accountingPeriodId: baseAccountingPeriod.id }, commandCtx);
+
+    expectErr(result, ConcurrentCloseConflictError);
+  });
+
+  it("creates PeriodClose in NOT_STARTED status for an OPEN period", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdPeriodClose = {
+      ...basePeriodClose,
+      initiatedByUserId: commandCtx.actorId,
+    };
+    spies.select
+      .mockReturnValueOnce(baseAccountingPeriod) // period lookup
+      .mockReturnValueOnce(undefined); // no existing PeriodClose
+    spies.insert.mockReturnValueOnce(createdPeriodClose);
+
+    const result = await run(db, { accountingPeriodId: baseAccountingPeriod.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.periodClose.status).toBe("NOT_STARTED");
+  });
+
+  it("records the initiating user's userId", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdPeriodClose = {
+      ...basePeriodClose,
+      initiatedByUserId: commandCtx.actorId,
+    };
+    spies.select
+      .mockReturnValueOnce(baseAccountingPeriod) // period lookup
+      .mockReturnValueOnce(undefined); // no existing PeriodClose
+    spies.insert.mockReturnValueOnce(createdPeriodClose);
+
+    const result = await run(db, { accountingPeriodId: baseAccountingPeriod.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.periodClose.initiatedByUserId).toBe(commandCtx.actorId);
+  });
+
+  it("sets completionPercentage to 0", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdPeriodClose = {
+      ...basePeriodClose,
+      initiatedByUserId: commandCtx.actorId,
+      completionPercentage: 0,
+    };
+    spies.select
+      .mockReturnValueOnce(baseAccountingPeriod) // period lookup
+      .mockReturnValueOnce(undefined); // no existing PeriodClose
+    spies.insert.mockReturnValueOnce(createdPeriodClose);
+
+    const result = await run(db, { accountingPeriodId: baseAccountingPeriod.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.periodClose.completionPercentage).toBe(0);
+  });
+
+  it("emits audit event recording acting user, timestamp, and period reference", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdPeriodClose = {
+      ...basePeriodClose,
+      initiatedByUserId: commandCtx.actorId,
+    };
+    spies.select
+      .mockReturnValueOnce(baseAccountingPeriod) // period lookup
+      .mockReturnValueOnce(undefined); // no existing PeriodClose
+    spies.insert.mockReturnValueOnce(createdPeriodClose);
+
+    const result = await run(db, { accountingPeriodId: baseAccountingPeriod.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.auditEvent).toBeDefined();
+    expect(value.auditEvent.actorId).toBe(commandCtx.actorId);
+    expect(value.auditEvent.timestamp).toBeInstanceOf(Date);
+    expect(value.auditEvent.accountingPeriodId).toBe(baseAccountingPeriod.id);
+  });
+});

package/src/modules/finance-ledger/command/initiatePeriodClose.ts

@@ -0,0 +1,84 @@
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AccountingPeriodNotFoundError,
+  InvalidPeriodStatusError,
+  CloseAlreadyInProgressError,
+  ConcurrentCloseConflictError,
+} from "../lib/errors.generated";
+
+export interface InitiatePeriodCloseInput {
+  accountingPeriodId: string;
+}
+
+const TERMINAL_PERIOD_CLOSE_STATUSES = ["PERMANENTLY_CLOSED"];
+
+/**
+ * Function: initiatePeriodClose
+ *
+ * Creates a new PeriodClose record in NOT_STARTED status for a given
+ * accounting period. Only periods in OPEN status can have a close initiated,
+ * and each period can have at most one active PeriodClose record.
+ */
+export async function run(db: Transaction, input: InitiatePeriodCloseInput, ctx: CommandContext) {
+  const { accountingPeriodId } = input;
+
+  // 1. Find accounting period
+  const period = await db
+    .selectFrom("AccountingPeriod")
+    .selectAll()
+    .where("id", "=", accountingPeriodId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!period) {
+    return err(new AccountingPeriodNotFoundError(accountingPeriodId));
+  }
+
+  // 2. Validate period is in OPEN status
+  if (period.status !== "OPEN") {
+    return err(new InvalidPeriodStatusError(accountingPeriodId));
+  }
+
+  // 3. Check for existing active PeriodClose record
+  const existingClose = await db
+    .selectFrom("PeriodClose")
+    .selectAll()
+    .where("accountingPeriodId", "=", accountingPeriodId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (existingClose && !TERMINAL_PERIOD_CLOSE_STATUSES.includes(existingClose.status)) {
+    return err(new CloseAlreadyInProgressError(accountingPeriodId));
+  }
+
+  // 4. Create PeriodClose record in NOT_STARTED status
+  const now = new Date();
+  let periodClose;
+  try {
+    periodClose = await db
+      .insertInto("PeriodClose")
+      .values({
+        accountingPeriodId,
+        status: "NOT_STARTED",
+        initiatedByUserId: ctx.actorId,
+        completionPercentage: 0,
+        yearEndCloseExecuted: false,
+        createdAt: now,
+      })
+      .returningAll()
+      .executeTakeFirstOrThrow();
+  } catch {
+    return err(new ConcurrentCloseConflictError(accountingPeriodId));
+  }
+
+  // 5. Build audit event
+  const auditEvent = {
+    type: "PERIOD_CLOSE_INITIATED",
+    actorId: ctx.actorId,
+    timestamp: now,
+    accountingPeriodId,
+  };
+
+  return ok({ periodClose, auditEvent });
+}

package/src/modules/finance-ledger/command/openForAdvanceEntry.generated.ts

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

package/src/modules/finance-ledger/command/openForAdvanceEntry.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AccountingPeriodNotFoundError,
+  InvalidStatusTransitionError,
+} from "../lib/errors.generated";
+import {
+  neverOpenedPeriod,
+  futureEnterablePeriod,
+  baseAccountingPeriod,
+  closedPeriod,
+  permanentlyClosedPeriod,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./openForAdvanceEntry";
+
+describe("openForAdvanceEntry", () => {
+  it("returns error when accounting period does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "non-existent" }, commandCtx);
+
+    expectErr(result, AccountingPeriodNotFoundError);
+  });
+
+  it("returns error when period is in FUTURE_ENTERABLE status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(futureEnterablePeriod);
+
+    const result = await run(db, { id: futureEnterablePeriod.id }, commandCtx);
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("returns error when period is in OPEN status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseAccountingPeriod);
+
+    const result = await run(db, { id: baseAccountingPeriod.id }, commandCtx);
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("returns error when period is in CLOSED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(closedPeriod);
+
+    const result = await run(db, { id: closedPeriod.id }, commandCtx);
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("returns error when period is in PERMANENTLY_CLOSED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(permanentlyClosedPeriod);
+
+    const result = await run(db, { id: permanentlyClosedPeriod.id }, commandCtx);
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("transitions NEVER_OPENED period to FUTURE_ENTERABLE", async () => {
+    const updatedPeriod = { ...neverOpenedPeriod, status: "FUTURE_ENTERABLE" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(neverOpenedPeriod);
+    spies.update.mockReturnValueOnce(updatedPeriod);
+
+    const result = await run(db, { id: neverOpenedPeriod.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.accountingPeriod.status).toBe("FUTURE_ENTERABLE");
+  });
+
+  it("emits audit event recording status transition from NEVER_OPENED to FUTURE_ENTERABLE and acting user", async () => {
+    const updatedPeriod = { ...neverOpenedPeriod, status: "FUTURE_ENTERABLE" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(neverOpenedPeriod);
+    spies.update.mockReturnValueOnce(updatedPeriod);
+
+    const result = await run(db, { id: neverOpenedPeriod.id }, commandCtx);
+
+    expectOk(result);
+    expect(spies.update).toHaveBeenCalled();
+  });
+});

package/src/modules/finance-ledger/command/openForAdvanceEntry.ts

@@ -0,0 +1,44 @@
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AccountingPeriodNotFoundError,
+  InvalidStatusTransitionError,
+} from "../lib/errors.generated";
+
+export interface OpenForAdvanceEntryInput {
+  id: string;
+}
+
+const from = ["NEVER_OPENED"];
+
+export async function run(db: Transaction, input: OpenForAdvanceEntryInput, ctx: CommandContext) {
+  const period = await db
+    .selectFrom("AccountingPeriod")
+    .selectAll()
+    .where("id", "=", input.id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!period) {
+    return err(new AccountingPeriodNotFoundError(input.id));
+  }
+
+  if (!from.includes(period.status as string)) {
+    return err(new InvalidStatusTransitionError(input.id));
+  }
+
+  const updated = await db
+    .updateTable("AccountingPeriod")
+    .set({
+      status: "FUTURE_ENTERABLE",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", input.id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  // Emit audit event recording status transition from NEVER_OPENED to FUTURE_ENTERABLE and acting user
+  void ctx;
+
+  return ok({ accountingPeriod: updated });
+}

package/src/modules/finance-ledger/command/openPeriod.generated.ts

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

package/src/modules/finance-ledger/command/openPeriod.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AccountingPeriodNotFoundError,
+  InvalidStatusTransitionError,
+} from "../lib/errors.generated";
+import {
+  neverOpenedPeriod,
+  futureEnterablePeriod,
+  baseAccountingPeriod,
+  closedPeriod,
+  permanentlyClosedPeriod,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./openPeriod";
+
+describe("openPeriod", () => {
+  it("returns error when accounting period does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "non-existent" }, commandCtx);
+
+    expectErr(result, AccountingPeriodNotFoundError);
+  });
+
+  it("returns error when period is in OPEN status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseAccountingPeriod);
+
+    const result = await run(db, { id: baseAccountingPeriod.id }, commandCtx);
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("returns error when period is in CLOSED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(closedPeriod);
+
+    const result = await run(db, { id: closedPeriod.id }, commandCtx);
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("returns error when period is in PERMANENTLY_CLOSED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(permanentlyClosedPeriod);
+
+    const result = await run(db, { id: permanentlyClosedPeriod.id }, commandCtx);
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("transitions NEVER_OPENED period directly to OPEN", async () => {
+    const updatedPeriod = { ...neverOpenedPeriod, status: "OPEN" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(neverOpenedPeriod);
+    spies.update.mockReturnValueOnce(updatedPeriod);
+
+    const result = await run(db, { id: neverOpenedPeriod.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.accountingPeriod.status).toBe("OPEN");
+  });
+
+  it("transitions FUTURE_ENTERABLE period to OPEN", async () => {
+    const updatedPeriod = { ...futureEnterablePeriod, status: "OPEN" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(futureEnterablePeriod);
+    spies.update.mockReturnValueOnce(updatedPeriod);
+
+    const result = await run(db, { id: futureEnterablePeriod.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.accountingPeriod.status).toBe("OPEN");
+  });
+
+  it("emits audit event recording status transition and acting user", async () => {
+    const updatedPeriod = { ...neverOpenedPeriod, status: "OPEN" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(neverOpenedPeriod);
+    spies.update.mockReturnValueOnce(updatedPeriod);
+
+    const result = await run(db, { id: neverOpenedPeriod.id }, commandCtx);
+
+    expectOk(result);
+    expect(spies.update).toHaveBeenCalled();
+  });
+});

package/src/modules/finance-ledger/command/openPeriod.ts

@@ -0,0 +1,44 @@
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AccountingPeriodNotFoundError,
+  InvalidStatusTransitionError,
+} from "../lib/errors.generated";
+
+export interface OpenPeriodInput {
+  id: string;
+}
+
+const from = ["NEVER_OPENED", "FUTURE_ENTERABLE"];
+
+export async function run(db: Transaction, input: OpenPeriodInput, ctx: CommandContext) {
+  const period = await db
+    .selectFrom("AccountingPeriod")
+    .selectAll()
+    .where("id", "=", input.id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!period) {
+    return err(new AccountingPeriodNotFoundError(input.id));
+  }
+
+  if (!from.includes(period.status as string)) {
+    return err(new InvalidStatusTransitionError(input.id));
+  }
+
+  const updated = await db
+    .updateTable("AccountingPeriod")
+    .set({
+      status: "OPEN",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", input.id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  // Emit audit event recording status transition and acting user
+  void ctx;
+
+  return ok({ accountingPeriod: updated });
+}

package/src/modules/finance-ledger/command/permanentlyClosePeriod.generated.ts

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

package/src/modules/finance-ledger/command/permanentlyClosePeriod.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AccountingPeriodNotFoundError,
+  InvalidStatusTransitionError,
+} from "../lib/errors.generated";
+import {
+  neverOpenedPeriod,
+  futureEnterablePeriod,
+  baseAccountingPeriod,
+  closedPeriod,
+  permanentlyClosedPeriod,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./permanentlyClosePeriod";
+
+describe("permanentlyClosePeriod", () => {
+  it("returns error when accounting period does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "non-existent" }, commandCtx);
+
+    expectErr(result, AccountingPeriodNotFoundError);
+  });
+
+  it("returns error when period is in NEVER_OPENED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(neverOpenedPeriod);
+
+    const result = await run(db, { id: neverOpenedPeriod.id }, commandCtx);
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("returns error when period is in OPEN status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseAccountingPeriod);
+
+    const result = await run(db, { id: baseAccountingPeriod.id }, commandCtx);
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("returns error when period is in FUTURE_ENTERABLE status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(futureEnterablePeriod);
+
+    const result = await run(db, { id: futureEnterablePeriod.id }, commandCtx);
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("returns error when period is already PERMANENTLY_CLOSED", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(permanentlyClosedPeriod);
+
+    const result = await run(db, { id: permanentlyClosedPeriod.id }, commandCtx);
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("transitions CLOSED period to PERMANENTLY_CLOSED", async () => {
+    const updatedPeriod = { ...closedPeriod, status: "PERMANENTLY_CLOSED" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(closedPeriod);
+    spies.update.mockReturnValueOnce(updatedPeriod);
+
+    const result = await run(db, { id: closedPeriod.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.accountingPeriod.status).toBe("PERMANENTLY_CLOSED");
+  });
+
+  it("emits audit event recording the irreversible transition and acting user", async () => {
+    const updatedPeriod = { ...closedPeriod, status: "PERMANENTLY_CLOSED" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(closedPeriod);
+    spies.update.mockReturnValueOnce(updatedPeriod);
+
+    const result = await run(db, { id: closedPeriod.id }, commandCtx);
+
+    expectOk(result);
+    expect(spies.update).toHaveBeenCalled();
+  });
+});

package/src/modules/finance-ledger/command/permanentlyClosePeriod.ts

@@ -0,0 +1,48 @@
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AccountingPeriodNotFoundError,
+  InvalidStatusTransitionError,
+} from "../lib/errors.generated";
+
+export interface PermanentlyClosePeriodInput {
+  id: string;
+}
+
+const from = ["CLOSED"];
+
+export async function run(
+  db: Transaction,
+  input: PermanentlyClosePeriodInput,
+  ctx: CommandContext,
+) {
+  const period = await db
+    .selectFrom("AccountingPeriod")
+    .selectAll()
+    .where("id", "=", input.id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!period) {
+    return err(new AccountingPeriodNotFoundError(input.id));
+  }
+
+  if (!from.includes(period.status as string)) {
+    return err(new InvalidStatusTransitionError(input.id));
+  }
+
+  const updated = await db
+    .updateTable("AccountingPeriod")
+    .set({
+      status: "PERMANENTLY_CLOSED",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", input.id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  // Emit audit event recording the irreversible transition and acting user
+  void ctx;
+
+  return ok({ accountingPeriod: updated });
+}

package/src/modules/finance-ledger/command/postAdjustingEntries.generated.ts

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