@open-mercato/shared 0.10.1-develop.7576.1.21d5b50435 → 0.10.1-develop.7577.1.477f2486e5

package/src/modules/search.ts

@@ -94,6 +94,39 @@ export type SearchOptions = {
   offset?: number
   /** How to combine results: 'or' merges all, 'and' requires match in all strategies */
   combineMode?: 'or' | 'and'
+  /**
+   * Restricts results to records whose query-index row (`entity_indexes`) matches this predicate,
+   * evaluated inside the strategy's ranking query so a restrictive filter never starves the result
+   * set (additive, 2026-10-06). Only strategies with `supportsIndexDocFilter: true` receive a
+   * filtered search; any other strategy returns no results for it rather than unfiltered ones.
+   */
+  indexDocFilter?: SearchIndexDocFilter
+}
+
+/**
+ * One condition over a record's query-index document (`entity_indexes.doc`), with the query
+ * engine's index-document semantics:
+ * - `exists`: the key is present and not JSON `null`;
+ * - `eq`: the key's text value equals `value` (booleans and numbers compare by their JSON text);
+ * - `overlap`: the key holds an array sharing at least one entry with `values`; empty `values`
+ *   matches nothing;
+ * - `noverlap`: the key holds an array sharing no entry with `values`; a missing key never matches;
+ * - `recordIdNotIn`: the record id is none of `values`.
+ */
+export type SearchIndexDocCondition =
+  | { op: 'exists'; key: string }
+  | { op: 'eq'; key: string; value: string | number | boolean }
+  | { op: 'overlap'; key: string; values: string[] }
+  | { op: 'noverlap'; key: string; values: string[] }
+  | { op: 'recordIdNotIn'; values: string[] }
+
+/**
+ * A predicate over a record's `entity_indexes` row in disjunctive normal form: the record matches
+ * when its index row is not deleted and every condition of at least one `anyOf` branch holds.
+ * An empty `anyOf` matches nothing; an empty branch matches every indexed record.
+ */
+export type SearchIndexDocFilter = {
+  anyOf: SearchIndexDocCondition[][]
 }
 
 // =============================================================================
@@ -144,6 +177,12 @@ export interface SearchStrategy {
   /** Priority for result merging (higher = more prominent in results) */
   readonly priority: number
 
+  /**
+   * Whether `search()` applies `SearchOptions.indexDocFilter` inside its ranking query. Absent or
+   * `false` means the strategy is skipped for filtered searches (fail closed).
+   */
+  readonly supportsIndexDocFilter?: boolean
+
   /** Check if strategy is available and configured */
   isAvailable(): Promise<boolean>
 

package/src/modules/widgets/__tests__/injection-loader.partitioned-registration.test.ts

@@ -0,0 +1,78 @@
+/**
+ * Regression coverage for the partitioned-bootstrap registry contract.
+ *
+ * A Node process can run more than one bootstrap partition: the API-only one
+ * (`skipCoreInjectionWidgets: true`) and the full page one. Two invariants have to hold
+ * together, and skipping registration outright only satisfied the first:
+ *
+ * 1. the partition that registers second must never shrink the registry the first published;
+ * 2. an API-only process must still be able to READ the registry, because module API routes
+ *    resolve widget contributions on the request path.
+ */
+import { describe, it, expect, beforeEach, jest } from '@jest/globals'
+import type { ModuleInjectionWidgetEntry } from '@open-mercato/shared/modules/registry'
+
+const GLOBAL_INJECTION_WIDGETS_KEY = '__openMercatoCoreInjectionWidgetEntries__'
+
+function entry(key: string): ModuleInjectionWidgetEntry {
+  return { moduleId: key.split(':')[0]!, key, source: 'package', widgetId: key, loader: async () => ({}) as never }
+}
+
+type Loader = typeof import('@open-mercato/shared/modules/widgets/injection-loader')
+
+function freshLoader(): Loader {
+  delete (globalThis as Record<string, unknown>)[GLOBAL_INJECTION_WIDGETS_KEY]
+  let loader!: Loader
+  jest.isolateModules(() => {
+    loader = require('@open-mercato/shared/modules/widgets/injection-loader') as Loader
+  })
+  return loader
+}
+
+describe('core injection widget registration modes', () => {
+  beforeEach(() => {
+    delete (globalThis as Record<string, unknown>)[GLOBAL_INJECTION_WIDGETS_KEY]
+  })
+
+  it('replaces the registry by default', () => {
+    const loader = freshLoader()
+    loader.registerCoreInjectionWidgets([entry('a:one'), entry('b:two')])
+    loader.registerCoreInjectionWidgets([entry('a:one')])
+
+    expect(loader.getCoreInjectionWidgets().map((it) => it.key)).toEqual(['a:one'])
+  })
+
+  it('populates an unregistered registry in merge mode instead of leaving it throwing', () => {
+    const loader = freshLoader()
+    expect(() => loader.getCoreInjectionWidgets()).toThrow(/not registered/)
+
+    loader.registerCoreInjectionWidgets([entry('a:one')], { mode: 'merge' })
+
+    expect(loader.getCoreInjectionWidgets().map((it) => it.key)).toEqual(['a:one'])
+  })
+
+  it('never shrinks a registry a fuller partition already published', () => {
+    const loader = freshLoader()
+    loader.registerCoreInjectionWidgets([entry('a:one'), entry('b:two'), entry('c:three')])
+    loader.registerCoreInjectionWidgets([entry('a:one')], { mode: 'merge' })
+
+    expect(loader.getCoreInjectionWidgets().map((it) => it.key)).toEqual(['a:one', 'b:two', 'c:three'])
+  })
+
+  it('adds only the entries the registry does not already carry', () => {
+    const loader = freshLoader()
+    loader.registerCoreInjectionWidgets([entry('a:one')])
+    loader.registerCoreInjectionWidgets([entry('a:one'), entry('d:four')], { mode: 'merge' })
+
+    expect(loader.getCoreInjectionWidgets().map((it) => it.key)).toEqual(['a:one', 'd:four'])
+  })
+
+  it('leaves an unregistered registry untouched when it has nothing to contribute', () => {
+    const loader = freshLoader()
+    loader.registerCoreInjectionWidgets([], { mode: 'merge' })
+
+    // Publishing an empty array here would turn the loud "not registered" bootstrap error into
+    // silently missing contributions on every request.
+    expect(() => loader.getCoreInjectionWidgets()).toThrow(/not registered/)
+  })
+})

package/src/modules/widgets/injection-loader.ts

@@ -141,11 +141,41 @@ function notifyInjectionRegistryChanged() {
   }))
 }
 
-export function registerCoreInjectionWidgets(entries: ModuleInjectionWidgetEntry[]) {
-  if (_coreInjectionWidgetEntries !== null && process.env.NODE_ENV === 'development') {
+export type RegisterCoreInjectionWidgetsOptions = {
+  /**
+   * `replace` (default) publishes `entries` as the whole registry.
+   *
+   * `merge` adds only the entries the registry does not already carry, keeping whatever a
+   * previous bootstrap published. A process may run more than one bootstrap partition (the
+   * API-only one and the full page one share a Node process in a mixed web host), and the
+   * partition that registers second must not shrink the registry the first one populated.
+   */
+  mode?: 'replace' | 'merge'
+}
+
+export function registerCoreInjectionWidgets(
+  entries: ModuleInjectionWidgetEntry[],
+  options: RegisterCoreInjectionWidgetsOptions = {},
+) {
+  if (_coreInjectionWidgetEntries !== null && process.env.NODE_ENV === 'development' && options.mode !== 'merge') {
     logger.debug('Core injection widgets re-registered (this may occur during HMR)')
   }
-  const finalEntries = applyInjectionWidgetOverridesToEntries(entries)
+  const incoming = applyInjectionWidgetOverridesToEntries(entries)
+  if (options.mode !== 'merge') {
+    _coreInjectionWidgetEntries = incoming
+    writeGlobalInjectionWidgets(incoming)
+    notifyInjectionRegistryChanged()
+    return
+  }
+
+  const existing = readGlobalInjectionWidgets() ?? _coreInjectionWidgetEntries ?? []
+  const known = new Set(existing.map((entry) => entry.key))
+  const added = incoming.filter((entry) => !known.has(entry.key))
+  // Nothing to contribute: leave the registry exactly as it was. Publishing an empty array here
+  // would turn "never registered" into "registered with no widgets", which downgrades the loud
+  // bootstrap error into silently missing contributions.
+  if (!added.length) return
+  const finalEntries = [...existing, ...added]
   _coreInjectionWidgetEntries = finalEntries
   writeGlobalInjectionWidgets(finalEntries)
   notifyInjectionRegistryChanged()