@open-mercato/core 0.8.1-develop.7239.1.d90c352076 → 0.8.1-develop.7241.1.fad7b2ce2a

package/src/modules/query_index/lib/coverage.ts

@@ -140,6 +140,147 @@ async function pruneDuplicateCoverageRows(
   await query.execute()
 }
 
+function coverageInitializationLockKey(scope: CoverageScope): string {
+  return [
+    scope.entityType,
+    scope.tenantId ?? '__null_tenant__',
+    normalizeOrganizationForStore(scope.organizationId ?? null),
+    scope.withDeleted === true ? 'with_deleted' : 'active_only',
+  ].join('|')
+}
+
+async function lockCoverageInitialization(db: CoverageExecutor, scope: CoverageScope): Promise<void> {
+  await sql`
+    select pg_advisory_xact_lock(
+      hashtextextended(${coverageInitializationLockKey(scope)}, 0)
+    )
+  `.execute(db)
+}
+
+async function updateCoverageRows(
+  db: CoverageExecutor,
+  scope: CoverageScope,
+  deltas: { deltaBase: number; deltaIndex: number; deltaVector: number },
+): Promise<Array<{ id: string }>> {
+  let update = db
+    .updateTable('entity_index_coverage' as any)
+    .set({
+      base_count: sql`greatest(${sql.ref('base_count')} + ${deltas.deltaBase}, 0)`,
+      indexed_count: sql`greatest(${sql.ref('indexed_count')} + ${deltas.deltaIndex}, 0)`,
+      vector_indexed_count: sql`greatest(${sql.ref('vector_indexed_count')} + ${deltas.deltaVector}, 0)`,
+      refreshed_at: sql`now()`,
+    } as any)
+    .where('entity_type' as any, '=', scope.entityType)
+    .where('with_deleted' as any, '=', scope.withDeleted === true)
+  update = scope.tenantId == null
+    ? update.where('tenant_id' as any, 'is', null as any)
+    : update.where('tenant_id' as any, '=', scope.tenantId)
+  update = applyOrganizationCondition(update as any, 'organization_id', scope.organizationId ?? null)
+  return update.returning(['id' as any]).execute() as Promise<Array<{ id: string }>>
+}
+
+// Applies a coverage delta by incrementing the stored columns in SQL (#5604). The obvious
+// alternative — read the row, add the delta in JavaScript, write the total back — is a
+// read-modify-write: two adjustments for the same scope that overlap both read the same row
+// and both write the same total, so one of them is silently lost. Incrementing in SQL makes
+// overlapping adjustments compose, and drops the `SELECT` (and the window between it and the
+// write) that made the coverage row a contention point in the first place.
+//
+// In steady state that is one statement. The extra statements are recovery paths that do not
+// fire once a scope has settled: the legacy NULL-organization fold below runs only for
+// global-organization scopes, the insert only until the scope's row exists, and the duplicate
+// prune only when the scope somehow holds more than one row.
+//
+// The statement is an `UPDATE` rather than an `INSERT … ON CONFLICT DO UPDATE`, because the
+// conflict target cannot see every scope this table stores: `entity_index_coverage_scope_idx`
+// is a plain `UNIQUE` constraint, and Postgres treats NULLs in one as distinct. For a scope
+// whose tenant is NULL — `resolveQueryIndexRecordScope`'s `global` branch, or any source row
+// with a NULL tenant column — the conflict branch would never fire, so every adjustment would
+// insert a fresh row carrying only its own delta and `pruneDuplicateCoverageRows` would then
+// delete the accumulated one. A NULL-aware `UPDATE` matches those rows, and it still adds the
+// delta to the column's own value, so it composes exactly the way the conflict branch does.
+async function incrementCoverageRow(
+  db: CoverageExecutor,
+  scope: CoverageScope,
+  deltas: { deltaBase: number; deltaIndex: number; deltaVector: number }
+): Promise<void> {
+  const storedOrgId = normalizeOrganizationForStore(scope.organizationId ?? null)
+  let deltaBase = deltas.deltaBase
+  let deltaIndex = deltas.deltaIndex
+  let deltaVector = deltas.deltaVector
+
+  if (scope.organizationId == null) {
+    // Legacy rows stored the global scope as a NULL organization; they are replaced by the
+    // placeholder-organization row. `RETURNING` carries their counts into this delta so the
+    // migration does not reset the counters (the read-modify-write this replaced folded them
+    // in via its `SELECT`, which matched NULL and placeholder alike).
+    let purge = db
+      .deleteFrom('entity_index_coverage' as any)
+      .where('entity_type' as any, '=', scope.entityType)
+      .where('with_deleted' as any, '=', scope.withDeleted === true)
+      .where('organization_id' as any, 'is', null as any)
+    purge = scope.tenantId == null
+      ? purge.where('tenant_id' as any, 'is', null as any)
+      : purge.where('tenant_id' as any, '=', scope.tenantId)
+    const purged = await purge
+      .returning(['base_count' as any, 'indexed_count' as any, 'vector_indexed_count' as any])
+      .execute() as Array<CoverageRow>
+    for (const row of purged ?? []) {
+      deltaBase += toCount(row.base_count)
+      deltaIndex += toCount(row.indexed_count)
+      deltaVector += toCount(row.vector_indexed_count)
+    }
+  }
+
+  let updated = await updateCoverageRows(db, scope, { deltaBase, deltaIndex, deltaVector })
+
+  if (updated.length === 0 && scope.tenantId == null) {
+    // The unique constraint cannot serialize a first insert whose tenant is NULL. Take a
+    // transaction-scoped lock only on this rowless branch, then repeat the UPDATE: a creator
+    // that won while we waited has committed its row, so this adjustment composes into it.
+    await lockCoverageInitialization(db, scope)
+    updated = await updateCoverageRows(db, scope, { deltaBase, deltaIndex, deltaVector })
+  }
+
+  if (updated.length > 0) {
+    // In steady state the scope holds exactly the row just incremented, so the adjustment is
+    // the single statement it is described as. Only a scope that somehow accumulated more than
+    // one row — a legacy import, or a concurrent first insert on a NULL-tenant scope, which the
+    // unique constraint cannot prevent — pays for the collapse, and only until it is collapsed.
+    if (updated.length > 1) await pruneDuplicateCoverageRows(db, scope, updated[0]!.id)
+    return
+  }
+
+  // No row for this scope yet. `ON CONFLICT` closes the insert race for scopes the unique
+  // constraint can see. NULL-tenant initialization reaches here only while holding the scoped
+  // transaction advisory lock above, so it has the same single-creator guarantee.
+  const rows = await db
+    .insertInto('entity_index_coverage' as any)
+    .values({
+      entity_type: scope.entityType,
+      tenant_id: scope.tenantId ?? null,
+      organization_id: storedOrgId,
+      with_deleted: scope.withDeleted === true,
+      base_count: Math.max(deltaBase, 0),
+      indexed_count: Math.max(deltaIndex, 0),
+      vector_indexed_count: Math.max(deltaVector, 0),
+      refreshed_at: sql`now()`,
+    } as any)
+    .onConflict((oc: any) => oc
+      .columns(['entity_type', 'tenant_id', 'organization_id', 'with_deleted'])
+      .doUpdateSet({
+        base_count: sql`greatest(${sql.ref('entity_index_coverage.base_count')} + ${deltaBase}, 0)`,
+        indexed_count: sql`greatest(${sql.ref('entity_index_coverage.indexed_count')} + ${deltaIndex}, 0)`,
+        vector_indexed_count: sql`greatest(${sql.ref('entity_index_coverage.vector_indexed_count')} + ${deltaVector}, 0)`,
+        refreshed_at: sql`now()`,
+      } as any))
+    .returning(['id' as any])
+    .execute() as Array<{ id: string }>
+
+  const keepId = rows?.[0]?.id ?? null
+  await pruneDuplicateCoverageRows(db, scope, keepId)
+}
+
 async function upsertCoverageRow(
   db: CoverageExecutor,
   scope: CoverageScope,
@@ -266,23 +407,34 @@ export async function applyCoverageAdjustments(
   options?: { trx?: CoverageExecutor },
 ): Promise<void> {
   if (!adjustments.length) return
-  const db = options?.trx ?? ((em as any).getKysely() as Kysely<any>)
-  const aggregated = aggregateAdjustments(adjustments)
+  const db = (em as any).getKysely() as Kysely<any>
+  // `em.getKysely()` hands back the EntityManager's transaction context whenever one is open,
+  // and Kysely's `Transaction` throws rather than nesting a second one. A caller already inside
+  // `em.transactional(...)` therefore gets the same guarantee the rowless nullable-tenant branch
+  // opens a transaction for, so use the ambient one instead of asking for another.
+  const ambientTrx = (db as { isTransaction?: boolean }).isTransaction === true
+    ? (db as CoverageExecutor)
+    : null
+  // Keep scope initialization in a stable order. A caller-supplied transaction retains
+  // advisory and unique-index locks until commit, so two batches that initialize the same
+  // scopes in opposite orders could otherwise deadlock.
+  const aggregated = aggregateAdjustments(adjustments).sort((left, right) => (
+    scopeKey(left.scope).localeCompare(scopeKey(right.scope))
+  ))
+  const executor = options?.trx ?? ambientTrx
   for (const entry of aggregated) {
-    const scope = entry.scope
-    const existing = await fetchCoverageRow(db, scope)
-    const currentBase = existing ? toCount(existing.base_count) : 0
-    const currentIndex = existing ? toCount(existing.indexed_count) : 0
-    const currentVector = existing ? toCount(existing.vector_indexed_count) : 0
-    const nextBase = Math.max(currentBase + entry.deltaBase, 0)
-    const nextIndex = Math.max(currentIndex + entry.deltaIndex, 0)
-    const nextVector = Math.max(currentVector + entry.deltaVector, 0)
-
-    await upsertCoverageRow(db, scope, {
-      baseCount: nextBase,
-      indexedCount: nextIndex,
-      vectorIndexedCount: nextVector,
-    })
+    const deltas = {
+      deltaBase: entry.deltaBase,
+      deltaIndex: entry.deltaIndex,
+      deltaVector: entry.deltaVector,
+    }
+    if (executor) {
+      await incrementCoverageRow(executor, entry.scope, deltas)
+    } else if (entry.scope.tenantId == null) {
+      await db.transaction().execute((trx) => incrementCoverageRow(trx, entry.scope, deltas))
+    } else {
+      await incrementCoverageRow(db, entry.scope, deltas)
+    }
   }
 }
 

package/src/modules/query_index/subscribers/delete_one.ts

@@ -99,6 +99,10 @@ export default async function handle(payload: any, ctx: { resolve: <T=any>(name:
             indexDelta: effectiveIndexDelta,
           })
           if (adjustments.length) {
+            // Stays inside the transaction: `alwaysConsistent` exists to make the read
+            // projection and its coverage counters commit together, and the adjustment is a
+            // one incrementing statement in steady state (see `applyCoverageAdjustments`), so
+            // it holds the coverage row's lock only for that statement.
             await applyCoverageAdjustments(em, adjustments, { trx })
           }
         }

package/src/modules/query_index/subscribers/upsert_one.ts

@@ -92,6 +92,10 @@ export default async function handle(payload: any, ctx: { resolve: <T=any>(name:
             indexDelta,
           })
           if (adjustments.length) {
+            // Stays inside the transaction: `alwaysConsistent` exists to make the read
+            // projection and its coverage counters commit together, and the adjustment is a
+            // one incrementing statement in steady state (see `applyCoverageAdjustments`), so
+            // it holds the coverage row's lock only for that statement.
             await applyCoverageAdjustments(em, adjustments, { trx })
           }
         }

package/src/modules/sales/data/entities.ts

@@ -806,6 +806,14 @@ export class SalesDocumentSequence {
   @Property({ name: 'document_kind', type: 'text' })
   documentKind!: SalesDocumentNumberKind
 
+  /**
+   * @deprecated Since #5604 the authoritative counter is the Postgres sequence named after
+   * this row (`sales_docseq_<id without dashes>`); `nextval` on it is what issues document
+   * numbers. This column is retained for backward compatibility, is only refreshed by
+   * `setNextSequence` and by the down-migration, and must not be read as the current value —
+   * use `SalesDocumentNumberGenerator.peekSequences()`. Scheduled for removal one minor
+   * version after the deprecation window, per BACKWARD_COMPATIBILITY.md.
+   */
   @Property({ name: 'current_value', type: 'integer', default: 0 })
   currentValue: number = 0
 

package/src/modules/sales/migrations/Migration20260825120000_sales_document_sequences_backing_sequences.ts

@@ -0,0 +1,61 @@
+import { Migration } from '@mikro-orm/migrations'
+
+/**
+ * Backs every `sales_document_sequences` registry row with a real Postgres sequence (#5604).
+ *
+ * The table itself is unchanged, so the ORM snapshot is untouched — the sequences are
+ * catalog objects MikroORM does not model. Each sequence is named after the registry row
+ * that owns it (`sales_docseq_<row id without dashes>`), which is how
+ * `SalesDocumentNumberGenerator` recomputes the name in SQL without an extra column.
+ *
+ * `current_value` is carried over as the starting point so numbering continues where it left
+ * off, and stops being authoritative from here on — see the entity's deprecation note.
+ */
+export class Migration20260825120000_sales_document_sequences_backing_sequences extends Migration {
+  override async up(): Promise<void> {
+    this.addSql(`
+      do $$
+      declare
+        registry record;
+        sequence_name text;
+      begin
+        for registry in select id, current_value from sales_document_sequences loop
+          sequence_name := 'sales_docseq_' || replace(registry.id::text, '-', '');
+          execute format(
+            'create sequence if not exists %I as bigint minvalue 1 start with 1 no cycle',
+            sequence_name
+          );
+          if coalesce(registry.current_value, 0) >= 1 then
+            execute format('select setval(%L, %s, true)', sequence_name, registry.current_value);
+          end if;
+        end loop;
+      end $$;
+    `)
+  }
+
+  override async down(): Promise<void> {
+    // Hand authority back to `current_value` before dropping the sequences, otherwise the
+    // rolled-back code resumes from a value that stopped advancing when this migration ran
+    // and re-issues numbers that are already on documents.
+    this.addSql(`
+      do $$
+      declare
+        registry record;
+        sequence_name text;
+        last_issued bigint;
+      begin
+        for registry in select id from sales_document_sequences loop
+          sequence_name := 'sales_docseq_' || replace(registry.id::text, '-', '');
+          execute format('select pg_sequence_last_value(%L::regclass)', sequence_name) into last_issued;
+          if last_issued is not null then
+            update sales_document_sequences
+               set current_value = greatest(coalesce(current_value, 0), last_issued),
+                   updated_at = now()
+             where id = registry.id;
+          end if;
+          execute format('drop sequence if exists %I', sequence_name);
+        end loop;
+      end $$;
+    `)
+  }
+}

package/src/modules/sales/services/salesDocumentNumberGenerator.ts

@@ -1,6 +1,6 @@
 import { randomBytes, randomUUID } from 'crypto'
 import type { EntityManager } from '@mikro-orm/postgresql'
-import { SalesDocumentSequence, SalesSettings } from '../data/entities'
+import { SalesSettings } from '../data/entities'
 import {
   DEFAULT_ORDER_NUMBER_FORMAT,
   DEFAULT_QUOTE_NUMBER_FORMAT,
@@ -57,6 +57,56 @@ const generateRandomDigits = (size = 4) => {
   return digits.join('')
 }
 
+// Each (organization, tenant, kind) scope is backed by its own Postgres sequence, named
+// after the `sales_document_sequences` registry row that owns it (#5604). Deriving the name
+// from the row's primary key keeps the mapping recomputable from the table alone — no extra
+// column, and `\ds sales_docseq_*` in psql lines up with the registry.
+const SEQUENCE_NAME_PREFIX = 'sales_docseq_'
+const SEQUENCE_NAME_PATTERN = /^sales_docseq_[0-9a-f]{32}$/
+// Recomputes the name in SQL so a claim is a single round trip: look the registry row up by
+// its unique scope index and call `nextval` on the sequence that row names.
+const SEQUENCE_REGCLASS_SQL = `('${SEQUENCE_NAME_PREFIX}' || replace(id::text, '-', ''))::regclass`
+const SEQUENCE_SCOPE_PREDICATE = 'organization_id = ? and tenant_id = ? and document_kind = ?'
+
+export function documentSequenceName(registryId: string): string {
+  const name = `${SEQUENCE_NAME_PREFIX}${String(registryId).replace(/-/g, '').toLowerCase()}`
+  if (!SEQUENCE_NAME_PATTERN.test(name)) {
+    throw new Error('[internal] Document-sequence registry id is not a UUID')
+  }
+  return name
+}
+
+function isMissingRelationError(error: unknown): boolean {
+  if ((error as { code?: unknown } | null)?.code === '42P01') return true
+  const message = error instanceof Error ? error.message : ''
+  return /does not exist/i.test(message)
+}
+
+function isDuplicateRelationError(error: unknown): boolean {
+  const code = (error as { code?: unknown } | null)?.code
+  if (code === '42P07' || code === '23505') return true
+  const message = error instanceof Error ? error.message : ''
+  return /already exists/i.test(message)
+}
+
+/**
+ * Creates the Postgres sequence backing a `sales_document_sequences` registry row, if it is
+ * not there yet. Safe to call concurrently: `if not exists` still races on `pg_class`, so a
+ * duplicate error means another caller won and is treated as success.
+ */
+export async function createDocumentSequence(em: EntityManager, registryId: string): Promise<void> {
+  const name = documentSequenceName(registryId)
+  try {
+    await em.getConnection().execute(
+      `create sequence if not exists "${name}" as bigint minvalue ${DEFAULT_SEQUENCE_START} start with ${DEFAULT_SEQUENCE_START} no cycle`,
+      [],
+      'run'
+    )
+  } catch (error) {
+    if (!isDuplicateRelationError(error)) throw error
+  }
+}
+
 export class SalesDocumentNumberGenerator {
   constructor(private readonly em: EntityManager) {}
 
@@ -81,16 +131,41 @@ export class SalesDocumentNumberGenerator {
   }
 
   async setNextSequence(kind: SalesDocumentNumberKind, scope: Scope, nextValue: number): Promise<void> {
-    const next = Math.min(Math.max(Math.floor(nextValue), DEFAULT_SEQUENCE_START), MAX_SEQUENCE)
-    const baseValue = next - 1
+    const next = Math.floor(nextValue)
+    // Refuse an out-of-range target rather than clamping to it, for the same reason
+    // `tryClaimSequence` refuses to hand out a clamped value: parking the series on the ceiling
+    // makes every later claim collide there, so silently accepting the value is the same "two
+    // documents share a number" hazard one step earlier. `salesSettingsUpsertSchema` already
+    // rejects the range at the API boundary, so this only fires for a direct service caller.
+    if (!Number.isFinite(next) || next < DEFAULT_SEQUENCE_START || next > MAX_SEQUENCE) {
+      throw new Error('[internal] Sales document sequence target is outside the supported range')
+    }
+    await this.ensureSequence(kind, scope)
+    // Park the sequence on `next - 1` as an already-issued value, so the next `nextval`
+    // returns exactly `next`. The `setval(next, false)` form would do that too, but it leaves
+    // `is_called = false`, and that is precisely the state `pg_sequence_last_value` reports as
+    // NULL — `peekNextSequence` would then read the series back as the start value and the
+    // settings form would write that rewind back on its next save.
+    // The start value has no predecessor to park on and `minvalue` forbids one; it is also the
+    // one value the untouched "never called" state already claims and reports correctly.
+    const isCalled = next > DEFAULT_SEQUENCE_START
+    const armedAt = isCalled ? next - 1 : DEFAULT_SEQUENCE_START
     await this.em.getConnection().execute(
       `
-        insert into sales_document_sequences (id, organization_id, tenant_id, document_kind, current_value, created_at, updated_at)
-        values (gen_random_uuid(), ?, ?, ?, ?, now(), now())
-        on conflict (organization_id, tenant_id, document_kind)
-        do update set current_value = ?, updated_at = now()
+        select setval(${SEQUENCE_REGCLASS_SQL}, ?, ?)
+          from sales_document_sequences
+         where ${SEQUENCE_SCOPE_PREDICATE}
       `,
-      [scope.organizationId, scope.tenantId, kind, baseValue, baseValue]
+      [armedAt, isCalled, scope.organizationId, scope.tenantId, kind]
+    )
+    await this.em.getConnection().execute(
+      `
+        update sales_document_sequences
+           set current_value = ?, updated_at = now()
+         where ${SEQUENCE_SCOPE_PREDICATE}
+      `,
+      [next - 1, scope.organizationId, scope.tenantId, kind],
+      'run'
     )
   }
 
@@ -118,31 +193,93 @@ export class SalesDocumentNumberGenerator {
   }
 
   private async peekNextSequence(kind: SalesDocumentNumberKind, scope: Scope): Promise<number> {
-    const record = await this.em.findOne(SalesDocumentSequence, {
-      tenantId: scope.tenantId,
-      organizationId: scope.organizationId,
-      documentKind: kind,
-    })
-    if (record && typeof record.currentValue === 'number') {
-      return Math.min(record.currentValue + 1, MAX_SEQUENCE)
+    let rows: { last_value: string | number | null }[] | undefined
+    try {
+      // `pg_sequence_last_value` reports the sequence's state without consuming a value, and
+      // returns NULL for a sequence that has never been called — which is the only state
+      // `setNextSequence` leaves behind for the start value, and the value it claims next.
+      rows = await this.em.getConnection().execute<{ last_value: string | number | null }[]>(
+        `
+          select pg_sequence_last_value(${SEQUENCE_REGCLASS_SQL}) as last_value
+            from sales_document_sequences
+           where ${SEQUENCE_SCOPE_PREDICATE}
+        `,
+        [scope.organizationId, scope.tenantId, kind]
+      )
+    } catch (error) {
+      if (isMissingRelationError(error)) return DEFAULT_SEQUENCE_START
+      throw error
     }
-    return DEFAULT_SEQUENCE_START
+    const lastValue = rows?.[0]?.last_value
+    if (lastValue == null) return DEFAULT_SEQUENCE_START
+    const value = Number(lastValue)
+    if (!Number.isFinite(value)) return DEFAULT_SEQUENCE_START
+    return Math.min(Math.max(value + 1, DEFAULT_SEQUENCE_START), MAX_SEQUENCE)
   }
 
+  // `nextval` is the whole point of the sequence: it is atomic, never takes a row lock, and
+  // produces no dead tuples, so concurrent claims for the same scope no longer serialize on a
+  // single `sales_document_sequences` row the way the previous `UPDATE … current_value + 1`
+  // did (#5604). The registry row still exists — it names the sequence and records the scope —
+  // but the hot path only reads it.
   private async claimSequence(kind: SalesDocumentNumberKind, scope: Scope): Promise<number> {
-    const rows = await this.em.getConnection().execute<{ current_value: string }[]>(
+    const claimed = await this.tryClaimSequence(kind, scope)
+    if (claimed !== null) return claimed
+    // First claim for this scope (or a tenant created before the sequences existed): create
+    // the registry row and its sequence, then claim once more.
+    await this.ensureSequence(kind, scope)
+    const retried = await this.tryClaimSequence(kind, scope)
+    if (retried === null) {
+      throw new Error('[internal] Sales document sequence is missing immediately after being created')
+    }
+    return retried
+  }
+
+  private async tryClaimSequence(kind: SalesDocumentNumberKind, scope: Scope): Promise<number | null> {
+    let rows: { claimed: string | number | null }[] | undefined
+    try {
+      rows = await this.em.getConnection().execute<{ claimed: string | number | null }[]>(
+        `
+          select nextval(${SEQUENCE_REGCLASS_SQL}) as claimed
+            from sales_document_sequences
+           where ${SEQUENCE_SCOPE_PREDICATE}
+        `,
+        [scope.organizationId, scope.tenantId, kind]
+      )
+    } catch (error) {
+      if (isMissingRelationError(error)) return null
+      throw error
+    }
+    const claimed = rows?.[0]?.claimed
+    if (claimed == null) return null
+    const value = Number(claimed)
+    if (!Number.isFinite(value) || value < DEFAULT_SEQUENCE_START) {
+      throw new Error('[internal] Sales document sequence returned a value below its start')
+    }
+    if (value > MAX_SEQUENCE) {
+      // Never hand out a clamped value: two documents sharing a number is a worse failure
+      // than refusing to issue one, and the caller's transaction can still roll back cleanly.
+      throw new Error('[internal] Sales document sequence is exhausted')
+    }
+    return value
+  }
+
+  private async ensureSequence(kind: SalesDocumentNumberKind, scope: Scope): Promise<void> {
+    const rows = await this.em.getConnection().execute<{ id: string }[]>(
       `
         insert into sales_document_sequences (id, organization_id, tenant_id, document_kind, current_value, created_at, updated_at)
-        values (gen_random_uuid(), ?, ?, ?, ?, now(), now())
+        values (gen_random_uuid(), ?, ?, ?, 0, now(), now())
         on conflict (organization_id, tenant_id, document_kind)
-        do update set current_value = sales_document_sequences.current_value + 1, updated_at = now()
-        returning current_value
+        do update set updated_at = now()
+        returning id
       `,
-      [scope.organizationId, scope.tenantId, kind, DEFAULT_SEQUENCE_START]
+      [scope.organizationId, scope.tenantId, kind]
     )
-    const value = Number(rows?.[0]?.current_value ?? DEFAULT_SEQUENCE_START)
-    if (!Number.isFinite(value) || value < DEFAULT_SEQUENCE_START) return DEFAULT_SEQUENCE_START
-    return Math.min(value, MAX_SEQUENCE)
+    const registryId = rows?.[0]?.id
+    if (!registryId) {
+      throw new Error('[internal] Could not resolve a sales document sequence registry row')
+    }
+    await createDocumentSequence(this.em, registryId)
   }
 
   private formatNumber(

package/src/modules/sales/setup.ts

@@ -6,6 +6,7 @@ import { seedSalesStatusDictionaries, seedSalesAdjustmentKinds } from './lib/dic
 import { seedSalesChannelsToggle } from './lib/salesChannelsToggleSeed'
 import { ensureExampleShippingMethods, ensureExamplePaymentMethods } from './seed/examples-data'
 import { seedSalesExamples } from './seed/examples'
+import { createDocumentSequence } from './services/salesDocumentNumberGenerator'
 
 type SeedScope = { tenantId: string; organizationId: string }
 
@@ -87,14 +88,15 @@ export const setup: ModuleSetupConfig = {
       )
     }
 
+    const sequenceRows: SalesDocumentSequence[] = []
     for (const kind of ['order', 'quote', 'return', 'invoice', 'credit_memo'] as const) {
       const seq = await em.findOne(SalesDocumentSequence, {
         tenantId,
         organizationId,
         documentKind: kind,
       })
-      if (!seq) {
-        em.persist(
+      sequenceRows.push(
+        seq ??
           em.create(SalesDocumentSequence, {
             tenantId,
             organizationId,
@@ -103,11 +105,21 @@ export const setup: ModuleSetupConfig = {
             createdAt: new Date(),
             updatedAt: new Date(),
           })
-        )
-      }
+      )
+      if (!seq) em.persist(sequenceRows[sequenceRows.length - 1]!)
     }
 
     await em.flush()
+
+    // Each registry row is backed by its own Postgres sequence (#5604); create them now so the
+    // first document of a fresh tenant does not have to fall back to lazy creation. The ids come
+    // from the rows just flushed rather than from a re-read: `createDocumentSequence` issues DDL
+    // over `em.getConnection()`, which runs outside the EntityManager's transaction context, so
+    // a read on that connection would not see rows this hook wrote inside a transaction and the
+    // loop would silently create nothing.
+    for (const row of sequenceRows) {
+      await createDocumentSequence(em, row.id)
+    }
   },
 
   async seedDefaults({ em, tenantId, organizationId }) {