@open-mercato/shared 0.6.7-develop.6706.1.b3a4c759bb → 0.6.7-develop.6726.1.983ae8a07e

package/src/lib/search/config.ts

@@ -1,5 +1,6 @@
 import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
 import { parseNumberWithDefault } from '@open-mercato/shared/lib/number'
+import { parseCommaSeparatedList } from '@open-mercato/shared/lib/string'
 
 export type SearchConfig = {
   enabled: boolean
@@ -8,12 +9,15 @@ export type SearchConfig = {
   hashAlgorithm: 'sha256' | 'sha1' | 'md5'
   storeRawTokens: boolean
   blocklistedFields: string[]
+  entityBlocklistedFields?: Record<string, string[]>
 }
 
 export const DEFAULT_SEARCH_MIN_TOKEN_LENGTH = 3
 
 const DEFAULT_BLOCKLIST = ['password', 'token', 'secret', 'hash']
 
+const ENTITY_BLOCKLIST_SEPARATOR = '@'
+
 function parseBoolean(raw: string | undefined, fallback: boolean): boolean {
   return parseBooleanWithDefault(raw, fallback)
 }
@@ -29,24 +33,90 @@ function parseHashAlgorithm(raw: string | undefined): 'sha256' | 'sha1' | 'md5'
   return 'sha256'
 }
 
+/**
+ * Parses `OM_SEARCH_FIELD_BLOCKLIST` into a global list plus per-entity-type lists.
+ *
+ * Why: a deployment often needs to keep one large free-text column out of the token
+ * index (e-mail bodies on `customers:customer_interaction`) while still indexing the
+ * same-named column elsewhere. A flat global list cannot express that.
+ *
+ * How to apply: entries are comma-separated; an entry may carry an optional
+ * `entityType@` prefix — `body` blocks the field everywhere, while
+ * `customers:customer_interaction@body` blocks it only for that entity type. Entries
+ * whose field part is empty are ignored so malformed env input cannot break indexing.
+ */
+function parseFieldBlocklist(raw: string | undefined): {
+  global: string[]
+  byEntity: Record<string, string[]>
+} {
+  const global: string[] = []
+  const byEntity = new Map<string, string[]>()
+
+  for (const rawEntry of parseCommaSeparatedList(raw)) {
+    const entry = rawEntry.toLowerCase()
+    const separatorIndex = entry.indexOf(ENTITY_BLOCKLIST_SEPARATOR)
+    const entityType = separatorIndex >= 0 ? entry.slice(0, separatorIndex).trim() : ''
+    const field = separatorIndex >= 0 ? entry.slice(separatorIndex + 1).trim() : entry
+    if (!field.length) continue
+
+    if (!entityType.length) {
+      if (!global.includes(field)) global.push(field)
+      continue
+    }
+
+    const scoped = byEntity.get(entityType) ?? []
+    if (!scoped.includes(field)) scoped.push(field)
+    byEntity.set(entityType, scoped)
+  }
+
+  for (const fallback of DEFAULT_BLOCKLIST) {
+    if (!global.includes(fallback)) global.push(fallback)
+  }
+
+  const scopedBlocklist = Object.create(null) as Record<string, string[]>
+  for (const [entityType, fields] of byEntity) scopedBlocklist[entityType] = fields
+
+  return { global, byEntity: scopedBlocklist }
+}
+
 export function resolveSearchConfig(): SearchConfig {
+  const blocklist = parseFieldBlocklist(process.env.OM_SEARCH_FIELD_BLOCKLIST)
   return {
     enabled: parseBoolean(process.env.OM_SEARCH_ENABLED, true),
     minTokenLength: resolveSearchMinTokenLength(),
     enablePartials: parseBoolean(process.env.OM_SEARCH_ENABLE_PARTIAL, true),
     hashAlgorithm: parseHashAlgorithm(process.env.OM_SEARCH_HASH_ALGO),
     storeRawTokens: parseBoolean(process.env.OM_SEARCH_STORE_RAW_TOKENS, false),
-    blocklistedFields: (process.env.OM_SEARCH_FIELD_BLOCKLIST ?? '')
-      .split(',')
-      .map((entry) => entry.trim())
-      .filter((entry) => entry.length > 0)
-      .filter((value, index, arr) => arr.indexOf(value) === index)
-      .map((entry) => entry.toLowerCase())
-      .concat(DEFAULT_BLOCKLIST)
-      .filter((value, index, arr) => arr.indexOf(value) === index),
+    blocklistedFields: blocklist.global,
+    entityBlocklistedFields: blocklist.byEntity,
   }
 }
 
+/**
+ * Single matcher for "should this field be kept out of the search index?".
+ *
+ * Why: the per-field token path and the `search_text` aggregate previously each
+ * decided this on their own, and the aggregate simply never consulted the config —
+ * so a blocklisted column's text came back into the index under the aggregate's
+ * field name (#4624). Both paths now share this function so they cannot drift.
+ *
+ * How to apply: pass the document's field name and the entity type being indexed;
+ * `entityType` may be omitted when unknown, in which case only global entries apply.
+ * Matching keeps the historical substring semantics (`fieldName.includes(pattern)`).
+ */
+export function isSearchFieldBlocklisted(
+  field: string,
+  entityType: string | null | undefined,
+  config: SearchConfig,
+): boolean {
+  const lower = field.toLowerCase()
+  if (config.blocklistedFields.some((blocked) => lower.includes(blocked))) return true
+  if (!entityType) return false
+  const scoped = config.entityBlocklistedFields?.[entityType.trim().toLowerCase()]
+  if (!Array.isArray(scoped) || !scoped.length) return false
+  return scoped.some((blocked) => lower.includes(blocked))
+}
+
 /**
  * Browser-safe accessor for the minimum search token length.
  *

package/src/lib/search/tokenLookup.ts

@@ -0,0 +1,133 @@
+import { type Kysely, sql } from 'kysely'
+import { resolveSearchConfig, type SearchConfig } from './config'
+import { tokenizeText } from './tokenize'
+
+export type SearchTokenDatabase = {
+  search_tokens: {
+    entity_id: string
+    entity_type: string
+    field: string
+    token_hash: string
+    tenant_id: string | null
+    organization_id: string | null
+  }
+}
+
+/**
+ * Tenant/organization scoping for a `search_tokens` lookup.
+ *
+ * `undefined` and `null` are NOT interchangeable:
+ * - `undefined` omits the predicate entirely (the caller owns visibility).
+ * - `null` emits a null-safe predicate that matches only globally scoped rows.
+ */
+export type SearchTokenScope = {
+  tenantId?: string | null
+  organizationId?: string | null
+  organizationIds?: readonly string[] | null
+}
+
+/**
+ * Why a lookup could not produce an id set. Callers MUST NOT read these as
+ * "nothing matched" — the token index was never consulted, so the caller's own
+ * predicate (usually an `ilike`) is still the authoritative one.
+ */
+export type SearchTokenLookupSkipReason = 'empty-query' | 'search-disabled' | 'no-tokens'
+
+export type SearchTokenLookupResult =
+  | { matched: true; ids: string[] }
+  | { matched: false; reason: SearchTokenLookupSkipReason }
+
+export type FindEntityIdsBySearchTokensInput = {
+  db: Kysely<SearchTokenDatabase>
+  entityType: string
+  query: string
+  fields?: readonly string[] | null
+  scope?: SearchTokenScope
+  config?: SearchConfig
+}
+
+/**
+ * Resolve the record ids whose indexed `search_tokens` cover every token in
+ * `query`.
+ *
+ * This is the encryption-safe replacement for `ilike` filtering on columns an
+ * encryption map covers: the stored column holds ciphertext, so
+ * `ilike '%term%'` silently matches nothing, while the token index stores
+ * hashes of the plaintext and keeps matching. See issue #2990.
+ *
+ * Matching requires ALL query tokens to be present on the record. The token
+ * search strategy in `@open-mercato/search` uses a looser match ratio; list
+ * endpoints want the stricter behavior so a two-word query narrows rather than
+ * widens the result set.
+ */
+export async function findEntityIdsBySearchTokens({
+  db,
+  entityType,
+  query,
+  fields,
+  scope,
+  config,
+}: FindEntityIdsBySearchTokensInput): Promise<SearchTokenLookupResult> {
+  const trimmed = query.trim()
+  if (!trimmed) return { matched: false, reason: 'empty-query' }
+
+  const searchConfig = config ?? resolveSearchConfig()
+  if (!searchConfig.enabled) return { matched: false, reason: 'search-disabled' }
+
+  const { hashes } = tokenizeText(trimmed, searchConfig)
+  if (!hashes.length) return { matched: false, reason: 'no-tokens' }
+
+  let builder = db
+    .selectFrom('search_tokens')
+    .select('entity_id')
+    .where('entity_type', '=', entityType)
+    .where('token_hash', 'in', hashes)
+
+  const scopedFields = (fields ?? []).filter((field) => typeof field === 'string' && field.length > 0)
+  if (scopedFields.length === 1) {
+    builder = builder.where('field', '=', scopedFields[0])
+  } else if (scopedFields.length > 1) {
+    builder = builder.where('field', 'in', Array.from(scopedFields))
+  }
+
+  if (scope?.tenantId !== undefined) {
+    builder = builder.where(sql<boolean>`tenant_id is not distinct from ${scope.tenantId}`)
+  }
+
+  if (scope?.organizationId !== undefined) {
+    builder = scope.organizationId === null
+      ? builder.where(sql<boolean>`organization_id is not distinct from ${null}`)
+      : builder.where('organization_id', '=', scope.organizationId)
+  } else if (scope?.organizationIds?.length) {
+    builder = builder.where('organization_id', 'in', Array.from(scope.organizationIds))
+  }
+
+  const rows = (await builder
+    .groupBy('entity_id')
+    .having(sql<boolean>`count(distinct token_hash) >= ${hashes.length}`)
+    .execute()) as Array<{ entity_id?: unknown }>
+
+  const ids = rows
+    .map((row) => (typeof row.entity_id === 'string' ? row.entity_id : null))
+    .filter((id): id is string => typeof id === 'string' && id.length > 0)
+
+  return { matched: true, ids }
+}
+
+/**
+ * Legacy-shaped adapter for call sites that predate
+ * {@link SearchTokenLookupResult}: `null` for a blank query, `[]` for every
+ * other non-answer, otherwise the matched ids.
+ *
+ * Prefer {@link findEntityIdsBySearchTokens} in new code — the discriminated
+ * result distinguishes "the index says nothing matched" from "the index was
+ * never consulted", and that distinction is exactly what a `null`/`[]` pair
+ * loses.
+ */
+export async function findEntityIdsBySearchTokensCompat(
+  input: FindEntityIdsBySearchTokensInput,
+): Promise<string[] | null> {
+  const result = await findEntityIdsBySearchTokens(input)
+  if (result.matched) return result.ids
+  return result.reason === 'empty-query' ? null : []
+}

package/src/modules/__tests__/nav-group-order-override.test.ts

@@ -0,0 +1,183 @@
+/** @jest-environment node */
+
+// `defaultGroupOrder` in `auth/lib/backendChrome.tsx` ranks any group it lists ahead of any group it
+// does not, regardless of an app's own page `priority`/`order` — so a downstream app could not place its
+// own primary module above the shipped groups by any documented means. `overrides.nav.groupOrder` wires
+// that as a real override domain, which `BACKWARD_COMPATIBILITY.md` §2 explicitly reserves for additive
+// wiring.
+
+const mockLoggerWarn = jest.fn()
+
+jest.mock('../../lib/logger', () => ({
+  createLogger: () => {
+    const child = { warn: (...args: unknown[]) => mockLoggerWarn(...args), error: jest.fn(), info: jest.fn(), debug: jest.fn() }
+    return { child: () => child, warn: child.warn, error: child.error, info: child.info, debug: child.debug }
+  },
+}))
+
+import {
+  applyModuleOverridesFromEnabledModules,
+  applyNavGroupOrderOverrides,
+  getNavGroupOrderOverride,
+  resetModuleContractOverridesForTests,
+  resetModuleOverrideAppliersForTests,
+} from '../overrides'
+
+function reset() {
+  resetModuleOverrideAppliersForTests()
+  resetModuleContractOverridesForTests()
+  mockLoggerWarn.mockClear()
+}
+
+beforeEach(reset)
+afterEach(reset)
+
+const collisionWarnings = () =>
+  mockLoggerWarn.mock.calls.filter((call) => String(call[0]).includes('nav.groupOrder declared by more than one'))
+
+describe('nav.groupOrder override domain', () => {
+  it('is unset when no module declares it', () => {
+    applyModuleOverridesFromEnabledModules([{ id: 'catalog' }, { id: 'sales', overrides: {} }])
+
+    expect(getNavGroupOrderOverride()).toBeNull()
+  })
+
+  it('captures the ids a module declares, in order — proving the domain is wired', () => {
+    applyModuleOverridesFromEnabledModules([
+      { id: 'app', overrides: { nav: { groupOrder: ['app.nav.group', 'catalog.nav.group'] } } },
+    ])
+
+    expect(getNavGroupOrderOverride()).toEqual(['app.nav.group', 'catalog.nav.group'])
+    // An unwired domain would be dropped with a "not yet wired" warning instead of being captured.
+    expect(mockLoggerWarn.mock.calls.filter((call) => String(call[0]).includes('not yet wired'))).toEqual([])
+  })
+
+  it('ignores an empty list, leaving the shipped ordering in charge', () => {
+    applyModuleOverridesFromEnabledModules([{ id: 'app', overrides: { nav: { groupOrder: [] } } }])
+
+    expect(getNavGroupOrderOverride()).toBeNull()
+  })
+
+  it('drops blank entries and de-duplicates while preserving first position', () => {
+    applyModuleOverridesFromEnabledModules([
+      {
+        id: 'app',
+        overrides: { nav: { groupOrder: ['  app.nav.group  ', '', '   ', 'app.nav.group', 'catalog.nav.group'] } },
+      },
+    ])
+
+    expect(getNavGroupOrderOverride()).toEqual(['app.nav.group', 'catalog.nav.group'])
+  })
+
+  it('ignores a non-array value rather than throwing', () => {
+    applyModuleOverridesFromEnabledModules([
+      { id: 'app', overrides: { nav: { groupOrder: 'app.nav.group' as never } } },
+    ])
+
+    expect(getNavGroupOrderOverride()).toBeNull()
+  })
+
+  it('lets the later module win when two declare an order, and says so', () => {
+    applyModuleOverridesFromEnabledModules([
+      { id: 'first', overrides: { nav: { groupOrder: ['first.nav.group'] } } },
+      { id: 'second', overrides: { nav: { groupOrder: ['second.nav.group'] } } },
+    ])
+
+    expect(getNavGroupOrderOverride()).toEqual(['second.nav.group'])
+    expect(collisionWarnings()).toHaveLength(1)
+  })
+
+  it('does not warn when the same module declares it twice', () => {
+    applyModuleOverridesFromEnabledModules([
+      { id: 'app', overrides: { nav: { groupOrder: ['a.nav.group'] } } },
+      { id: 'app', overrides: { nav: { groupOrder: ['b.nav.group'] } } },
+    ])
+
+    expect(getNavGroupOrderOverride()).toEqual(['b.nav.group'])
+    expect(collisionWarnings()).toEqual([])
+  })
+
+  it('is cleared by the store reset hook so suites cannot leak into each other', () => {
+    applyModuleOverridesFromEnabledModules([
+      { id: 'app', overrides: { nav: { groupOrder: ['app.nav.group'] } } },
+    ])
+    expect(getNavGroupOrderOverride()).not.toBeNull()
+
+    resetModuleContractOverridesForTests()
+
+    expect(getNavGroupOrderOverride()).toBeNull()
+  })
+})
+
+describe('nav.groupOrder programmatic tier', () => {
+  it('takes precedence over the modules.ts declaration', () => {
+    applyModuleOverridesFromEnabledModules([
+      { id: 'app', overrides: { nav: { groupOrder: ['from-modules.nav.group'] } } },
+    ])
+    applyNavGroupOrderOverrides(['from-code.nav.group'])
+
+    expect(getNavGroupOrderOverride()).toEqual(['from-code.nav.group'])
+  })
+
+  it('falls back to the modules.ts declaration when cleared with null', () => {
+    applyModuleOverridesFromEnabledModules([
+      { id: 'app', overrides: { nav: { groupOrder: ['from-modules.nav.group'] } } },
+    ])
+    applyNavGroupOrderOverrides(['from-code.nav.group'])
+    applyNavGroupOrderOverrides(null)
+
+    expect(getNavGroupOrderOverride()).toEqual(['from-modules.nav.group'])
+  })
+
+  it('applies the same normalisation as the modules.ts tier', () => {
+    applyNavGroupOrderOverrides(['  a.nav.group  ', '', 'a.nav.group', 'b.nav.group'])
+
+    expect(getNavGroupOrderOverride()).toEqual(['a.nav.group', 'b.nav.group'])
+  })
+
+  it('treats an all-blank list as no override', () => {
+    applyNavGroupOrderOverrides(['   ', ''])
+
+    expect(getNavGroupOrderOverride()).toBeNull()
+  })
+
+  it('works before any module override has been dispatched', () => {
+    applyNavGroupOrderOverrides(['standalone.nav.group'])
+
+    expect(getNavGroupOrderOverride()).toEqual(['standalone.nav.group'])
+  })
+})
+
+describe('nav.groupOrder survives module duplication', () => {
+  // Regression for `.ai/lessons.md`, "Global registries in publishable packages must use
+  // `globalThis`". This domain's writer (app bootstrap) and reader (`@open-mercato/core`'s backend
+  // chrome) sit in different packages, and standalone builds can evaluate `@open-mercato/shared`
+  // through more than one module instance. `jest.isolateModules` reproduces that: a second, freshly
+  // loaded copy of the module must still observe what the first copy stored.
+  it('a separately loaded module instance sees the value written by bootstrap', () => {
+    applyModuleOverridesFromEnabledModules([
+      { id: 'app', overrides: { nav: { groupOrder: ['bootstrap.nav.group'] } } },
+    ])
+
+    let observedFromSecondInstance: readonly string[] | null | undefined
+    jest.isolateModules(() => {
+      const freshModule = require('../overrides') as typeof import('../overrides')
+      observedFromSecondInstance = freshModule.getNavGroupOrderOverride()
+    })
+
+    // A module-local variable would leave this second instance blind to the bootstrap value.
+    expect(observedFromSecondInstance).toEqual(['bootstrap.nav.group'])
+  })
+
+  it('a programmatic override is visible to a separately loaded instance too', () => {
+    applyNavGroupOrderOverrides(['programmatic.nav.group'])
+
+    let observed: readonly string[] | null | undefined
+    jest.isolateModules(() => {
+      const freshModule = require('../overrides') as typeof import('../overrides')
+      observed = freshModule.getNavGroupOrderOverride()
+    })
+
+    expect(observed).toEqual(['programmatic.nav.group'])
+  })
+})

package/src/modules/navigation/backendChrome.ts

@@ -47,6 +47,19 @@ export type BackendChromeBrand = {
   } | null
 }
 
+/**
+ * The organization the current request is scoped to, resolved server-side.
+ *
+ * Distinct from `brand`, which is a *branding* channel and only populates when the organization has a
+ * logo configured. This is always present when a single organization is in scope, so UI can label
+ * "you are viewing: <name>" without a second round trip. `null` under an all-organizations selection,
+ * when no organization is in scope, or when the lookup fails.
+ */
+export type BackendChromeCurrentOrganization = {
+  id: string
+  name: string
+}
+
 export type BackendChromePayload = {
   groups: BackendChromeNavGroup[]
   settingsSections: BackendChromeSectionGroup[]
@@ -56,4 +69,5 @@ export type BackendChromePayload = {
   grantedFeatures: string[]
   roles: string[]
   brand?: BackendChromeBrand | null
+  currentOrganization?: BackendChromeCurrentOrganization | null
 }

package/src/modules/overrides.ts

@@ -116,6 +116,21 @@ export interface EncryptionOverridesShape {
   maps?: EncryptionMapOverridesMap | LooseOverrideMap
 }
 
+/**
+ * Backend navigation ordering.
+ *
+ * `groupOrder` **prepends** sidebar nav group ids: the ids listed here rank ahead of every other
+ * group, in the order given, and any group not named keeps the ordering it has today. Prepending
+ * rather than replacing means an app that only cares about its own group lists that one id, instead of
+ * having to enumerate every shipped group and accidentally demoting the ones it forgot.
+ *
+ * This is a *default*, applied beneath both role and user sidebar preferences — an operator's own
+ * arrangement still wins.
+ */
+export interface NavOverridesShape {
+  groupOrder?: string[]
+}
+
 /**
  * Umbrella shape for `entry.overrides`. Every key is optional; a
  * downstream app sets only the domains it cares about.
@@ -136,6 +151,7 @@ export interface ModuleOverrides {
   acl?: AclOverridesShape
   di?: DiOverridesMap | LooseOverrideMap
   encryption?: EncryptionOverridesShape
+  nav?: NavOverridesShape
 }
 
 /**
@@ -175,6 +191,7 @@ export type ModuleOverrideDomain =
   | 'acl'
   | 'di'
   | 'encryption'
+  | 'nav'
 
 export interface ModuleOverrideEntry<TShape> {
   moduleId: string
@@ -227,6 +244,7 @@ const DOMAIN_KEYS: ModuleOverrideDomain[] = [
   'acl',
   'di',
   'encryption',
+  'nav',
 ]
 
 const TRACKING_ISSUE_HINT =
@@ -441,6 +459,71 @@ const encryptionMapOverrideStore: OverrideStore<ModuleEncryptionMap> = { modules
 const diOverrideStore: OverrideStore<Exclude<DiBindingOverride, null>> = { modules: {}, programmatic: {} }
 const setupOverridesByModule: Record<string, SetupOverridesShape> = {}
 
+/**
+ * Sidebar nav ordering state.
+ *
+ * Persisted on `globalThis` rather than in a module-local variable. This is the one override domain
+ * whose consumer lives in a *different package* (`@open-mercato/core`'s backend chrome reads what the
+ * app's bootstrap wrote), and standalone builds can evaluate `@open-mercato/shared` through more than
+ * one server chunk — bootstrap would store the value in one instance while the reader saw `null` from
+ * another. See `.ai/lessons.md`, "Global registries in publishable packages must use `globalThis`".
+ *
+ * Two tiers, matching every other override domain and the documented resolution order: programmatic
+ * calls win over `modules.ts` inline declarations.
+ */
+const GLOBAL_NAV_OVERRIDE_STATE_KEY = '__openMercatoNavOverrideState__'
+
+type NavOverrideState = {
+  /** From `modules.ts` inline `overrides.nav`, with the module entry that supplied it. */
+  modules: { moduleId: string; groupOrder: string[] } | null
+  /** From `applyNavGroupOrderOverrides`. Takes precedence over `modules`. */
+  programmatic: string[] | null
+}
+
+function getNavOverrideState(): NavOverrideState {
+  const existing = (globalThis as Record<string, unknown>)[GLOBAL_NAV_OVERRIDE_STATE_KEY]
+  if (existing && typeof existing === 'object') {
+    const typed = existing as NavOverrideState
+    if ('modules' in typed && 'programmatic' in typed) return typed
+  }
+  const initial: NavOverrideState = { modules: null, programmatic: null }
+  ;(globalThis as Record<string, unknown>)[GLOBAL_NAV_OVERRIDE_STATE_KEY] = initial
+  return initial
+}
+
+/** Drops blank/duplicate ids and returns `null` when nothing usable remains. */
+function normalizeNavGroupOrder(value: unknown): string[] | null {
+  if (!Array.isArray(value)) return null
+  const ids = Array.from(
+    new Set(
+      value
+        .filter((id): id is string => typeof id === 'string' && id.trim().length > 0)
+        .map((id) => id.trim()),
+    ),
+  )
+  return ids.length > 0 ? ids : null
+}
+
+/**
+ * Programmatic nav ordering, for env-driven boot decisions and tests. Takes precedence over
+ * `modules.ts` inline `overrides.nav`, consistent with the other domains' programmatic tier. Pass
+ * `null` to clear it and fall back to the inline declaration.
+ */
+export function applyNavGroupOrderOverrides(groupOrder: string[] | null): void {
+  getNavOverrideState().programmatic = groupOrder === null ? null : normalizeNavGroupOrder(groupOrder)
+}
+
+/**
+ * Nav group ids an app wants ranked ahead of the built-in order, or `null` when none is configured.
+ *
+ * Consumers MUST treat `null` as "use the shipped ordering unchanged" — this is a default, applied
+ * beneath role and user sidebar preferences.
+ */
+export function getNavGroupOrderOverride(): readonly string[] | null {
+  const state = getNavOverrideState()
+  return state.programmatic ?? state.modules?.groupOrder ?? null
+}
+
 function normalizeIdOverrideKey(key: string, label: string): string | null {
   if (typeof key !== 'string') return null
   const trimmed = key.trim()
@@ -721,6 +804,9 @@ export function resetModuleContractOverridesForTests(): void {
   clearStore(encryptionMapOverrideStore)
   clearStore(diOverrideStore)
   for (const key of Object.keys(setupOverridesByModule)) delete setupOverridesByModule[key]
+  const navState = getNavOverrideState()
+  navState.modules = null
+  navState.programmatic = null
 }
 
 /**
@@ -1500,7 +1586,24 @@ function encryptionOverridesApplier(entries: ReadonlyArray<ModuleOverrideEntry<E
   }
 }
 
+function navOverridesApplier(entries: ReadonlyArray<ModuleOverrideEntry<NavOverridesShape>>): void {
+  const state = getNavOverrideState()
+  for (const entry of entries) {
+    const groupOrder = normalizeNavGroupOrder(entry.overrides?.groupOrder)
+    if (!groupOrder) continue
+    if (state.modules && state.modules.moduleId !== entry.moduleId) {
+      logger.warn('nav.groupOrder declared by more than one module — the later one wins', {
+        previousModuleId: state.modules.moduleId,
+        moduleId: entry.moduleId,
+        hint: 'Sidebar group ordering is a single app-wide decision; declare it on one module entry.',
+      })
+    }
+    state.modules = { moduleId: entry.moduleId, groupOrder }
+  }
+}
+
 function registerBuiltInModuleOverrideAppliers(): void {
+  registerModuleOverrideApplier<NavOverridesShape>('nav', navOverridesApplier)
   registerModuleOverrideApplier<RoutesOverridesShape>('routes', routesOverridesApplier)
   registerModuleOverrideApplier<EventsOverridesShape>('events', eventsOverridesApplier)
   registerModuleOverrideApplier<WorkerOverridesMap>('workers', workersOverridesApplier)