@tailor-platform/erp-kit 0.3.0 → 0.4.0

package/src/modules/coa-management/generated/enums.ts

@@ -0,0 +1,45 @@
+/**
+ * Account type: ASSET, LIABILITY, EQUITY, REVENUE, or EXPENSE
+ */
+export const AccountAccountType = {
+  "ASSET": "ASSET",
+  "LIABILITY": "LIABILITY",
+  "EQUITY": "EQUITY",
+  "REVENUE": "REVENUE",
+  "EXPENSE": "EXPENSE"
+} as const;
+export type AccountAccountType = (typeof AccountAccountType)[keyof typeof AccountAccountType];
+
+/**
+ * Operational classification of the account
+ */
+export const AccountClassification = {
+  "REGULAR": "REGULAR",
+  "RECEIVABLE": "RECEIVABLE",
+  "PAYABLE": "PAYABLE",
+  "BANK_CASH": "BANK_CASH",
+  "FIXED_ASSET": "FIXED_ASSET",
+  "RETAINED_EARNINGS": "RETAINED_EARNINGS",
+  "NON_POSTING": "NON_POSTING"
+} as const;
+export type AccountClassification = (typeof AccountClassification)[keyof typeof AccountClassification];
+
+/**
+ * Lifecycle status: DRAFT, ACTIVE, INACTIVE
+ */
+export const AccountStatus = {
+  "DRAFT": "DRAFT",
+  "ACTIVE": "ACTIVE",
+  "INACTIVE": "INACTIVE"
+} as const;
+export type AccountStatus = (typeof AccountStatus)[keyof typeof AccountStatus];
+
+/**
+ * Lifecycle status: DRAFT, ACTIVE, ARCHIVED
+ */
+export const ChartOfAccountsStatus = {
+  "DRAFT": "DRAFT",
+  "ACTIVE": "ACTIVE",
+  "ARCHIVED": "ARCHIVED"
+} as const;
+export type ChartOfAccountsStatus = (typeof ChartOfAccountsStatus)[keyof typeof ChartOfAccountsStatus];

package/src/modules/coa-management/generated/kysely-tailordb.ts

@@ -0,0 +1,81 @@
+import {
+  createGetDB,
+  type Generated,
+  type Timestamp,
+  type NamespaceDB,
+  type NamespaceInsertable,
+  type NamespaceSelectable,
+  type NamespaceTable,
+  type NamespaceTableName,
+  type NamespaceTransaction,
+  type NamespaceUpdateable,
+} from "@tailor-platform/sdk/kysely";
+
+export interface Namespace {
+  "main-db": {
+    Account: {
+      id: Generated<string>;
+      code: string;
+      name: string;
+      accountType: "ASSET" | "LIABILITY" | "EQUITY" | "REVENUE" | "EXPENSE";
+      classification: "REGULAR" | "RECEIVABLE" | "PAYABLE" | "BANK_CASH" | "FIXED_ASSET" | "RETAINED_EARNINGS" | "NON_POSTING";
+      chartOfAccountsId: string;
+      accountGroupId: string | null;
+      currencyRestriction: string | null;
+      reconciliation: boolean;
+      defaultTaxCode: string | null;
+      tags: string | null;
+      successorAccountId: string | null;
+      hasPostedTransactions: boolean;
+      status: "DRAFT" | "ACTIVE" | "INACTIVE";
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    AccountGroup: {
+      id: Generated<string>;
+      code: string;
+      name: string;
+      chartOfAccountsId: string;
+      parentAccountGroupId: string | null;
+      sortOrder: number | null;
+      numberRangeStart: number | null;
+      numberRangeEnd: number | null;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    ChartOfAccounts: {
+      id: Generated<string>;
+      name: string;
+      description: string | null;
+      companyId: string;
+      baseCurrencyId: string;
+      status: "DRAFT" | "ACTIVE" | "ARCHIVED";
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    Company: {
+      id: Generated<string>;
+    }
+
+    Currency: {
+      id: Generated<string>;
+    }
+  }
+}
+
+export const getDB = createGetDB<Namespace>();
+
+export type DB<N extends keyof Namespace = keyof Namespace> = NamespaceDB<Namespace, N>;
+
+export type Transaction<K extends keyof Namespace | DB = keyof Namespace> =
+  NamespaceTransaction<Namespace, K>;
+
+type TableName = NamespaceTableName<Namespace>;
+export type Table<T extends TableName> = NamespaceTable<Namespace, T>;
+
+export type Insertable<T extends TableName> = NamespaceInsertable<Namespace, T>;
+export type Selectable<T extends TableName> = NamespaceSelectable<Namespace, T>;
+export type Updateable<T extends TableName> = NamespaceUpdateable<Namespace, T>;

package/src/modules/coa-management/index.ts

@@ -0,0 +1,2 @@
+export { defineModule } from "./module";
+export { permissions, own, all } from "./lib/permissions.generated";

package/src/modules/coa-management/lib/_db_deps.ts

@@ -0,0 +1,17 @@
+// Stub types for cross-module dependencies — used only for codegen.
+// At runtime, actual types are injected via defineModule() params.
+import {
+  db,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+
+export const company = db
+  .type("Company", {})
+  .permission(unsafeAllowAllTypePermission)
+  .gqlPermission(unsafeAllowAllGqlPermission);
+
+export const currency = db
+  .type("Currency", {})
+  .permission(unsafeAllowAllTypePermission)
+  .gqlPermission(unsafeAllowAllGqlPermission);

package/src/modules/coa-management/lib/errors.generated.ts

@@ -0,0 +1,162 @@
+// @generated — do not edit
+import { createDomainError } from "../../../shared";
+
+export const AccountNotFoundError = createDomainError(
+  "AccountNotFoundError", "COA_MANAGEMENT_ACCOUNT_NOT_FOUND",
+  (identifier: string) => `Specified account ID does not exist: ${identifier}`,
+);
+
+export const ChartOfAccountsNotActiveError = createDomainError(
+  "ChartOfAccountsNotActiveError", "COA_MANAGEMENT_CHART_OF_ACCOUNTS_NOT_ACTIVE",
+  (identifier: string) => `Parent CoA is not in ACTIVE status; account activation requires the CoA to be ACTIVE: ${identifier}`,
+);
+
+export const InvalidStateTransitionError = createDomainError(
+  "InvalidStateTransitionError", "COA_MANAGEMENT_INVALID_STATE_TRANSITION",
+  (identifier: string) => `Entity is not in the required status for the requested state transition: ${identifier}`,
+);
+
+export const ChartOfAccountsNotFoundError = createDomainError(
+  "ChartOfAccountsNotFoundError", "COA_MANAGEMENT_CHART_OF_ACCOUNTS_NOT_FOUND",
+  (identifier: string) => `Specified CoA ID does not exist: ${identifier}`,
+);
+
+export const DuplicateActiveChartOfAccountsError = createDomainError(
+  "DuplicateActiveChartOfAccountsError", "COA_MANAGEMENT_DUPLICATE_ACTIVE_CHART_OF_ACCOUNTS",
+  (identifier: string) => `Another ACTIVE CoA already exists for the same company: ${identifier}`,
+);
+
+export const DuplicateAccountCodeError = createDomainError(
+  "DuplicateAccountCodeError", "COA_MANAGEMENT_DUPLICATE_ACCOUNT_CODE",
+  (identifier: string) => `An account with the same code already exists in the CoA: ${identifier}`,
+);
+
+export const IncompatibleClassificationError = createDomainError(
+  "IncompatibleClassificationError", "COA_MANAGEMENT_INCOMPATIBLE_CLASSIFICATION",
+  (identifier: string) => `Account classification is not compatible with the account type: ${identifier}`,
+);
+
+export const DuplicateRetainedEarningsError = createDomainError(
+  "DuplicateRetainedEarningsError", "COA_MANAGEMENT_DUPLICATE_RETAINED_EARNINGS",
+  (identifier: string) => `Another account in the CoA already has RETAINED_EARNINGS classification: ${identifier}`,
+);
+
+export const CurrencyNotFoundError = createDomainError(
+  "CurrencyNotFoundError", "COA_MANAGEMENT_CURRENCY_NOT_FOUND",
+  (identifier: string) => `Referenced currency does not exist or is not active: ${identifier}`,
+);
+
+export const AccountGroupNotFoundError = createDomainError(
+  "AccountGroupNotFoundError", "COA_MANAGEMENT_ACCOUNT_GROUP_NOT_FOUND",
+  (identifier: string) => `Referenced account group does not exist or belongs to a different CoA: ${identifier}`,
+);
+
+export const CodeOutOfRangeError = createDomainError(
+  "CodeOutOfRangeError", "COA_MANAGEMENT_CODE_OUT_OF_RANGE",
+  (identifier: string) => `Account code does not fall within the assigned group's number range: ${identifier}`,
+);
+
+export const NameRequiredError = createDomainError(
+  "NameRequiredError", "COA_MANAGEMENT_NAME_REQUIRED",
+  (identifier: string) => `Account name is empty or not provided: ${identifier}`,
+);
+
+export const InvalidAccountCodeError = createDomainError(
+  "InvalidAccountCodeError", "COA_MANAGEMENT_INVALID_ACCOUNT_CODE",
+  (identifier: string) => `Account code is not a valid structured numeric identifier: ${identifier}`,
+);
+
+export const ReconciliationRequiredError = createDomainError(
+  "ReconciliationRequiredError", "COA_MANAGEMENT_RECONCILIATION_REQUIRED",
+  (identifier: string) => `Reconciliation cannot be set to false for RECEIVABLE, PAYABLE, or BANK_CASH classifications: ${identifier}`,
+);
+
+export const ChartOfAccountsArchivedError = createDomainError(
+  "ChartOfAccountsArchivedError", "COA_MANAGEMENT_CHART_OF_ACCOUNTS_ARCHIVED",
+  (identifier: string) => `Parent CoA is in ARCHIVED status; no modifications are permitted: ${identifier}`,
+);
+
+export const CodeRequiredError = createDomainError(
+  "CodeRequiredError", "COA_MANAGEMENT_CODE_REQUIRED",
+  (identifier: string) => `Group code is empty or not provided: ${identifier}`,
+);
+
+export const DuplicateGroupCodeError = createDomainError(
+  "DuplicateGroupCodeError", "COA_MANAGEMENT_DUPLICATE_GROUP_CODE",
+  (identifier: string) => `A group with the same code already exists in the CoA: ${identifier}`,
+);
+
+export const ParentGroupNotFoundError = createDomainError(
+  "ParentGroupNotFoundError", "COA_MANAGEMENT_PARENT_GROUP_NOT_FOUND",
+  (identifier: string) => `Specified parent group does not exist or belongs to a different CoA: ${identifier}`,
+);
+
+export const InvalidNumberRangeError = createDomainError(
+  "InvalidNumberRangeError", "COA_MANAGEMENT_INVALID_NUMBER_RANGE",
+  (identifier: string) => `Number range is invalid (start >= end) or overlaps with another group's range: ${identifier}`,
+);
+
+export const CompanyNotFoundError = createDomainError(
+  "CompanyNotFoundError", "COA_MANAGEMENT_COMPANY_NOT_FOUND",
+  (identifier: string) => `Referenced company does not exist or is not in ACTIVE status: ${identifier}`,
+);
+
+export const TemplateNotFoundError = createDomainError(
+  "TemplateNotFoundError", "COA_MANAGEMENT_TEMPLATE_NOT_FOUND",
+  (identifier: string) => `Specified templateId does not reference a valid template in the template provider: ${identifier}`,
+);
+
+export const TemplateProviderNotConfiguredError = createDomainError(
+  "TemplateProviderNotConfiguredError", "COA_MANAGEMENT_TEMPLATE_PROVIDER_NOT_CONFIGURED",
+  (identifier: string) => `templateId was provided but no template provider is configured: ${identifier}`,
+);
+
+export const OpenBalancesExistError = createDomainError(
+  "OpenBalancesExistError", "COA_MANAGEMENT_OPEN_BALANCES_EXIST",
+  (identifier: string) => `Pre-deactivation hook reports open or unreconciled balances (GL module integration): ${identifier}`,
+);
+
+export const SuccessorNotActiveError = createDomainError(
+  "SuccessorNotActiveError", "COA_MANAGEMENT_SUCCESSOR_NOT_ACTIVE",
+  (identifier: string) => `Specified successor account is not in ACTIVE status: ${identifier}`,
+);
+
+export const HasPostedTransactionsError = createDomainError(
+  "HasPostedTransactionsError", "COA_MANAGEMENT_HAS_POSTED_TRANSACTIONS",
+  (identifier: string) => `Account has posted transactions and cannot be deleted: ${identifier}`,
+);
+
+export const HasChildGroupsError = createDomainError(
+  "HasChildGroupsError", "COA_MANAGEMENT_HAS_CHILD_GROUPS",
+  (identifier: string) => `Group contains child groups and cannot be deleted: ${identifier}`,
+);
+
+export const HasAssignedAccountsError = createDomainError(
+  "HasAssignedAccountsError", "COA_MANAGEMENT_HAS_ASSIGNED_ACCOUNTS",
+  (identifier: string) => `Group has accounts assigned to it and cannot be deleted: ${identifier}`,
+);
+
+export const CircularReferenceError = createDomainError(
+  "CircularReferenceError", "COA_MANAGEMENT_CIRCULAR_REFERENCE",
+  (identifier: string) => `New parent is the group itself or one of its descendants: ${identifier}`,
+);
+
+export const StructuralFieldImmutableError = createDomainError(
+  "StructuralFieldImmutableError", "COA_MANAGEMENT_STRUCTURAL_FIELD_IMMUTABLE",
+  (identifier: string) => `Attempted to change a structural field on an account with posted transactions: ${identifier}`,
+);
+
+export const AccountsOutOfRangeError = createDomainError(
+  "AccountsOutOfRangeError", "COA_MANAGEMENT_ACCOUNTS_OUT_OF_RANGE",
+  (identifier: string) => `Existing assigned accounts have codes outside the new number range: ${identifier}`,
+);
+
+export const SelfReferenceError = createDomainError(
+  "SelfReferenceError", "COA_MANAGEMENT_SELF_REFERENCE",
+  (identifier: string) => `Group is moved to itself as parent — returns isCircular: true: ${identifier}`,
+);
+
+export const EmptyResultError = createDomainError(
+  "EmptyResultError", "COA_MANAGEMENT_EMPTY_RESULT",
+  (identifier: string) => `No groups match the given criteria — returns empty list: ${identifier}`,
+);

package/src/modules/coa-management/lib/permissions.generated.ts

@@ -0,0 +1,20 @@
+// @generated — do not edit
+import { definePermissions } from "../../../shared";
+
+export const { permissions, own, all } = definePermissions("coa-management", [
+  "activateAccount",
+  "activateChartOfAccounts",
+  "createAccount",
+  "createAccountGroup",
+  "createChartOfAccounts",
+  "deactivateAccount",
+  "deactivateChartOfAccounts",
+  "deleteAccount",
+  "deleteAccountGroup",
+  "deleteChartOfAccounts",
+  "moveAccountGroup",
+  "reactivateAccount",
+  "updateAccount",
+  "updateAccountGroup",
+  "updateChartOfAccounts",
+] as const);

package/src/modules/coa-management/lib/types.ts

@@ -0,0 +1,22 @@
+import type { InferSchema, Selectable, Insertable, Updateable } from "../../../shared";
+import type { DB } from "../generated/kysely-tailordb";
+
+export type Schema = InferSchema<DB>;
+
+export type ChartOfAccounts<T extends { ChartOfAccounts: object }> = Selectable<
+  T["ChartOfAccounts"]
+>;
+export type ChartOfAccountsCreate<T extends { ChartOfAccounts: object }> = Insertable<
+  T["ChartOfAccounts"]
+>;
+export type ChartOfAccountsUpdate<T extends { ChartOfAccounts: object }> = Updateable<
+  T["ChartOfAccounts"]
+>;
+
+export type AccountGroup<T extends { AccountGroup: object }> = Selectable<T["AccountGroup"]>;
+export type AccountGroupCreate<T extends { AccountGroup: object }> = Insertable<T["AccountGroup"]>;
+export type AccountGroupUpdate<T extends { AccountGroup: object }> = Updateable<T["AccountGroup"]>;
+
+export type Account<T extends { Account: object }> = Selectable<T["Account"]>;
+export type AccountCreate<T extends { Account: object }> = Insertable<T["Account"]>;
+export type AccountUpdate<T extends { Account: object }> = Updateable<T["Account"]>;

package/src/modules/coa-management/module.ts

@@ -0,0 +1,136 @@
+import { type TailorAnyDBField } from "@tailor-platform/sdk";
+import { type EmptyFields, type FieldsToInsertable } from "../../shared";
+import type { defineModule as defineOrganizationModule } from "../organization";
+import type { defineModule as definePrimitivesModule } from "../primitives";
+import type { TemplateProvider, AuditCommands } from "./command/createChartOfAccounts";
+// Commands
+import { createChartOfAccounts } from "./command/createChartOfAccounts.generated";
+import { updateChartOfAccounts } from "./command/updateChartOfAccounts.generated";
+import { activateChartOfAccounts } from "./command/activateChartOfAccounts.generated";
+import { deactivateChartOfAccounts } from "./command/deactivateChartOfAccounts.generated";
+import { deleteChartOfAccounts } from "./command/deleteChartOfAccounts.generated";
+import { createAccountGroup } from "./command/createAccountGroup.generated";
+import { updateAccountGroup } from "./command/updateAccountGroup.generated";
+import { moveAccountGroup } from "./command/moveAccountGroup.generated";
+import { deleteAccountGroup } from "./command/deleteAccountGroup.generated";
+import { createAccount } from "./command/createAccount.generated";
+import { updateAccount } from "./command/updateAccount.generated";
+import { activateAccount } from "./command/activateAccount.generated";
+import { deactivateAccount } from "./command/deactivateAccount.generated";
+import { reactivateAccount } from "./command/reactivateAccount.generated";
+import { deleteAccount } from "./command/deleteAccount.generated";
+// Queries
+import { getChartOfAccounts } from "./query/getChartOfAccounts.generated";
+import { getAccount } from "./query/getAccount.generated";
+import { getAccountGroup } from "./query/getAccountGroup.generated";
+import { listAccounts } from "./query/listAccounts.generated";
+import { listUnassignedAccounts } from "./query/listUnassignedAccounts.generated";
+import { listAccountGroups } from "./query/listAccountGroups.generated";
+import { detectCircularReference } from "./query/detectCircularReference.generated";
+// DB types
+import {
+  createChartOfAccountsType,
+  type CreateChartOfAccountsTypeParams,
+} from "./db/chartOfAccounts";
+import { createAccountGroupType, type CreateAccountGroupTypeParams } from "./db/accountGroup";
+import { createAccountType, type CreateAccountTypeParams } from "./db/account";
+
+type OrganizationModule = ReturnType<typeof defineOrganizationModule>;
+type OrganizationDB = OrganizationModule["db"];
+export type OrganizationQueries = OrganizationModule["queries"];
+
+type PrimitivesModule = ReturnType<typeof definePrimitivesModule>;
+type PrimitivesDB = PrimitivesModule["db"];
+export type PrimitivesQueries = PrimitivesModule["queries"];
+
+export interface DefineModuleParams<
+  COAF extends Record<string, TailorAnyDBField>,
+  AGF extends Record<string, TailorAnyDBField>,
+  AF extends Record<string, TailorAnyDBField>,
+> {
+  chartOfAccounts?: CreateChartOfAccountsTypeParams<COAF>;
+  accountGroup?: CreateAccountGroupTypeParams<AGF>;
+  account?: CreateAccountTypeParams<AF>;
+  organization: {
+    db: { company: OrganizationDB["company"] };
+    queries: Pick<OrganizationQueries, "getCompany">;
+  };
+  primitives: {
+    db: { currency: PrimitivesDB["currency"] };
+    queries: Pick<PrimitivesQueries, "getCurrency">;
+  };
+  templateProvider?: TemplateProvider;
+  audit?: {
+    commands: AuditCommands;
+  };
+}
+
+export const defineModule = <
+  const COAF extends Record<string, TailorAnyDBField> = EmptyFields,
+  const AGF extends Record<string, TailorAnyDBField> = EmptyFields,
+  const AF extends Record<string, TailorAnyDBField> = EmptyFields,
+>(
+  params: DefineModuleParams<COAF, AGF, AF>,
+) => {
+  const chartOfAccountsDb = createChartOfAccountsType({
+    ...params.chartOfAccounts,
+    companyType: params.organization.db.company,
+    currencyType: params.primitives.db.currency,
+  });
+  const accountGroupDb = createAccountGroupType({
+    ...params.accountGroup,
+    chartOfAccountsType: chartOfAccountsDb,
+  });
+  const accountDb = createAccountType({
+    ...params.account,
+    chartOfAccountsType: chartOfAccountsDb,
+    accountGroupType: accountGroupDb,
+    currencyType: params.primitives.db.currency,
+  });
+
+  const auditCommands = params.audit?.commands;
+
+  return {
+    db: {
+      chartOfAccounts: chartOfAccountsDb,
+      accountGroup: accountGroupDb,
+      account: accountDb,
+    },
+    commands: {
+      createChartOfAccounts: createChartOfAccounts<FieldsToInsertable<COAF>>(
+        params.organization.queries,
+        params.templateProvider,
+        auditCommands,
+      ),
+      updateChartOfAccounts: updateChartOfAccounts<FieldsToInsertable<COAF>>(auditCommands),
+      activateChartOfAccounts: activateChartOfAccounts(auditCommands),
+      deactivateChartOfAccounts: deactivateChartOfAccounts(auditCommands),
+      deleteChartOfAccounts: deleteChartOfAccounts(auditCommands),
+      createAccountGroup: createAccountGroup<FieldsToInsertable<AGF>>(auditCommands),
+      updateAccountGroup: updateAccountGroup<FieldsToInsertable<AGF>>(auditCommands),
+      moveAccountGroup: moveAccountGroup(auditCommands),
+      deleteAccountGroup: deleteAccountGroup(auditCommands),
+      createAccount: createAccount<FieldsToInsertable<AF>>(
+        params.primitives.queries,
+        auditCommands,
+      ),
+      updateAccount: updateAccount<FieldsToInsertable<AF>>(
+        params.primitives.queries,
+        auditCommands,
+      ),
+      activateAccount: activateAccount(auditCommands),
+      deactivateAccount: deactivateAccount(auditCommands),
+      reactivateAccount: reactivateAccount(auditCommands),
+      deleteAccount: deleteAccount(auditCommands),
+    },
+    queries: {
+      getChartOfAccounts,
+      getAccount,
+      getAccountGroup,
+      listAccounts,
+      listUnassignedAccounts,
+      listAccountGroups,
+      detectCircularReference,
+    },
+  };
+};

package/src/modules/coa-management/permissions.ts

@@ -0,0 +1,3 @@
+import { definePermissions } from "../../shared";
+
+export const { permissions, own, all } = definePermissions("coa-management", [] as const);

package/src/modules/coa-management/query/detectCircularReference.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { defineQuery } from "../../../shared";
+import { run } from "./detectCircularReference";
+
+export const detectCircularReference = defineQuery(run);

package/src/modules/coa-management/query/detectCircularReference.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { baseRootGroup, baseChildGroup, baseGrandchildGroup } from "../testing/fixtures";
+import { run } from "./detectCircularReference";
+
+describe("detectCircularReference", () => {
+  it("detects self-reference as circular", async () => {
+    const { db } = createMockDb<DB>();
+
+    const result = await run(db, { groupId: "group-1", newParentId: "group-1" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.isCircular).toBe(true);
+    }
+  });
+
+  it("detects moving group under its child as circular", async () => {
+    const { db, spies } = createMockDb<DB>();
+    // Walking up from group-2 (child): parent is group-1 (the group being moved)
+    spies.select.mockReturnValueOnce(baseChildGroup); // group-2's parent is group-1
+
+    const result = await run(db, { groupId: "group-1", newParentId: "group-2" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.isCircular).toBe(true);
+    }
+  });
+
+  it("detects moving group under its grandchild as circular", async () => {
+    const { db, spies } = createMockDb<DB>();
+    // Walking up from group-3: parent is group-2
+    spies.select
+      .mockReturnValueOnce(baseGrandchildGroup) // group-3's parent is group-2
+      .mockReturnValueOnce(baseChildGroup); // group-2's parent is group-1
+
+    const result = await run(db, { groupId: "group-1", newParentId: "group-3" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.isCircular).toBe(true);
+    }
+  });
+
+  it("returns not circular for valid move", async () => {
+    const { db, spies } = createMockDb<DB>();
+    // Walking up from group-4 (root, no parent)
+    spies.select.mockReturnValueOnce({
+      ...baseRootGroup,
+      id: "group-4",
+      parentAccountGroupId: null,
+    });
+
+    const result = await run(db, { groupId: "group-2", newParentId: "group-4" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.isCircular).toBe(false);
+    }
+  });
+
+  it("returns not circular when new parent is root", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseRootGroup); // group-1 is root (parentAccountGroupId: null)
+
+    const result = await run(db, { groupId: "group-2", newParentId: "group-1" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.isCircular).toBe(false);
+    }
+  });
+
+  it("handles broken ancestor chain gracefully (not circular)", async () => {
+    const { db, spies } = createMockDb<DB>();
+    // Parent not found in DB
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { groupId: "group-1", newParentId: "group-unknown" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.isCircular).toBe(false);
+    }
+  });
+});

package/src/modules/coa-management/query/detectCircularReference.ts

@@ -0,0 +1,46 @@
+import { ok, type ReadonlyDB } from "../../../shared";
+import type { DB } from "../generated/kysely-tailordb";
+
+export interface DetectCircularReferenceInput {
+  groupId: string;
+  newParentId: string;
+}
+
+/**
+ * Function: detectCircularReference
+ *
+ * Validates that reparenting an account group would not create a circular
+ * reference in the tree hierarchy.
+ */
+export async function run(db: ReadonlyDB<DB>, input: DetectCircularReferenceInput) {
+  const { groupId, newParentId } = input;
+
+  // Self-reference is always circular
+  if (newParentId === groupId) {
+    return ok({ isCircular: true });
+  }
+
+  // Walk up the ancestor chain from newParentId
+  let ancestorId: string | null = newParentId;
+
+  while (ancestorId) {
+    const ancestor = await db
+      .selectFrom("AccountGroup")
+      .selectAll()
+      .where("id", "=", ancestorId)
+      .executeTakeFirst();
+
+    if (!ancestor) {
+      // Broken chain — no cycle
+      return ok({ isCircular: false });
+    }
+
+    ancestorId = ancestor.parentAccountGroupId;
+
+    if (ancestorId === groupId) {
+      return ok({ isCircular: true });
+    }
+  }
+
+  return ok({ isCircular: false });
+}

package/src/modules/coa-management/query/getAccount.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { defineQuery } from "../../../shared";
+import { run } from "./getAccount";
+
+export const getAccount = defineQuery(run);