@accounter/server 0.0.9-alpha-20251231123714-6cdd9de71b4672d74ece5d34c438d162987b2c93 → 0.0.9-alpha-20251231163357-33d4c33fec5e21dad2e04d1f293f6248d2550588

package/scripts/seed-admin-context.ts

@@ -44,37 +44,22 @@ export async function seedAdminCore(client: PoolClient): Promise<{ adminEntityId
   console.log('Creating admin business entity...');
 
   // First check if admin entity already exists (by name and type, ignoring owner_id for admin)
-  const existingAdmin = await client.query(
-    `SELECT id FROM accounter_schema.financial_entities 
-     WHERE name = $1 AND type = $2 
-     ORDER BY created_at ASC
-     LIMIT 1`,
-    ['Admin Business', 'business'],
-  );
-
-  let adminEntityId: string;
-  if (existingAdmin.rows.length > 0) {
-    adminEntityId = existingAdmin.rows[0].id;
-    console.log(`ℹ️  Admin entity already exists: ${adminEntityId}`);
-  } else {
-    const { id } = await ensureFinancialEntity(client, {
-      name: 'Admin Business',
-      type: 'business',
-    });
-    adminEntityId = id;
-    console.log(`✅ Admin entity: ${adminEntityId}`);
-
-    // Create corresponding business record
-    await ensureBusinessForEntity(client, adminEntityId);
-    console.log('✅ Admin business record created');
-
-    // Update owner_id to self
-    await client.query(
-      `UPDATE accounter_schema.financial_entities SET owner_id = $1 WHERE id = $1`,
-      [adminEntityId],
-    );
-    console.log('✅ Admin entity owner_id set to self');
-  }
+  const { id } = await ensureFinancialEntity(client, {
+    name: 'Admin Business',
+    type: 'business',
+  });
+  const adminEntityId = id;
+  console.log(`✅ Admin entity: ${adminEntityId}`);
+
+  // Create corresponding business record
+  await ensureBusinessForEntity(client, adminEntityId);
+  console.log('✅ Admin business record created');
+
+  // Update owner_id to self
+  await client.query(`UPDATE accounter_schema.financial_entities SET owner_id = $1 WHERE id = $1`, [
+    adminEntityId,
+  ]);
+  console.log('✅ Admin entity owner_id set to self');
 
   // 2. Create authority businesses
   const authorities = {
@@ -88,9 +73,10 @@ export async function seedAdminCore(client: PoolClient): Promise<{ adminEntityId
     const { id } = await ensureFinancialEntity(client, {
       name,
       type: 'business',
+      ownerId: adminEntityId,
     });
     authorityBusinessIds[name] = id;
-    await ensureBusinessForEntity(client, id, { noInvoicesRequired: true });
+    await ensureBusinessForEntity(client, id, { isDocumentsOptional: true });
   }
   console.log(`✅ Created ${authorities.businesses.length} authority businesses`);
 
@@ -101,6 +87,7 @@ export async function seedAdminCore(client: PoolClient): Promise<{ adminEntityId
     const { id } = await ensureFinancialEntity(client, {
       name,
       type: 'tax_category',
+      ownerId: adminEntityId,
     });
     authorityTaxCategoryIds[name] = id;
     await ensureTaxCategoryForEntity(client, id);
@@ -129,6 +116,7 @@ export async function seedAdminCore(client: PoolClient): Promise<{ adminEntityId
     const { id } = await ensureFinancialEntity(client, {
       name,
       type: 'tax_category',
+      ownerId: adminEntityId,
     });
     generalTaxCategoryIds[name] = id;
     await ensureTaxCategoryForEntity(client, id);
@@ -149,6 +137,7 @@ export async function seedAdminCore(client: PoolClient): Promise<{ adminEntityId
     const { id } = await ensureFinancialEntity(client, {
       name,
       type: 'tax_category',
+      ownerId: adminEntityId,
     });
     crossYearTaxCategoryIds[name] = id;
     await ensureTaxCategoryForEntity(client, id);
@@ -199,7 +188,7 @@ export async function seedAdminCore(client: PoolClient): Promise<{ adminEntityId
     const values = Object.values(context);
 
     await client.query(
-      `INSERT INTO accounter_schema.user_context (${columns}) VALUES (${placeholders})`,
+      `INSERT INTO accounter_schema.user_context (${columns}) VALUES (${placeholders}) ON CONFLICT (owner_id) DO NOTHING`,
       values,
     );
     console.log('✅ user_context created');

package/src/__tests__/db-bootstrap.test.ts

@@ -3,6 +3,7 @@ import { TestDatabase, isPoolHealthy } from './helpers/db-setup.js';
 import { assertLatestMigrationApplied } from './helpers/migration-verification.js';
 import { seedAdminCore } from '../../scripts/seed-admin-context.js';
 import { qualifyTable } from './helpers/test-db-config.js';
+import { buildAdminContextFromDb } from './helpers/admin-context-builder.js';
 
 /**
  * Smoke test for DB test harness
@@ -67,8 +68,12 @@ describe('DB Test Harness Bootstrap', () => {
   it('has expected tax categories', async () =>
     db.withTransaction(async client => {
       await seedAdminCore(client);
+      const adminContext = await buildAdminContextFromDb(client);
       const result = await client.query(
-        `SELECT COUNT(*) FROM ${qualifyTable('tax_categories')}`,
+        `SELECT COUNT(tc.*) FROM ${qualifyTable('tax_categories')} tc
+        LEFT JOIN ${qualifyTable('financial_entities')} fe USING (id)
+        WHERE owner_id = $1`,
+        [adminContext.defaultAdminBusinessId]
       );
       const count = parseInt(result.rows[0].count, 10);
       expect(count).toBe(EXPECTED_TAX_CATEGORIES);
@@ -77,8 +82,10 @@ describe('DB Test Harness Bootstrap', () => {
   it('has user_context after seeding', async () =>
     db.withTransaction(async client => {
       await seedAdminCore(client);
+      const adminContext = await buildAdminContextFromDb(client);
       const result = await client.query(
-        `SELECT owner_id, vat_business_id FROM ${qualifyTable('user_context')} LIMIT 1`,
+        `SELECT owner_id, vat_business_id FROM ${qualifyTable('user_context')} WHERE owner_id = $1 LIMIT 1`,
+        [adminContext.defaultAdminBusinessId]
       );
       expect(result.rows).toHaveLength(1);
       expect(result.rows[0].owner_id).toBeDefined();

package/src/__tests__/factories/business.ts

@@ -1,6 +1,6 @@
 import { makeUUIDLegacy } from '../../demo-fixtures/helpers/deterministic-uuid.js';
 import { CountryCode } from '../../shared/enums.js';
-import { FixtureBusinesses } from '__tests__/helpers/fixture-types.js';
+import { FixtureBusinesses } from '../helpers/fixture-types.js';
 
 /**
  * Business factory for test fixtures

package/src/__tests__/factories/financial-account.ts

@@ -2,7 +2,7 @@ import type {
   financial_account_type,
 } from '../../modules/financial-accounts/__generated__/financial-accounts.types.js';
 import { makeUUIDLegacy } from '../../demo-fixtures/helpers/deterministic-uuid.js';
-import { FixtureAccounts } from '__tests__/helpers/fixture-types.js';
+import { FixtureAccounts } from '../helpers/fixture-types.js';
 
 /**
  * Valid financial account types

package/src/__tests__/factories/index.test.ts

@@ -45,6 +45,7 @@ describe('Factory Integration', () => {
     const taxCategoryId = makeUUID('tax-category', 'tax-expense');
     const taxCategory = createTaxCategory({
       id: taxCategoryId,
+      name: 'Expense Tax',
     });
 
     const accountId = makeUUID('financial-account', 'bank-account');

package/src/__tests__/factories/tax-category.test.ts

@@ -6,7 +6,7 @@ import { createTaxCategory } from './tax-category.js';
 describe('Factory: Tax Category', () => {
   describe('createTaxCategory', () => {
     it('should create tax category with default values', () => {
-      const category = createTaxCategory();
+      const category = createTaxCategory({name: 'Default Category'});
 
       // Required field with default
       expect(category.id).toBeDefined();
@@ -20,8 +20,8 @@ describe('Factory: Tax Category', () => {
     });
 
     it('should generate unique IDs by default', () => {
-      const category1 = createTaxCategory();
-      const category2 = createTaxCategory();
+      const category1 = createTaxCategory({name: 'Category 1'});
+      const category2 = createTaxCategory({name: 'Category 2'});
 
       expect(category1.id).not.toBe(category2.id);
     });
@@ -50,7 +50,7 @@ describe('Factory: Tax Category', () => {
     });
 
     it('should preserve all required fields', () => {
-      const category = createTaxCategory();
+      const category = createTaxCategory({name: 'Default Category'});
 
       // Verify structure matches expected pgtyped interface
       expect(category).toHaveProperty('id');
@@ -61,6 +61,7 @@ describe('Factory: Tax Category', () => {
     it('should handle tax-excluded categories', () => {
       const category = createTaxCategory({
         taxExcluded: true,
+        name: 'Tax Exempt',
       });
 
       expect(category.taxExcluded).toBe(true);
@@ -78,14 +79,15 @@ describe('Factory: Tax Category', () => {
     it('should allow explicit null overrides', () => {
       const category = createTaxCategory({
         hashavshevetName: null,
+        name: 'No Integration',
       });
 
       expect(category.hashavshevetName).toBeNull();
     });
 
     it('should create deterministic categories with seed', () => {
-      const category1 = createTaxCategory({ id: makeUUID('tax-category', 'default-category') });
-      const category2 = createTaxCategory({ id: makeUUID('tax-category', 'default-category') });
+      const category1 = createTaxCategory({ id: makeUUID('tax-category', 'default-category'), name: 'Default Category' });
+      const category2 = createTaxCategory({ id: makeUUID('tax-category', 'default-category'), name: 'Default Category' });
 
       expect(category1.id).toBe(category2.id);
     });

package/src/__tests__/factories/tax-category.ts

@@ -1,5 +1,5 @@
 import { makeUUIDLegacy } from '../../demo-fixtures/helpers/deterministic-uuid.js';
-import { FixtureTaxCategories } from '__tests__/helpers/fixture-types.js';
+import { FixtureTaxCategories } from '../helpers/fixture-types.js';
 
 /**
  * Tax category factory for test fixtures
@@ -41,7 +41,7 @@ export function createTaxCategory(
     id: defaultId,
     // Intelligent name defaulting: use provided id, or use generated UUID
     // This ensures display name is always meaningful even when only id is specified
-    name: overrides?.id ?? defaultId,
+    name: overrides?.name ?? overrides?.id ?? defaultId,
     hashavshevetName: null,
     taxExcluded: false,
     ...overrides,

package/src/__tests__/helpers/fixture-loader.ts

@@ -13,6 +13,8 @@ import type { Fixture } from './fixture-types.js';
 import { assertValidFixture } from './fixture-validation.js';
 import { qualifyTable } from './test-db-config.js';
 import { makeUUID, makeUUIDLegacy } from '../../demo-fixtures/helpers/deterministic-uuid.js';
+import { UUID_REGEX } from '../../shared/constants.js';
+import { ensureBusinessForEntity, ensureFinancialEntity, ensureTaxCategoryForEntity } from './seed-helpers.js';
 
 /**
  * Custom error for fixture insertion failures
@@ -118,6 +120,7 @@ export type FixtureIdMapping = Map<string, string>;
 export async function insertFixture(
   client: PoolClient | Client,
   fixture: Fixture,
+  adminBusinessId?: string,
 ): Promise<FixtureIdMapping> {
   // Validate fixture before insertion
   assertValidFixture(fixture);
@@ -153,49 +156,19 @@ export async function insertFixture(
       for (const business of fixture.businesses!.businesses) {
         // Insert financial entity first (type='business')
         // Field mapping: business.name used for display (required); hebrewName is legacy/optional
-        const entityResult = await client.query(
-          `INSERT INTO ${qualifyTable('financial_entities')} (id, name, type)
-           VALUES ($1, $2, 'business')
-           ON CONFLICT (id) DO NOTHING
-           RETURNING id`,
-          [business.id, business.name || business.id],
-        );
+        const {id: entityId} = await ensureFinancialEntity(client, {
+          id: business.id,
+          name: business.name || business.id!,
+          type: 'business',
+          ownerId: adminBusinessId,
+        });
+
+        const {id: businessId, ...options } = business;
 
         // Insert business details - note: vat_number column maps to governmentId field
-        await client.query(
-          `INSERT INTO ${qualifyTable('businesses')} (
-            id, hebrew_name, address, city, zip_code, email, website, phone_number, vat_number,
-            exempt_dealer, suggestion_data, optional_vat, country,
-            pcn874_record_type_override, can_settle_with_receipt, no_invoices_required
-          )
-          VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16)
-          ON CONFLICT (id) DO NOTHING`,
-          [
-            business.id,
-            business.hebrewName,
-            business.address,
-            business.city,
-            business.zipCode,
-            business.email,
-            business.website,
-            business.phoneNumber,
-            business.governmentId, // Maps to vat_number column
-            business.exemptDealer ?? false,
-            business.suggestions ?? null,
-            business.optionalVat ?? false,
-            business.country ?? 'ISR',
-            business.pcn874RecordTypeOverride ?? null,
-            business.isReceiptEnough ?? false,
-            business.isDocumentsOptional ?? false,
-          ],
-        );
+        await ensureBusinessForEntity(client, entityId, options)
 
-        if (entityResult.rows.length > 0) {
-          idMapping.set(business.id!, entityResult.rows[0].id);
-        } else {
-          // Entity already existed, map to itself
-          idMapping.set(business.id!, business.id!);
-        }
+        idMapping.set(business.id!, entityId);
       }
     });
   }
@@ -205,29 +178,21 @@ export async function insertFixture(
     await executeSavepointSection('tax_categories', async () => {
       for (const taxCategory of fixture.taxCategories!.taxCategories) {
         // Insert financial entity first
-        const entityResult = await client.query(
-          `INSERT INTO ${qualifyTable('financial_entities')} (id, name, type)
-           VALUES ($1, $2, 'tax_category')
-           ON CONFLICT (id) DO NOTHING
-           RETURNING id`,
-          [taxCategory.id, taxCategory.hashavshevetName || taxCategory.id],
-        );
+        const {id: entityId} = await ensureFinancialEntity(client, {
+          id: taxCategory.id,
+          name: taxCategory.name || taxCategory.id!,
+          type: 'tax_category',
+          ownerId: adminBusinessId,
+        });
 
         // Insert tax category details
-        await client.query(
-          `INSERT INTO ${qualifyTable('tax_categories')} (
-            id, hashavshevet_name, tax_excluded
-          )
-          VALUES ($1, $2, $3)
-          ON CONFLICT (id) DO NOTHING`,
-          [taxCategory.id, taxCategory.hashavshevetName, taxCategory.taxExcluded ?? false],
-        );
+        await ensureTaxCategoryForEntity(client, entityId, {
+          name: taxCategory.name,
+          hashavshevetName: taxCategory.hashavshevetName,
+          taxExcluded: taxCategory.taxExcluded,
+        });
 
-        if (entityResult.rows.length > 0) {
-          idMapping.set(taxCategory.id!, entityResult.rows[0].id);
-        } else {
-          idMapping.set(taxCategory.id!, taxCategory.id!);
-        }
+        idMapping.set(taxCategory.id!, entityId);
       }
     });
   }
@@ -328,7 +293,7 @@ export async function insertFixture(
       for (const transaction of fixture.transactions!.transactions) {
         // If account_id looks like an account_number (not a UUID), look up the actual UUID
         let accountId = transaction.account_id;
-        if (accountId && !accountId.match(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i)) {
+        if (accountId && !accountId.match(UUID_REGEX)) {
           // account_id is actually an account_number, look up the UUID
           const accountResult = await client.query(
             `SELECT id FROM ${qualifyTable('financial_accounts')} WHERE account_number = $1`,

package/src/__tests__/helpers/migration-verification.ts

@@ -1,4 +1,4 @@
-import { Client, Pool, PoolClient } from 'pg';
+import { type Client, Pool, type PoolClient } from 'pg';
 import { LATEST_MIGRATION_NAME } from '../../../../migrations/src/run-pg-migrations.js';
 
 export { LATEST_MIGRATION_NAME };
@@ -71,4 +71,4 @@ export async function assertLatestMigrationApplied(
         `Migration check failed for ${result.latestMigrationName}. Run: yarn workspace @accounter/migrations migration:run`,
     );
   }
-}
+}

package/src/__tests__/helpers/seed-helpers.business.test.ts

@@ -70,7 +70,7 @@ describe('ensureBusinessForEntity', () => {
       });
 
       // Ensure business with noInvoicesRequired set to true
-      await ensureBusinessForEntity(client, entityId, { noInvoicesRequired: true });
+      await ensureBusinessForEntity(client, entityId, { isDocumentsOptional: true });
 
       // Verify business has correct option set
       const result = await client.query(
@@ -112,11 +112,11 @@ describe('ensureBusinessForEntity', () => {
         type: 'business',
       });
 
-      // Create business with noInvoicesRequired = true
-      await ensureBusinessForEntity(client, entityId, { noInvoicesRequired: true });
+      // Create business with isDocumentsOptional = true
+      await ensureBusinessForEntity(client, entityId, { isDocumentsOptional: true });
 
       // Call again with different options (should be no-op)
-      await ensureBusinessForEntity(client, entityId, { noInvoicesRequired: false });
+      await ensureBusinessForEntity(client, entityId, { isDocumentsOptional: false });
 
       // Verify original value is preserved
       const result = await client.query(

package/src/__tests__/helpers/seed-helpers.ts

@@ -1,6 +1,9 @@
-import type { PoolClient } from 'pg';
+import type { Client, PoolClient } from 'pg';
 import { qualifyTable } from './test-db-config.js';
 import { EntityValidationError, SeedError } from './seed-errors.js';
+import { makeUUID } from '../factories/index.js';
+import { UUID_REGEX } from '../../shared/constants.js';
+import type {FixtureBusinesses, FixtureTaxCategories} from './fixture-types.js';
 
 /**
  * Valid financial entity types based on database schema
@@ -13,6 +16,7 @@ export type FinancialEntityType = 'business' | 'tax_category' | 'tag';
 const VALID_ENTITY_TYPES: readonly FinancialEntityType[] = ['business', 'tax_category', 'tag'];
 
 export interface EnsureFinancialEntityParams {
+  id?: string;
   name: string;
   type: FinancialEntityType;
   ownerId?: string;
@@ -68,10 +72,10 @@ export interface FinancialEntityResult {
  * ```
  */
 export async function ensureFinancialEntity(
-  client: PoolClient,
+  client: PoolClient | Client,
   params: EnsureFinancialEntityParams,
 ): Promise<FinancialEntityResult> {
-  const { name, type, ownerId } = params;
+  const { name, type, ownerId, id: originId } = params;
 
   // Validate inputs
   const validationErrors: string[] = [];
@@ -91,41 +95,32 @@ export async function ensureFinancialEntity(
   }
 
   try {
-    // Check if entity already exists
-    const selectQuery = `
-      SELECT id
-      FROM ${qualifyTable('financial_entities')}
-      WHERE name = $1
-        AND type = $2
-        AND (owner_id = $3 OR (owner_id IS NULL AND $3 IS NULL))
-      LIMIT 1
-    `;
-
-    const existingResult = await client.query<{ id: string }>(
-      selectQuery,
-      [name, type, ownerId ?? null],
-    );
-
-    if (existingResult.rows.length > 0) {
-      return { id: existingResult.rows[0].id };
-    }
-
-    // Insert new entity
+    // Generate deterministic UUID based on type, name, and ownerId for idempotency
+    // Same (type, name, ownerId) always generates same ID, ensuring multiple calls are safe
+    // Include ownerId in the composite key so different owners get different IDs
+    const compositeKey = ownerId ? `${name}:owner=${ownerId}` : name;
+    const consistentId = originId ?? makeUUID(type, compositeKey);
+
+    // Use atomic INSERT...ON CONFLICT on PRIMARY KEY (id) to handle concurrent inserts
+    // If the deterministic ID already exists (from a previous call or concurrent insert),
+    // the conflict handler will safely return the existing row
     const insertQuery = `
-      INSERT INTO ${qualifyTable('financial_entities')} (name, type, owner_id)
-      VALUES ($1, $2, $3)
+      INSERT INTO ${qualifyTable('financial_entities')} (id, name, type, owner_id)
+      VALUES ($1, $2, $3, $4)
+      ON CONFLICT (id) DO UPDATE
+      SET id = EXCLUDED.id  -- No-op update, just to return the existing id
       RETURNING id
     `;
 
-    const insertResult = await client.query<{ id: string }>(
+    const result = await client.query<{ id: string }>(
       insertQuery,
-      [name, type, ownerId ?? null],
+      [consistentId, name, type, ownerId ?? null],
     );
 
-    const row = insertResult.rows[0];
+    const row = result.rows[0];
     if (!row) {
       throw new SeedError(
-        'INSERT returned no rows',
+        'INSERT...ON CONFLICT returned no rows',
         { name, type, ownerId },
       );
     }
@@ -144,9 +139,7 @@ export async function ensureFinancialEntity(
   }
 }
 
-export interface EnsureBusinessForEntityOptions {
-  noInvoicesRequired?: boolean;
-}
+export type EnsureBusinessForEntityOptions = Partial<Omit<FixtureBusinesses['businesses'][number], 'id'>>
 
 /**
  * Ensure a business row exists for a given financial entity id (idempotent)
@@ -190,13 +183,12 @@ export interface EnsureBusinessForEntityOptions {
  * ```
  */
 export async function ensureBusinessForEntity(
-  client: PoolClient,
+  client: PoolClient | Client,
   entityId: string,
   options?: EnsureBusinessForEntityOptions,
 ): Promise<void> {
   // Validate entityId format (basic UUID check)
-  const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-  if (!uuidPattern.test(entityId)) {
+  if (!UUID_REGEX.test(entityId)) {
     throw new EntityValidationError(
       'Business',
       ['entityId must be a valid UUID'],
@@ -223,27 +215,36 @@ export async function ensureBusinessForEntity(
       );
     }
 
-    // Check if business already exists
-    const selectQuery = `
-      SELECT 1
-      FROM ${qualifyTable('businesses')}
-      WHERE id = $1
-      LIMIT 1
-    `;
-
-    const existingResult = await client.query(selectQuery, [entityId]);
-
-    if (existingResult.rows.length > 0) {
-      return; // Business already exists, preserve existing values
-    }
-
-    // Insert new business
+    // Use atomic INSERT...ON CONFLICT on PRIMARY KEY (id) to handle concurrent inserts
+    // If the deterministic ID already exists (from a previous call or concurrent insert),
+    // the conflict handler will safely return the existing row
     const insertQuery = `
-      INSERT INTO ${qualifyTable('businesses')} (id, no_invoices_required)
-      VALUES ($1, $2)
+      INSERT INTO ${qualifyTable('businesses')} (
+        id, hebrew_name, address, city, zip_code, email, website, phone_number, vat_number,
+        exempt_dealer, suggestion_data, optional_vat, country,
+        pcn874_record_type_override, can_settle_with_receipt, no_invoices_required
+      )
+      VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16)
+      ON CONFLICT (id) DO NOTHING
     `;
 
-    await client.query(insertQuery, [entityId, options?.noInvoicesRequired ?? false]);
+    await client.query(insertQuery, [
+            entityId,
+            options?.hebrewName,
+            options?.address,
+            options?.city,
+            options?.zipCode,
+            options?.email,
+            options?.website,
+            options?.phoneNumber,
+            options?.governmentId, // Maps to vat_number column
+            options?.exemptDealer ?? false,
+            options?.suggestions ?? null,
+            options?.optionalVat ?? false,
+            options?.country ?? 'ISR',
+            options?.pcn874RecordTypeOverride ?? null,
+            options?.isReceiptEnough ?? false,
+            options?.isDocumentsOptional ?? false]);
   } catch (error) {
     if (error instanceof EntityValidationError || error instanceof SeedError) {
       throw error;
@@ -257,7 +258,7 @@ export async function ensureBusinessForEntity(
   }
 }
 
-export interface EnsureTaxCategoryForEntityOptions {
+export type EnsureTaxCategoryForEntityOptions = Partial<Omit<FixtureTaxCategories['taxCategories'][number], 'id'>> & {
   sortCode?: number;
 }
 
@@ -307,13 +308,12 @@ export interface EnsureTaxCategoryForEntityOptions {
  * ```
  */
 export async function ensureTaxCategoryForEntity(
-  client: PoolClient,
+  client: PoolClient | Client,
   entityId: string,
   options?: EnsureTaxCategoryForEntityOptions,
 ): Promise<void> {
   // Validate entityId format (basic UUID check)
-  const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-  if (!uuidPattern.test(entityId)) {
+  if (!UUID_REGEX.test(entityId)) {
     throw new EntityValidationError(
       'TaxCategory',
       ['entityId must be a valid UUID'],
@@ -340,27 +340,18 @@ export async function ensureTaxCategoryForEntity(
       );
     }
 
-    // Check if tax category already exists
-    const selectQuery = `
-      SELECT 1
-      FROM ${qualifyTable('tax_categories')}
-      WHERE id = $1
-      LIMIT 1
-    `;
-
-    const existingResult = await client.query(selectQuery, [entityId]);
-
-    if (existingResult.rows.length > 0) {
-      return; // Tax category already exists, preserve existing values
-    }
-
-    // Insert new tax category
+    // Use atomic INSERT...ON CONFLICT on PRIMARY KEY (id) to handle concurrent inserts
+    // If the deterministic ID already exists (from a previous call or concurrent insert),
+    // the conflict handler will safely return the existing row
     const insertQuery = `
-      INSERT INTO ${qualifyTable('tax_categories')} (id)
-      VALUES ($1)
+      INSERT INTO ${qualifyTable('tax_categories')} (
+        id, hashavshevet_name, tax_excluded
+      )
+      VALUES ($1, $2, $3)
+      ON CONFLICT (id) DO NOTHING
     `;
 
-    await client.query(insertQuery, [entityId]);
+    await client.query(insertQuery, [entityId, options?.hashavshevetName, options?.taxExcluded ?? false]);
   } catch (error) {
     if (error instanceof EntityValidationError || error instanceof SeedError) {
       throw error;

package/src/__tests__/seed-admin-context.integration.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it, beforeAll, afterAll } from 'vitest';
 import { TestDatabase } from './helpers/db-setup.js';
 import { seedAdminCore } from '../../scripts/seed-admin-context.js';
+import { UUID_REGEX } from '../shared/constants.js';
 
 describe('seedAdminCore integration', () => {
   let db: TestDatabase;
@@ -22,7 +23,7 @@ describe('seedAdminCore integration', () => {
       // Verify admin entity exists
       expect(adminEntityId).toBeTruthy();
       expect(adminEntityId).toMatch(
-        /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+        UUID_REGEX
       );
 
       // Verify admin financial entity