npm - @open-mercato/shared - Versions diffs - 0.7.0 → 0.7.1-develop.7103.1.41ff100d93 - Mend

@open-mercato/shared 0.7.0 → 0.7.1-develop.7103.1.41ff100d93

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (89) hide show

package/.turbo/turbo-build.log +1 -1
package/AGENTS.md +12 -1
package/dist/lib/auth/jwt.js +6 -0
package/dist/lib/auth/jwt.js.map +2 -2
package/dist/lib/auth/mfaPendingAccess.js +42 -0
package/dist/lib/auth/mfaPendingAccess.js.map +7 -0
package/dist/lib/auth/organizationAccess.js +7 -4
package/dist/lib/auth/organizationAccess.js.map +2 -2
package/dist/lib/auth/principal-service.js +1 -0
package/dist/lib/auth/principal-service.js.map +7 -0
package/dist/lib/auth/server.js +38 -7
package/dist/lib/auth/server.js.map +2 -2
package/dist/lib/commands/command-bus.js +6 -1
package/dist/lib/commands/command-bus.js.map +2 -2
package/dist/lib/crud/factory.js +29 -12
package/dist/lib/crud/factory.js.map +2 -2
package/dist/lib/crud/ids.js +6 -3
package/dist/lib/crud/ids.js.map +2 -2
package/dist/lib/crud/query-params.js +33 -0
package/dist/lib/crud/query-params.js.map +7 -0
package/dist/lib/data/engine.js +8 -2
package/dist/lib/data/engine.js.map +2 -2
package/dist/lib/html/htmlToPlainText.js +16 -0
package/dist/lib/html/htmlToPlainText.js.map +7 -0
package/dist/lib/location/countries.js +12 -0
package/dist/lib/location/countries.js.map +2 -2
package/dist/lib/openapi/crud.js +4 -1
package/dist/lib/openapi/crud.js.map +2 -2
package/dist/lib/query/count-cap.js +11 -0
package/dist/lib/query/count-cap.js.map +7 -0
package/dist/lib/query/engine.js +270 -34
package/dist/lib/query/engine.js.map +3 -3
package/dist/lib/query/types.js.map +1 -1
package/dist/lib/queue/dispatchOrigin.js +20 -0
package/dist/lib/queue/dispatchOrigin.js.map +7 -0
package/dist/lib/search/config.js +1 -0
package/dist/lib/search/config.js.map +2 -2
package/dist/lib/search/entityAccess.js +44 -0
package/dist/lib/search/entityAccess.js.map +7 -0
package/dist/lib/version.js +1 -1
package/dist/lib/version.js.map +1 -1
package/dist/modules/events/factory.js +69 -15
package/dist/modules/events/factory.js.map +2 -2
package/dist/modules/registry.js +15 -0
package/dist/modules/registry.js.map +2 -2
package/dist/modules/widgets/component-registry.js.map +2 -2
package/package.json +10 -3
package/src/lib/auth/__tests__/jwt.test.ts +13 -0
package/src/lib/auth/__tests__/mfaPendingAccess.test.ts +69 -0
package/src/lib/auth/__tests__/organizationAccess.test.ts +36 -1
package/src/lib/auth/__tests__/principalServiceExport.test.ts +67 -0
package/src/lib/auth/__tests__/server.apiKeyCache.test.ts +324 -0
package/src/lib/auth/__tests__/server.test.ts +104 -0
package/src/lib/auth/jwt.ts +17 -0
package/src/lib/auth/mfaPendingAccess.ts +70 -0
package/src/lib/auth/organizationAccess.ts +11 -3
package/src/lib/auth/principal-service.ts +110 -0
package/src/lib/auth/server.ts +78 -8
package/src/lib/commands/__tests__/command-bus.test.ts +31 -0
package/src/lib/commands/command-bus.ts +8 -1
package/src/lib/crud/__tests__/crud-factory.test.ts +236 -0
package/src/lib/crud/__tests__/ids.test.ts +29 -0
package/src/lib/crud/__tests__/query-params.test.ts +98 -0
package/src/lib/crud/factory.ts +38 -11
package/src/lib/crud/ids.ts +11 -8
package/src/lib/crud/query-params.ts +75 -0
package/src/lib/data/__tests__/engine.event-validation.test.ts +9 -1
package/src/lib/data/engine.ts +7 -1
package/src/lib/html/__tests__/htmlToPlainText.test.ts +59 -0
package/src/lib/html/htmlToPlainText.ts +17 -0
package/src/lib/location/__tests__/countries.test.ts +15 -0
package/src/lib/location/countries.ts +17 -0
package/src/lib/openapi/crud.ts +3 -0
package/src/lib/query/__tests__/count-cap-plan.test.ts +240 -0
package/src/lib/query/__tests__/count-cap.test.ts +41 -0
package/src/lib/query/__tests__/engine.count-distinct.test.ts +162 -15
package/src/lib/query/__tests__/engine.scope-and-or.test.ts +11 -1
package/src/lib/query/__tests__/engine.test.ts +445 -7
package/src/lib/query/count-cap.ts +19 -0
package/src/lib/query/engine.ts +434 -54
package/src/lib/query/types.ts +15 -0
package/src/lib/queue/dispatchOrigin.ts +35 -0
package/src/lib/search/config.ts +10 -0
package/src/lib/search/entityAccess.ts +132 -0
package/src/modules/events/__tests__/factory.test.ts +88 -0
package/src/modules/events/factory.ts +111 -19
package/src/modules/events/types.ts +17 -0
package/src/modules/registry.ts +40 -0
package/src/modules/widgets/component-registry.ts +14 -0

package/src/lib/data/__tests__/engine.event-validation.test.ts CHANGED Viewed

@@ -68,7 +68,15 @@ describe('DataEngine event contract validation (issue #1421)', () => {
       })
       expect(emitted).toEqual([
-        expect.objectContaining({ name: 'issue1421_test.widget.created' }),
+        expect.objectContaining({
+          name: 'issue1421_test.widget.created',
+          options: {
+            persistent: false,
+            tenantId: 'tenant-1',
+            organizationId: 'org-1',
+            emitterModuleId: 'issue1421_test',
+          },
+        }),
       ])
       expect(loggerWarn).not.toHaveBeenCalled()
     } finally {

package/src/lib/data/engine.ts CHANGED Viewed

@@ -226,7 +226,12 @@ export class DefaultDataEngine implements DataEngine {
           const eventName = `${mod}.${ent}.updated`
           warnIfUndeclaredEvent(eventName, 'setCustomFields')
           try {
-            await bus.emitEvent(eventName, { id: recordId, organizationId, tenantId }, { persistent: true })
+            await bus.emitEvent(eventName, { id: recordId, organizationId, tenantId }, {
+              persistent: true,
+              tenantId,
+              organizationId,
+              emitterModuleId: mod,
+            })
           } catch {
             // non-blocking
           }
@@ -627,6 +632,7 @@ export class DefaultDataEngine implements DataEngine {
           persistent: !!events.persistent,
           tenantId: ctx.identifiers.tenantId ?? null,
           organizationId: ctx.identifiers.organizationId ?? null,
+          emitterModuleId: events.module,
         })
       } catch {
         // non-blocking

package/src/lib/html/__tests__/htmlToPlainText.test.ts ADDED Viewed

@@ -0,0 +1,59 @@
+import { htmlToPlainText } from '../htmlToPlainText'
+describe('htmlToPlainText', () => {
+  it('returns an empty string for empty input without invoking the parser', () => {
+    expect(htmlToPlainText('')).toBe('')
+  })
+  it('renders block-level markup as readable prose', () => {
+    const html = '<html><body><p>Hello,</p><p>second paragraph.</p></body></html>'
+    const text = htmlToPlainText(html)
+    expect(text).toContain('Hello,')
+    expect(text).toContain('second paragraph.')
+    expect(text).not.toContain('<p>')
+    expect(text).not.toContain('</body>')
+  })
+  it('drops script and style content instead of inlining it as text', () => {
+    // Email HTML routinely carries a <style> block and a tracking <script>.
+    // Rendering either as text is what made ingested bodies unreadable.
+    const html = [
+      '<!DOCTYPE html><html><head>',
+      '<style>body { margin: 0; font-family: Helvetica; }</style>',
+      '<script>trackOpen("beacon")</script>',
+      '</head><body><p>Visible copy</p></body></html>',
+    ].join('')
+    const text = htmlToPlainText(html)
+    expect(text).toBe('Visible copy')
+    expect(text).not.toContain('font-family')
+    expect(text).not.toContain('trackOpen')
+    expect(text).not.toContain('<!DOCTYPE')
+  })
+  it('normalizes CRLF and lone CR line endings to LF', () => {
+    const text = htmlToPlainText('<pre>first\r\nsecond\rthird</pre>')
+    expect(text).not.toContain('\r')
+    expect(text).toBe('first\nsecond\nthird')
+  })
+  it('collapses runs of three or more blank lines down to one', () => {
+    const text = htmlToPlainText('<pre>top\n\n\n\n\nbottom</pre>')
+    expect(text).toBe('top\n\nbottom')
+  })
+  it('preserves a single blank line between paragraphs', () => {
+    const text = htmlToPlainText('<pre>top\n\nbottom</pre>')
+    expect(text).toBe('top\n\nbottom')
+  })
+  it('trims surrounding whitespace', () => {
+    expect(htmlToPlainText('<pre>\n\n  padded  \n\n</pre>')).toBe('padded')
+  })
+})

package/src/lib/html/htmlToPlainText.ts ADDED Viewed

@@ -0,0 +1,17 @@
+import { convert } from 'html-to-text'
+export function htmlToPlainText(html: string): string {
+  if (!html) return ''
+  return convert(html, {
+    wordwrap: false,
+    preserveNewlines: true,
+    selectors: [
+      { selector: 'script', format: 'skip' },
+      { selector: 'style', format: 'skip' },
+    ],
+  })
+    .replace(/\r\n/g, '\n')
+    .replace(/\r/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}

package/src/lib/location/__tests__/countries.test.ts CHANGED Viewed

@@ -2,6 +2,7 @@ import {
   COUNTRY_PRIORITY,
   ISO_COUNTRIES,
   buildCountryOptions,
+  matchCountryCodes,
   resolveCountryName,
 } from '../countries'
@@ -80,3 +81,17 @@ describe('buildCountryOptions', () => {
     expect(options).toEqual(expect.arrayContaining([{ code: 'XK', label: 'Kosovo (XK)' }]))
   })
 })
+describe('matchCountryCodes', () => {
+  it('maps English country names to ISO codes so list search can find stored PL rows', () => {
+    expect(matchCountryCodes('Poland')).toContain('PL')
+  })
+  it('maps localized names when extra locales are provided', () => {
+    expect(matchCountryCodes('Polska', { locales: ['pl'] })).toContain('PL')
+  })
+  it('returns nothing for blank search terms', () => {
+    expect(matchCountryCodes('   ')).toEqual([])
+  })
+})

package/src/lib/location/countries.ts CHANGED Viewed

@@ -106,3 +106,20 @@ export function buildCountryOptions(options: {
   return [...prioritized, ...remaining]
 }
+export function matchCountryCodes(
+  term: string,
+  options: { locales?: string[] } = {},
+): string[] {
+  const needle = term.trim().toLowerCase()
+  if (!needle) return []
+  const searchLocales = options.locales?.length ? options.locales : ['en']
+  return ISO_COUNTRIES
+    .filter((entry) => {
+      if (entry.name.toLowerCase().includes(needle)) return true
+      return searchLocales.some((locale) =>
+        resolveCountryName(entry.code, { locale }).toLowerCase().includes(needle),
+      )
+    })
+    .map((entry) => entry.code)
+}

package/src/lib/openapi/crud.ts CHANGED Viewed

@@ -17,6 +17,9 @@ export function createPagedListResponseSchema(itemSchema: ZodTypeAny, options: P
     page: paginationMetaOptional ? z.number().optional() : z.number(),
     pageSize: paginationMetaOptional ? z.number().optional() : z.number(),
     totalPages: z.number(),
+    // Present (true) only when the list count was bounded at OM_LIST_COUNT_CAP:
+    // `total` is then a floor, not an exact value.
+    totalIsCapped: z.boolean().optional(),
   })
 }

package/src/lib/query/__tests__/count-cap-plan.test.ts ADDED Viewed

@@ -0,0 +1,240 @@
+/**
+ * Plan-level guard for the capped list COUNT (#4552 Phase 2), run against a real
+ * PostgreSQL. This is the only test that fails if a future refactor reintroduces
+ * a blocking node (Aggregate/Sort/Unique) between the probe `Limit` and the base
+ * scan — a mocked total cannot catch a bound that does not bind. It doubles as
+ * the count-parity check: with the cap disabled, the rebuilt count must equal
+ * ground truth across the cf-filter / or-group / plain matrices.
+ *
+ * Gated on OM_COUNT_CAP_PG_URL (a throwaway database — the suite creates and
+ * drops its own tables). Example:
+ *   docker run --rm -d -p 54329:5432 -e POSTGRES_PASSWORD=t postgres:16
+ *   OM_COUNT_CAP_PG_URL=postgres://postgres:t@localhost:54329/postgres yarn jest count-cap-plan
+ */
+import { Kysely, PostgresDialect, sql } from 'kysely'
+import { BasicQueryEngine } from '../engine'
+const PG_URL = process.env.OM_COUNT_CAP_PG_URL
+const maybe = PG_URL ? describe : describe.skip
+const TENANT = '11111111-1111-4111-8111-111111111111'
+const ORG = '22222222-2222-4222-8222-222222222222'
+const ENTITY = 'capcheck:om_capcheck_order'
+const TABLE = 'om_capcheck_orders'
+const ROWS = 120
+const RED_ROWS = 30
+maybe('capped list COUNT against PostgreSQL', () => {
+  jest.setTimeout(60_000)
+  let db: Kysely<any>
+  let sqlLog: string[] = []
+  let paramLog: unknown[][] = []
+  const originalCap = process.env.OM_LIST_COUNT_CAP
+  beforeAll(async () => {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { Pool } = require('pg')
+    db = new Kysely<any>({
+      dialect: new PostgresDialect({ pool: new Pool({ connectionString: PG_URL }) }),
+      log(event) {
+        if (event.level === 'query' || event.level === 'error') {
+          sqlLog.push(event.query.sql)
+          paramLog.push([...event.query.parameters])
+        }
+      },
+    })
+    await sql`drop table if exists om_capcheck_orders`.execute(db)
+    await sql`create table om_capcheck_orders (
+      id uuid primary key,
+      tenant_id uuid not null,
+      organization_id uuid not null,
+      deleted_at timestamptz,
+      status text not null
+    )`.execute(db)
+    await sql`create table if not exists custom_field_defs (
+      id serial primary key,
+      key text not null,
+      entity_id text not null,
+      kind text,
+      config_json jsonb,
+      is_active boolean not null default true,
+      organization_id uuid,
+      tenant_id uuid,
+      updated_at timestamptz,
+      deleted_at timestamptz
+    )`.execute(db)
+    await sql`create table if not exists custom_field_values (
+      id serial primary key,
+      entity_id text not null,
+      field_key text not null,
+      record_id text not null,
+      value_text text,
+      value_multiline text,
+      value_int int,
+      value_float float,
+      value_bool boolean,
+      organization_id uuid,
+      tenant_id uuid
+    )`.execute(db)
+    await sql`delete from custom_field_defs where entity_id = ${ENTITY}`.execute(db)
+    await sql`delete from custom_field_values where entity_id = ${ENTITY}`.execute(db)
+    await sql`insert into custom_field_defs (key, entity_id, kind, is_active, tenant_id)
+      values ('color', ${ENTITY}, 'text', true, null)`.execute(db)
+    for (let i = 0; i < ROWS; i++) {
+      const id = `33333333-3333-4333-8333-${String(i).padStart(12, '0')}`
+      await sql`insert into om_capcheck_orders (id, tenant_id, organization_id, deleted_at, status)
+        values (${id}::uuid, ${TENANT}::uuid, ${ORG}::uuid, null, ${i % 2 === 0 ? 'open' : 'closed'})`.execute(db)
+      if (i < RED_ROWS) {
+        await sql`insert into custom_field_values (entity_id, field_key, record_id, value_text, tenant_id)
+          values (${ENTITY}, 'color', ${id}, 'red', ${TENANT}::uuid)`.execute(db)
+      }
+    }
+  })
+  afterAll(async () => {
+    await sql`drop table if exists om_capcheck_orders`.execute(db)
+    await sql`delete from custom_field_defs where entity_id = ${ENTITY}`.execute(db)
+    await sql`delete from custom_field_values where entity_id = ${ENTITY}`.execute(db)
+    await db.destroy()
+  })
+  afterEach(() => {
+    if (originalCap === undefined) delete process.env.OM_LIST_COUNT_CAP
+    else process.env.OM_LIST_COUNT_CAP = originalCap
+  })
+  const makeEngine = () => new BasicQueryEngine({} as any, () => db as any)
+  const baseOpts = {
+    tenantId: TENANT,
+    organizationId: ORG,
+    fields: ['id'],
+    page: { page: 1, pageSize: 10 },
+  }
+  function lastCountSql(): { text: string; params: unknown[] } {
+    for (let i = sqlLog.length - 1; i >= 0; i--) {
+      if (/count\(\*\)/i.test(sqlLog[i])) return { text: sqlLog[i], params: paramLog[i] }
+    }
+    throw new Error('no count SQL captured')
+  }
+  function collectNodes(node: any, out: any[] = []): any[] {
+    if (!node) return out
+    out.push(node)
+    for (const child of node.Plans ?? []) collectNodes(child, out)
+    return out
+  }
+  test('probe plan: no blocking node between the Limit and the base scan (cf-filtered)', async () => {
+    process.env.OM_LIST_COUNT_CAP = '50'
+    sqlLog = []; paramLog = []
+    const result = await makeEngine().query(ENTITY, {
+      ...baseOpts,
+      filters: { status: { $eq: 'open' } },
+    })
+    expect(result.total).toBe(50)
+    expect(result.meta?.listCountCapWarning).toEqual({ entity: ENTITY, cap: 50 })
+    const { text, params } = lastCountSql()
+    expect(text.toLowerCase()).toContain('limit')
+    const explained = await sql
+      .raw(`explain (format json) ${text.replace(/\$(\d+)/g, (_, n) => {
+        const value = params[Number(n) - 1]
+        return typeof value === 'number' ? String(value) : `'${String(value).replace(/'/g, "''")}'`
+      })}`)
+      .execute(db)
+    const plan = (explained.rows[0] as any)['QUERY PLAN'][0].Plan
+    const all = collectNodes(plan)
+    const limitNode = all.find((n) => n['Node Type'] === 'Limit')
+    expect(limitNode).toBeTruthy()
+    // Below the Limit: only row-producing nodes down to the scan. An Aggregate,
+    // Sort, or Unique here means the bound does not bind.
+    const belowLimit = collectNodes(limitNode).slice(1)
+    const blocking = belowLimit.filter((n) => /Aggregate|Sort|Unique/.test(String(n['Node Type'])))
+    expect(blocking).toEqual([])
+    // The base scan is inside the Limit subtree.
+    expect(belowLimit.some((n) => n['Relation Name'] === TABLE)).toBe(true)
+  })
+  test('cf filter compiles to EXISTS and stays cappable', async () => {
+    process.env.OM_LIST_COUNT_CAP = '10'
+    sqlLog = []; paramLog = []
+    const result = await makeEngine().query(ENTITY, {
+      ...baseOpts,
+      filters: { cf_color: { $eq: 'red' } },
+    })
+    expect(result.total).toBe(10)
+    expect(result.meta?.listCountCapWarning).toEqual({ entity: ENTITY, cap: 10 })
+    const { text } = lastCountSql()
+    expect(text.toLowerCase()).toContain('exists')
+    expect(text.toLowerCase()).not.toContain('group by')
+  })
+  test('parity with the cap disabled: rebuilt count matches the display query across the filter matrix', async () => {
+    process.env.OM_LIST_COUNT_CAP = '0'
+    const engine = makeEngine()
+    const wide = { page: { page: 1, pageSize: 1000 } }
+    // Each case asserts the rebuilt count against ground truth where the filter
+    // semantics are well-defined, and always against the display query's own
+    // row set — the regression guard for "count rebuild changing a total".
+    const expectParity = async (filters: any, expectedTotal?: number) => {
+      const result = await engine.query(ENTITY, { ...baseOpts, ...wide, filters })
+      expect(result.total).toBe(result.items.length)
+      if (expectedTotal !== undefined) expect(result.total).toBe(expectedTotal)
+      expect(result.meta?.listCountCapWarning).toBeUndefined()
+      return result
+    }
+    await expectParity(undefined, ROWS)
+    await expectParity({ status: { $eq: 'open' } }, ROWS / 2)
+    await expectParity({ cf_color: { $eq: 'red' } }, RED_ROWS)
+    await expectParity({ $and: [{ status: { $eq: 'open' } }, { cf_color: { $eq: 'red' } }] }, RED_ROWS / 2)
+    // Base-column-only $or exercises the or-group path in the count shape.
+    await expectParity({ $or: [{ status: { $eq: 'open' } }, { status: { $eq: 'closed' } }] }, ROWS)
+    // Mixed base + cf disjunction (#5039): the count shape must compile the cf
+    // leaf to an EXISTS rather than dropping it — a dropped leaf narrows the OR
+    // and undercounts. closed (60) ∪ red (30, half of which are closed) = 75.
+    await expectParity({ $or: [{ status: { $eq: 'closed' } }, { cf_color: { $eq: 'red' } }] }, ROWS / 2 + RED_ROWS / 2)
+    // cf-only disjunction: red (30) ∪ blue (0) = 30.
+    await expectParity({ $or: [{ cf_color: { $eq: 'red' } }, { cf_color: { $eq: 'blue' } }] }, RED_ROWS)
+    await expectParity({ cf_color: { $eq: 'blue' } }, 0)
+    await expectParity({ cf_color: { $eq: null } }, ROWS - RED_ROWS)
+    await expectParity({ cf_color: { $ne: 'red' } }, 0)
+    await expectParity({ cf_color: { $in: ['red', 'blue'] } }, RED_ROWS)
+  })
+  test('kill switch (cap=0): the cf-filtered count still plans set-oriented, not per-row', async () => {
+    // OM_LIST_COUNT_CAP=0 restores exact totals but runs them through the
+    // rebuilt shape. The documented escape hatch must not be slower than the
+    // problem: the uncapped EXISTS should plan as a semi-join or a hashed
+    // subplan, never an un-hashed per-row subplan re-executed for every row.
+    process.env.OM_LIST_COUNT_CAP = '0'
+    sqlLog = []; paramLog = []
+    const result = await makeEngine().query(ENTITY, {
+      ...baseOpts,
+      filters: { cf_color: { $eq: 'red' } },
+    })
+    expect(result.total).toBe(RED_ROWS)
+    const { text, params } = lastCountSql()
+    const explained = await sql
+      .raw(`explain (format json) ${text.replace(/\$(\d+)/g, (_, n) => {
+        const value = params[Number(n) - 1]
+        return typeof value === 'number' ? String(value) : `'${String(value).replace(/'/g, "''")}'`
+      })}`)
+      .execute(db)
+    const plan = (explained.rows[0] as any)['QUERY PLAN'][0].Plan
+    const all = collectNodes(plan)
+    const semiJoin = all.some((n) => /Semi/.test(String(n['Join Type'] ?? '')))
+    const hashedSubplan = all.some((n) => /hashed/i.test(String(n['Subplan Name'] ?? '')))
+    expect(semiJoin || hashedSubplan).toBe(true)
+  })
+  test('sub-cap totals stay exact with the cap active', async () => {
+    process.env.OM_LIST_COUNT_CAP = '1000'
+    const result = await makeEngine().query(ENTITY, { ...baseOpts, filters: { cf_color: { $eq: 'red' } } })
+    expect(result.total).toBe(RED_ROWS)
+    expect(result.meta?.listCountCapWarning).toBeUndefined()
+  })
+})

package/src/lib/query/__tests__/count-cap.test.ts ADDED Viewed

@@ -0,0 +1,41 @@
+import { resolveListCountCap, DEFAULT_LIST_COUNT_CAP } from '../count-cap'
+describe('resolveListCountCap', () => {
+  const original = process.env.OM_LIST_COUNT_CAP
+  afterEach(() => {
+    if (original === undefined) delete process.env.OM_LIST_COUNT_CAP
+    else process.env.OM_LIST_COUNT_CAP = original
+  })
+  test('unset: the default cap — the cap is on by default', () => {
+    delete process.env.OM_LIST_COUNT_CAP
+    expect(resolveListCountCap()).toBe(DEFAULT_LIST_COUNT_CAP)
+  })
+  test('blank: the default cap', () => {
+    process.env.OM_LIST_COUNT_CAP = '  '
+    expect(resolveListCountCap()).toBe(DEFAULT_LIST_COUNT_CAP)
+  })
+  test('0 disables capping', () => {
+    process.env.OM_LIST_COUNT_CAP = '0'
+    expect(resolveListCountCap()).toBeNull()
+  })
+  test('negative values disable capping like 0', () => {
+    process.env.OM_LIST_COUNT_CAP = '-5'
+    expect(resolveListCountCap()).toBeNull()
+  })
+  test('a positive integer is used as-is; floats floor', () => {
+    process.env.OM_LIST_COUNT_CAP = '500'
+    expect(resolveListCountCap()).toBe(500)
+    process.env.OM_LIST_COUNT_CAP = '500.9'
+    expect(resolveListCountCap()).toBe(500)
+  })
+  test('unparseable input falls back to the default — bad input must not silently disable the cap', () => {
+    process.env.OM_LIST_COUNT_CAP = 'unbounded'
+    expect(resolveListCountCap()).toBe(DEFAULT_LIST_COUNT_CAP)
+  })
+})