@objectstack/plugin-pinyin-search 17.0.0-rc.4 → 17.0.0-rc.6

package/CHANGELOG.md

@@ -1,5 +1,121 @@
 # @objectstack/plugin-pinyin-search
 
+## 17.0.0-rc.6
+
+### Patch Changes
+
+- 2465133: fix(plugins): sweep the service-lookup erasures out of the plugin composition roots, and fix the two alias-only HTTP reads it exposed (#4251 B5)
+
+  Batch B5 of the #4251 sweep: the seven remaining `packages/plugins/*` composition
+  roots. 35 lookup sites that had been erased to `any` now carry the slot's
+  contract, so the compiler checks what each plugin actually calls on the service
+  it resolved. The ratchet drops 143 sites / 32 files to 108 / 25.
+
+  **Two real defects, both of the shape this sweep exists to find.** Approvals'
+  actionable-link pages (ADR-0043) and sharing's public share-link REST routes each
+  read the HTTP server under `http-server` _only_ — the deprecated alias. The
+  ledger records `http.server` as canonical and as the only name present on every
+  provider path: `runtime.ts`'s `config.server` path registers no alias at all. On
+  that path both lookups threw, the surrounding `catch` swallowed it, and the
+  routes silently never mounted — approval e-mail action links 404'd and the
+  share-link surface was absent, with nothing in the log to say so. Both reads are
+  now canonical-first with the alias as fallback, each name in its own `try`
+  because `getService` throws on an empty slot (so `a() ?? b()` inside one `try`
+  never reaches `b` — the same correction #4393 made in metadata and
+  cloud-connection).
+
+  Typing choices follow the batch method: pure data-plane consumers take the
+  narrow contract (`IDataEngine` in reports), consumers that bind hook or
+  middleware seams take the engine seen whole (`IObjectQLEngine` in approvals,
+  sharing and pinyin-search), and slots with no contract get a **named** local
+  surface rather than `any` — plugin-email's `MailSettingsSurface`, and the
+  surfaces the consuming packages already declared (`ApprovalMessagingSurface`,
+  `SharingSecurityProbe`, `ReportEmail`). A named surface that omits a member
+  still makes the compiler name every call site; `any` says nothing.
+
+  No behaviour change beyond the two alias reads. No contract changes.
+
+- Updated dependencies [f16e54e]
+- Updated dependencies [06be54e]
+- Updated dependencies [259459d]
+- Updated dependencies [3f7f14e]
+- Updated dependencies [debe2f6]
+- Updated dependencies [ad878e7]
+- Updated dependencies [3028326]
+- Updated dependencies [ddd075a]
+- Updated dependencies [fe2dfa1]
+- Updated dependencies [6f6fec7]
+- Updated dependencies [ea1d916]
+- Updated dependencies [10c4ea9]
+- Updated dependencies [2ef1807]
+- Updated dependencies [55da611]
+- Updated dependencies [0fd8556]
+- Updated dependencies [6fde910]
+- Updated dependencies [9c82b89]
+- Updated dependencies [74155c7]
+- Updated dependencies [742a6a5]
+- Updated dependencies [6908830]
+- Updated dependencies [b7d3be4]
+- Updated dependencies [2a0d65e]
+- Updated dependencies [82da264]
+- Updated dependencies [f586f1a]
+- Updated dependencies [b127c8b]
+- Updated dependencies [92a67f2]
+- Updated dependencies [edb4af0]
+- Updated dependencies [f09a2e7]
+- Updated dependencies [fc3a36a]
+- Updated dependencies [69787f0]
+- Updated dependencies [5d022a1]
+- Updated dependencies [55011af]
+- Updated dependencies [3f8817a]
+- Updated dependencies [53ef057]
+- Updated dependencies [d6d1a50]
+- Updated dependencies [c804f19]
+- Updated dependencies [dbe92a7]
+- Updated dependencies [114e727]
+- Updated dependencies [5e247fd]
+- Updated dependencies [1a53a02]
+- Updated dependencies [1507ba3]
+- Updated dependencies [bf42e76]
+- Updated dependencies [bfe689b]
+- Updated dependencies [d0d5205]
+- Updated dependencies [de43f94]
+- Updated dependencies [28d1eb7]
+- Updated dependencies [3fb42d2]
+- Updated dependencies [82397b6]
+- Updated dependencies [4df747c]
+- Updated dependencies [7084313]
+- Updated dependencies [47a4e67]
+- Updated dependencies [91cefb8]
+- Updated dependencies [9bc846b]
+- Updated dependencies [4fedb11]
+- Updated dependencies [d13f627]
+- Updated dependencies [a841151]
+- Updated dependencies [1788e19]
+- Updated dependencies [1f6ed16]
+- Updated dependencies [d86815e]
+- Updated dependencies [e13fd91]
+- Updated dependencies [2bd4e5e]
+- Updated dependencies [129b378]
+- Updated dependencies [88f9d94]
+- Updated dependencies [1818998]
+- Updated dependencies [c9bf940]
+- Updated dependencies [a682670]
+  - @objectstack/objectql@17.0.0-rc.6
+  - @objectstack/core@17.0.0-rc.6
+  - @objectstack/types@17.0.0-rc.6
+
+## 17.0.0-rc.5
+
+### Patch Changes
+
+- Updated dependencies [ee3bde1]
+- Updated dependencies [1363084]
+- Updated dependencies [148d451]
+  - @objectstack/objectql@17.0.0-rc.5
+  - @objectstack/core@17.0.0-rc.5
+  - @objectstack/types@17.0.0-rc.5
+
 ## 17.0.0-rc.4
 
 ### Patch Changes

package/dist/index.d.mts

@@ -37,6 +37,12 @@ declare class PinyinSearchPlugin implements Plugin {
     private get enabled();
     init(_ctx: PluginContext): Promise<void>;
     start(ctx: PluginContext): Promise<void>;
+    /**
+     * [#4251 B5] The engine SEEN WHOLE — `bindSearchCompanionHooks` binds
+     * `registerHook`, which lives on `IObjectQLEngine`, not on the data plane.
+     * The ledger records `objectql` as "the SAME instance as `data`, seen whole",
+     * so the alias fallback resolves the same object under the same contract.
+     */
     private resolveEngine;
 }
 

package/dist/index.d.ts

@@ -37,6 +37,12 @@ declare class PinyinSearchPlugin implements Plugin {
     private get enabled();
     init(_ctx: PluginContext): Promise<void>;
     start(ctx: PluginContext): Promise<void>;
+    /**
+     * [#4251 B5] The engine SEEN WHOLE — `bindSearchCompanionHooks` binds
+     * `registerHook`, which lives on `IObjectQLEngine`, not on the data plane.
+     * The ledger records `objectql` as "the SAME instance as `data`, seen whole",
+     * so the alias fallback resolves the same object under the same contract.
+     */
     private resolveEngine;
 }
 

package/dist/index.js

@@ -207,6 +207,12 @@ var PinyinSearchPlugin = class {
       });
     }
   }
+  /**
+   * [#4251 B5] The engine SEEN WHOLE — `bindSearchCompanionHooks` binds
+   * `registerHook`, which lives on `IObjectQLEngine`, not on the data plane.
+   * The ledger records `objectql` as "the SAME instance as `data`, seen whole",
+   * so the alias fallback resolves the same object under the same contract.
+   */
   resolveEngine(ctx) {
     try {
       return ctx.getService("objectql");

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/pinyin-search-plugin.ts","../src/companion-projection.ts","../src/pinyin.ts"],"sourcesContent":["// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nexport { PinyinSearchPlugin } from './pinyin-search-plugin.js';\nexport type { PinyinSearchPluginOptions } from './pinyin-search-plugin.js';\nexport {\n  bindSearchCompanionHooks,\n  backfillSearchCompanion,\n  rebuildSearchCompanion,\n  PINYIN_SEARCH_HOOK_PACKAGE,\n} from './companion-projection.js';\nexport type {\n  CompanionBackfillOptions,\n  CompanionBackfillResult,\n} from './companion-projection.js';\nexport { computeSearchCompanionValue } from './pinyin.js';\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * PinyinSearchPlugin (#2486) — pinyin recall for `$search`.\n *\n * Pure hook plugin: the `__search` companion column is declared at object\n * compile time by the SchemaRegistry (gated on the SAME\n * `OS_SEARCH_PINYIN_ENABLED` decision point), the engine ORs it into the\n * `$search` filter, and this plugin fills the value:\n *\n *   - before-save hooks: recompute full pinyin + initials of the\n *     display/name field when it changes;\n *   - boot backfill (`kernel:bootstrapped`): fill rows that predate the\n *     switch or arrived via hook-bypassing writes;\n *   - `rebuildSearchCompanion` (exported): explicit reconcile/rebuild entry.\n *\n * When the flag is off the plugin is inert: no hooks, no backfill, and\n * `pinyin-pro` is never imported.\n */\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport { resolveSearchPinyinEnabled } from '@objectstack/types';\nimport {\n  bindSearchCompanionHooks,\n  backfillSearchCompanion,\n} from './companion-projection.js';\n\nexport interface PinyinSearchPluginOptions {\n  /**\n   * Force-enable/disable regardless of `OS_SEARCH_PINYIN_ENABLED` (tests /\n   * embedders). Default: `resolveSearchPinyinEnabled()`.\n   */\n  enabled?: boolean;\n  /** Skip the boot backfill (default: run it once per boot). */\n  backfill?: boolean;\n}\n\nexport class PinyinSearchPlugin implements Plugin {\n  name = 'com.objectstack.plugin.pinyin-search';\n  version = '1.0.0';\n  type = 'standard';\n  dependencies = ['com.objectstack.engine.objectql'];\n\n  private readonly options: PinyinSearchPluginOptions;\n\n  constructor(options: PinyinSearchPluginOptions = {}) {\n    this.options = options;\n  }\n\n  private get enabled(): boolean {\n    return this.options.enabled ?? resolveSearchPinyinEnabled();\n  }\n\n  async init(_ctx: PluginContext): Promise<void> {\n    // Nothing to register: the companion column is provisioned by the\n    // SchemaRegistry's compile-time seam, not injected at runtime.\n  }\n\n  async start(ctx: PluginContext): Promise<void> {\n    if (!this.enabled) {\n      ctx.logger.debug?.('PinyinSearchPlugin: OS_SEARCH_PINYIN_ENABLED is off — inert');\n      return;\n    }\n\n    ctx.hook('kernel:ready', async () => {\n      const engine = this.resolveEngine(ctx);\n      if (!engine) {\n        ctx.logger.warn('PinyinSearchPlugin: no ObjectQL engine — companion hooks NOT bound');\n        return;\n      }\n      try {\n        bindSearchCompanionHooks(engine, ctx.logger as any);\n      } catch (err: any) {\n        ctx.logger.warn('PinyinSearchPlugin: companion hooks not bound', { error: err?.message });\n      }\n    });\n\n    // Backfill AFTER boot settles (`kernel:bootstrapped` fires once every\n    // `kernel:ready` hook — including seed loading — has completed), so\n    // seeded rows written before/around hook binding are reconciled too.\n    if (this.options.backfill !== false) {\n      ctx.hook('kernel:bootstrapped', async () => {\n        const engine = this.resolveEngine(ctx);\n        if (!engine) return;\n        try {\n          await backfillSearchCompanion(engine, ctx.logger as any);\n        } catch (err: any) {\n          ctx.logger.warn('PinyinSearchPlugin: companion backfill failed', { error: err?.message });\n        }\n      });\n    }\n  }\n\n  private resolveEngine(ctx: PluginContext): any {\n    try {\n      return ctx.getService<any>('objectql');\n    } catch {\n      try {\n        return ctx.getService<any>('data');\n      } catch {\n        return null;\n      }\n    }\n  }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * `__search` companion-column projection (#2486).\n *\n * The column itself is DECLARED at object compile time by the SchemaRegistry\n * (`provisionSearchCompanion`, gated on `OS_SEARCH_PINYIN_ENABLED`); this\n * module only FILLS the value — the `plugin-sharing` primary-BU projection\n * pattern (column on the object, plugin maintains it via hooks).\n *\n * Write path: global `beforeInsert`/`beforeUpdate` hooks stamp\n * `data.__search` whenever a companion source field (the object's\n * display/name field) is present in the write — i.e. only when the source\n * actually changed, avoiding write amplification. Writes that bypass hooks\n * (bulk import, direct migration) leave the companion empty; the boot\n * backfill and the `rebuildSearchCompanion` reconcile entry cover that.\n */\n\nimport {\n  SEARCH_COMPANION_FIELD,\n  resolveSearchCompanionSources,\n  containsCJK,\n} from '@objectstack/objectql';\nimport { keysetWalk } from '@objectstack/types';\nimport { computeSearchCompanionValue } from './pinyin.js';\n\nconst SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] } as const;\n\nexport const PINYIN_SEARCH_HOOK_PACKAGE = 'plugin-pinyin-search:companion';\n\ninterface MinimalEngine {\n  registerHook(\n    event: string,\n    handler: (ctx: any) => any | Promise<any>,\n    options?: { object?: string | string[]; priority?: number; packageId?: string },\n  ): void;\n  unregisterHooksByPackage(packageId: string): number;\n  find(object: string, query?: any, options?: any): Promise<any[]>;\n  update(object: string, data: any, options?: any): Promise<any>;\n  registry?: {\n    getObject(name: string): any;\n    getAllObjects?(packageId?: string): any[];\n  };\n}\n\ninterface MinimalLogger {\n  info?: (msg: any, ...rest: any[]) => void;\n  warn?: (msg: any, ...rest: any[]) => void;\n  debug?: (msg: any, ...rest: any[]) => void;\n}\n\n/**\n * Stamp `data.__search` on a before-save hook context when a companion source\n * field is part of the write. Recomputes from the NEW value; a non-CJK new\n * value clears the companion (null) so stale pinyin never recalls a renamed\n * record. Never throws — a normalization failure must not fail the write.\n */\nasync function stampCompanion(engine: MinimalEngine, ctx: any, logger?: MinimalLogger): Promise<void> {\n  const object = ctx?.object;\n  if (!object) return;\n  const schema = engine.registry?.getObject?.(object);\n  if (!schema?.fields?.[SEARCH_COMPANION_FIELD]) return;\n\n  const data = ctx?.input?.data;\n  if (!data || typeof data !== 'object' || Array.isArray(data)) return;\n\n  const sources = resolveSearchCompanionSources(schema);\n  if (sources.length === 0) return;\n  const touched = sources.filter((s) => Object.prototype.hasOwnProperty.call(data, s));\n  if (touched.length === 0) return; // source unchanged → no recompute (no write amplification)\n\n  try {\n    data[SEARCH_COMPANION_FIELD] = await computeSearchCompanionValue(sources.map((s) => data[s]));\n  } catch (err: any) {\n    logger?.warn?.('[pinyin-search] companion normalization failed — write proceeds without it', {\n      object,\n      error: err?.message,\n    });\n  }\n}\n\n/**\n * Bind the global before-save hooks that keep `__search` in step. Idempotent\n * (unbinds the package first). Hooks are global (no object filter) with a\n * cheap early-out: objects without a provisioned companion column return\n * immediately. They run for system-context writes too — the projection must\n * stay correct regardless of who writes (seeds, imports, admin UI).\n */\nexport function bindSearchCompanionHooks(engine: MinimalEngine, logger?: MinimalLogger): void {\n  if (typeof engine.registerHook !== 'function') return;\n  if (typeof engine.unregisterHooksByPackage === 'function') {\n    engine.unregisterHooksByPackage(PINYIN_SEARCH_HOOK_PACKAGE);\n  }\n  const opts = { packageId: PINYIN_SEARCH_HOOK_PACKAGE, priority: 150 };\n  const handler = (ctx: any) => stampCompanion(engine, ctx, logger);\n  engine.registerHook('beforeInsert', handler, opts);\n  engine.registerHook('beforeUpdate', handler, opts);\n  logger?.info?.('[pinyin-search] companion hooks bound (beforeInsert/beforeUpdate, all objects)');\n}\n\nexport interface CompanionBackfillOptions {\n  /** Rows fetched per page during the scan. Default 1000. */\n  batchSize?: number;\n  /** Restrict to one object (reconcile entry); default: every provisioned object. */\n  object?: string;\n  /**\n   * Recompute EVERY row's companion, not just missing ones — the periodic\n   * reconcile/rebuild mode. Default false (backfill: only rows whose\n   * companion is empty but whose source has CJK content).\n   */\n  force?: boolean;\n}\n\nexport interface CompanionBackfillResult {\n  objects: number;\n  scanned: number;\n  updated: number;\n}\n\n/**\n * Backfill / reconcile the companion column.\n *\n * Denormalized-on-write columns go stale when writes bypass hooks (bulk\n * import, direct migration) and are empty for rows that predate the switch\n * being enabled. This scans every object that carries the companion column\n * (paged, system context) and fills the gaps; with `force: true` it\n * recomputes unconditionally (the periodic reconcile / rebuild entry).\n * Idempotent; per-row failures are skipped so one bad row never aborts the\n * pass.\n */\nexport async function backfillSearchCompanion(\n  engine: MinimalEngine,\n  logger?: MinimalLogger,\n  options?: CompanionBackfillOptions,\n): Promise<CompanionBackfillResult> {\n  const batchSize = Math.max(1, options?.batchSize ?? 1000);\n  const all = options?.object\n    ? [engine.registry?.getObject?.(options.object)].filter(Boolean)\n    : engine.registry?.getAllObjects?.() ?? [];\n\n  const result: CompanionBackfillResult = { objects: 0, scanned: 0, updated: 0 };\n\n  for (const schema of all) {\n    if (!schema?.name || !schema?.fields?.[SEARCH_COMPANION_FIELD]) continue;\n    const sources = resolveSearchCompanionSources(schema);\n    if (sources.length === 0) continue;\n    result.objects++;\n\n    // Seek by `id` (#4363). This walk UPDATES the rows it reads, and an offset\n    // counts into a set those writes are changing, so rows slide past the\n    // cursor and never get their companion blob — a backfill that reports a\n    // clean pass while leaving records unsearchable.\n    const walk = keysetWalk<any>(\n      (q) => engine.find(schema.name, {\n        ...q,\n        fields: ['id', ...sources, SEARCH_COMPANION_FIELD],\n        context: SYSTEM_CTX,\n      }),\n      { pageSize: batchSize },\n    );\n\n    try {\n      for await (const rows of walk.pages()) {\n      result.scanned += rows.length;\n\n      for (const row of rows) {\n        if (row?.id == null) continue;\n        const hasBlob = typeof row[SEARCH_COMPANION_FIELD] === 'string' && row[SEARCH_COMPANION_FIELD] !== '';\n        const hasCjkSource = sources.some((s) => containsCJK(row[s]));\n        // Backfill mode: touch only rows missing a blob they should have.\n        // Force mode: recompute everything (also clears stale blobs).\n        if (!options?.force && (hasBlob || !hasCjkSource)) continue;\n        try {\n          const value = await computeSearchCompanionValue(sources.map((s) => row[s]));\n          if (!options?.force && value == null) continue;\n          if (value === row[SEARCH_COMPANION_FIELD]) continue;\n          await engine.update(\n            schema.name,\n            { id: row.id, [SEARCH_COMPANION_FIELD]: value },\n            { context: SYSTEM_CTX },\n          );\n          result.updated++;\n        } catch (err: any) {\n          logger?.warn?.('[pinyin-search] backfill row skipped', {\n            object: schema.name,\n            id: row.id,\n            error: err?.message,\n          });\n        }\n      }\n      }\n    } catch (err: any) {\n      logger?.warn?.('[pinyin-search] backfill scan failed', { object: schema.name, error: err?.message });\n      continue;\n    }\n  }\n\n  if (result.updated > 0) {\n    logger?.info?.('[pinyin-search] companion backfill complete', result);\n  }\n  return result;\n}\n\n/**\n * Periodic reconcile / rebuild entry: recompute the companion for every row\n * (optionally one object). Alias for `backfillSearchCompanion` with\n * `force: true` — exposed under its own name so operators/jobs have an\n * explicit \"rebuild the pinyin index\" handle.\n */\nexport function rebuildSearchCompanion(\n  engine: MinimalEngine,\n  logger?: MinimalLogger,\n  options?: Omit<CompanionBackfillOptions, 'force'>,\n): Promise<CompanionBackfillResult> {\n  return backfillSearchCompanion(engine, logger, { ...options, force: true });\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Pinyin normalization for the `__search` companion column (#2486).\n *\n * One normalized blob per record — full pinyin AND initials in the same\n * column — so a single `$contains` recalls every latin input shape:\n *\n *   \"张伟\"  →  \"zhangwei zw\"\n *     `zhang` / `wei` / `zhangwei`  → substring of the full form\n *     `zw`                          → substring of the initials form\n *\n * `pinyin-pro` is loaded lazily on first use: non-Chinese deployments (flag\n * off → hooks never bound) never import it and pay zero cost.\n *\n * Polyphones: pinyin-pro's default heuristics are accepted (issue #2486\n * \"待定\" — surname polyphone dictionaries are a P2 follow-up).\n */\n\nimport { containsCJK } from '@objectstack/objectql';\n\ntype PinyinFn = (text: string, options?: Record<string, unknown>) => string | string[];\n\nlet _pinyin: Promise<PinyinFn> | null = null;\n\n/** Lazy-load `pinyin-pro` (cached module-wide). */\nfunction loadPinyin(): Promise<PinyinFn> {\n  _pinyin ??= import('pinyin-pro').then((m: any) => (m.pinyin ?? m.default?.pinyin) as PinyinFn);\n  return _pinyin;\n}\n\n/** Lowercase and strip everything that is not a latin letter or digit. */\nfunction squash(syllables: string | string[]): string {\n  const joined = Array.isArray(syllables) ? syllables.join('') : String(syllables ?? '');\n  return joined.toLowerCase().replace(/[^a-z0-9]+/g, '');\n}\n\n/**\n * Compute the companion value for the given source-field values.\n *\n * Returns the normalized blob (`\"<full-pinyin> <initials>\"`, deduplicated)\n * when at least one value contains CJK characters, else `null` — a `null`\n * companion means \"nothing pinyin-searchable here\" and clears any stale blob\n * when a name is edited away from CJK. Non-CJK values need no companion:\n * their source column already matches latin input directly.\n */\nexport async function computeSearchCompanionValue(values: ReadonlyArray<unknown>): Promise<string | null> {\n  const cjkValues = values.filter((v): v is string => containsCJK(v));\n  if (cjkValues.length === 0) return null;\n\n  const pinyin = await loadPinyin();\n  const parts: string[] = [];\n  for (const value of cjkValues) {\n    // `nonZh: 'consecutive'` keeps latin/digit runs intact inside mixed\n    // values (\"张伟2号\" → \"zhangwei2hao\"), so mixed names stay one token.\n    const full = squash(pinyin(value, { toneType: 'none', type: 'array', nonZh: 'consecutive' }));\n    const initials = squash(pinyin(value, { pattern: 'first', toneType: 'none', type: 'array', nonZh: 'consecutive' }));\n    if (full) parts.push(full);\n    if (initials && initials !== full) parts.push(initials);\n  }\n  if (parts.length === 0) return null;\n  return [...new Set(parts)].join(' ');\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACqBA,IAAAA,gBAA2C;;;ACH3C,IAAAC,mBAIO;AACP,mBAA2B;;;ACJ3B,sBAA4B;AAI5B,IAAI,UAAoC;AAGxC,SAAS,aAAgC;AACvC,wBAAY,OAAO,YAAY,EAAE,KAAK,CAAC,MAAY,EAAE,UAAU,EAAE,SAAS,MAAmB;AAC7F,SAAO;AACT;AAGA,SAAS,OAAO,WAAsC;AACpD,QAAM,SAAS,MAAM,QAAQ,SAAS,IAAI,UAAU,KAAK,EAAE,IAAI,OAAO,aAAa,EAAE;AACrF,SAAO,OAAO,YAAY,EAAE,QAAQ,eAAe,EAAE;AACvD;AAWA,eAAsB,4BAA4B,QAAwD;AACxG,QAAM,YAAY,OAAO,OAAO,CAAC,UAAmB,6BAAY,CAAC,CAAC;AAClE,MAAI,UAAU,WAAW,EAAG,QAAO;AAEnC,QAAM,SAAS,MAAM,WAAW;AAChC,QAAM,QAAkB,CAAC;AACzB,aAAW,SAAS,WAAW;AAG7B,UAAM,OAAO,OAAO,OAAO,OAAO,EAAE,UAAU,QAAQ,MAAM,SAAS,OAAO,cAAc,CAAC,CAAC;AAC5F,UAAM,WAAW,OAAO,OAAO,OAAO,EAAE,SAAS,SAAS,UAAU,QAAQ,MAAM,SAAS,OAAO,cAAc,CAAC,CAAC;AAClH,QAAI,KAAM,OAAM,KAAK,IAAI;AACzB,QAAI,YAAY,aAAa,KAAM,OAAM,KAAK,QAAQ;AAAA,EACxD;AACA,MAAI,MAAM,WAAW,EAAG,QAAO;AAC/B,SAAO,CAAC,GAAG,IAAI,IAAI,KAAK,CAAC,EAAE,KAAK,GAAG;AACrC;;;ADpCA,IAAM,aAAa,EAAE,UAAU,MAAM,WAAW,CAAC,GAAG,aAAa,CAAC,EAAE;AAE7D,IAAM,6BAA6B;AA6B1C,eAAe,eAAe,QAAuB,KAAU,QAAuC;AACpG,QAAM,SAAS,KAAK;AACpB,MAAI,CAAC,OAAQ;AACb,QAAM,SAAS,OAAO,UAAU,YAAY,MAAM;AAClD,MAAI,CAAC,QAAQ,SAAS,uCAAsB,EAAG;AAE/C,QAAM,OAAO,KAAK,OAAO;AACzB,MAAI,CAAC,QAAQ,OAAO,SAAS,YAAY,MAAM,QAAQ,IAAI,EAAG;AAE9D,QAAM,cAAU,gDAA8B,MAAM;AACpD,MAAI,QAAQ,WAAW,EAAG;AAC1B,QAAM,UAAU,QAAQ,OAAO,CAAC,MAAM,OAAO,UAAU,eAAe,KAAK,MAAM,CAAC,CAAC;AACnF,MAAI,QAAQ,WAAW,EAAG;AAE1B,MAAI;AACF,SAAK,uCAAsB,IAAI,MAAM,4BAA4B,QAAQ,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC;AAAA,EAC9F,SAAS,KAAU;AACjB,YAAQ,OAAO,mFAA8E;AAAA,MAC3F;AAAA,MACA,OAAO,KAAK;AAAA,IACd,CAAC;AAAA,EACH;AACF;AASO,SAAS,yBAAyB,QAAuB,QAA8B;AAC5F,MAAI,OAAO,OAAO,iBAAiB,WAAY;AAC/C,MAAI,OAAO,OAAO,6BAA6B,YAAY;AACzD,WAAO,yBAAyB,0BAA0B;AAAA,EAC5D;AACA,QAAM,OAAO,EAAE,WAAW,4BAA4B,UAAU,IAAI;AACpE,QAAM,UAAU,CAAC,QAAa,eAAe,QAAQ,KAAK,MAAM;AAChE,SAAO,aAAa,gBAAgB,SAAS,IAAI;AACjD,SAAO,aAAa,gBAAgB,SAAS,IAAI;AACjD,UAAQ,OAAO,gFAAgF;AACjG;AAgCA,eAAsB,wBACpB,QACA,QACA,SACkC;AAClC,QAAM,YAAY,KAAK,IAAI,GAAG,SAAS,aAAa,GAAI;AACxD,QAAM,MAAM,SAAS,SACjB,CAAC,OAAO,UAAU,YAAY,QAAQ,MAAM,CAAC,EAAE,OAAO,OAAO,IAC7D,OAAO,UAAU,gBAAgB,KAAK,CAAC;AAE3C,QAAM,SAAkC,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,EAAE;AAE7E,aAAW,UAAU,KAAK;AACxB,QAAI,CAAC,QAAQ,QAAQ,CAAC,QAAQ,SAAS,uCAAsB,EAAG;AAChE,UAAM,cAAU,gDAA8B,MAAM;AACpD,QAAI,QAAQ,WAAW,EAAG;AAC1B,WAAO;AAMP,UAAM,WAAO;AAAA,MACX,CAAC,MAAM,OAAO,KAAK,OAAO,MAAM;AAAA,QAC9B,GAAG;AAAA,QACH,QAAQ,CAAC,MAAM,GAAG,SAAS,uCAAsB;AAAA,QACjD,SAAS;AAAA,MACX,CAAC;AAAA,MACD,EAAE,UAAU,UAAU;AAAA,IACxB;AAEA,QAAI;AACF,uBAAiB,QAAQ,KAAK,MAAM,GAAG;AACvC,eAAO,WAAW,KAAK;AAEvB,mBAAW,OAAO,MAAM;AACtB,cAAI,KAAK,MAAM,KAAM;AACrB,gBAAM,UAAU,OAAO,IAAI,uCAAsB,MAAM,YAAY,IAAI,uCAAsB,MAAM;AACnG,gBAAM,eAAe,QAAQ,KAAK,CAAC,UAAM,8BAAY,IAAI,CAAC,CAAC,CAAC;AAG5D,cAAI,CAAC,SAAS,UAAU,WAAW,CAAC,cAAe;AACnD,cAAI;AACF,kBAAM,QAAQ,MAAM,4BAA4B,QAAQ,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC;AAC1E,gBAAI,CAAC,SAAS,SAAS,SAAS,KAAM;AACtC,gBAAI,UAAU,IAAI,uCAAsB,EAAG;AAC3C,kBAAM,OAAO;AAAA,cACX,OAAO;AAAA,cACP,EAAE,IAAI,IAAI,IAAI,CAAC,uCAAsB,GAAG,MAAM;AAAA,cAC9C,EAAE,SAAS,WAAW;AAAA,YACxB;AACA,mBAAO;AAAA,UACT,SAAS,KAAU;AACjB,oBAAQ,OAAO,wCAAwC;AAAA,cACrD,QAAQ,OAAO;AAAA,cACf,IAAI,IAAI;AAAA,cACR,OAAO,KAAK;AAAA,YACd,CAAC;AAAA,UACH;AAAA,QACF;AAAA,MACA;AAAA,IACF,SAAS,KAAU;AACjB,cAAQ,OAAO,wCAAwC,EAAE,QAAQ,OAAO,MAAM,OAAO,KAAK,QAAQ,CAAC;AACnG;AAAA,IACF;AAAA,EACF;AAEA,MAAI,OAAO,UAAU,GAAG;AACtB,YAAQ,OAAO,+CAA+C,MAAM;AAAA,EACtE;AACA,SAAO;AACT;AAQO,SAAS,uBACd,QACA,QACA,SACkC;AAClC,SAAO,wBAAwB,QAAQ,QAAQ,EAAE,GAAG,SAAS,OAAO,KAAK,CAAC;AAC5E;;;ADlLO,IAAM,qBAAN,MAA2C;AAAA,EAQhD,YAAY,UAAqC,CAAC,GAAG;AAPrD,gBAAO;AACP,mBAAU;AACV,gBAAO;AACP,wBAAe,CAAC,iCAAiC;AAK/C,SAAK,UAAU;AAAA,EACjB;AAAA,EAEA,IAAY,UAAmB;AAC7B,WAAO,KAAK,QAAQ,eAAW,0CAA2B;AAAA,EAC5D;AAAA,EAEA,MAAM,KAAK,MAAoC;AAAA,EAG/C;AAAA,EAEA,MAAM,MAAM,KAAmC;AAC7C,QAAI,CAAC,KAAK,SAAS;AACjB,UAAI,OAAO,QAAQ,kEAA6D;AAChF;AAAA,IACF;AAEA,QAAI,KAAK,gBAAgB,YAAY;AACnC,YAAM,SAAS,KAAK,cAAc,GAAG;AACrC,UAAI,CAAC,QAAQ;AACX,YAAI,OAAO,KAAK,yEAAoE;AACpF;AAAA,MACF;AACA,UAAI;AACF,iCAAyB,QAAQ,IAAI,MAAa;AAAA,MACpD,SAAS,KAAU;AACjB,YAAI,OAAO,KAAK,iDAAiD,EAAE,OAAO,KAAK,QAAQ,CAAC;AAAA,MAC1F;AAAA,IACF,CAAC;AAKD,QAAI,KAAK,QAAQ,aAAa,OAAO;AACnC,UAAI,KAAK,uBAAuB,YAAY;AAC1C,cAAM,SAAS,KAAK,cAAc,GAAG;AACrC,YAAI,CAAC,OAAQ;AACb,YAAI;AACF,gBAAM,wBAAwB,QAAQ,IAAI,MAAa;AAAA,QACzD,SAAS,KAAU;AACjB,cAAI,OAAO,KAAK,iDAAiD,EAAE,OAAO,KAAK,QAAQ,CAAC;AAAA,QAC1F;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF;AAAA,EAEQ,cAAc,KAAyB;AAC7C,QAAI;AACF,aAAO,IAAI,WAAgB,UAAU;AAAA,IACvC,QAAQ;AACN,UAAI;AACF,eAAO,IAAI,WAAgB,MAAM;AAAA,MACnC,QAAQ;AACN,eAAO;AAAA,MACT;AAAA,IACF;AAAA,EACF;AACF;","names":["import_types","import_objectql"]}
+{"version":3,"sources":["../src/index.ts","../src/pinyin-search-plugin.ts","../src/companion-projection.ts","../src/pinyin.ts"],"sourcesContent":["// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nexport { PinyinSearchPlugin } from './pinyin-search-plugin.js';\nexport type { PinyinSearchPluginOptions } from './pinyin-search-plugin.js';\nexport {\n  bindSearchCompanionHooks,\n  backfillSearchCompanion,\n  rebuildSearchCompanion,\n  PINYIN_SEARCH_HOOK_PACKAGE,\n} from './companion-projection.js';\nexport type {\n  CompanionBackfillOptions,\n  CompanionBackfillResult,\n} from './companion-projection.js';\nexport { computeSearchCompanionValue } from './pinyin.js';\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * PinyinSearchPlugin (#2486) — pinyin recall for `$search`.\n *\n * Pure hook plugin: the `__search` companion column is declared at object\n * compile time by the SchemaRegistry (gated on the SAME\n * `OS_SEARCH_PINYIN_ENABLED` decision point), the engine ORs it into the\n * `$search` filter, and this plugin fills the value:\n *\n *   - before-save hooks: recompute full pinyin + initials of the\n *     display/name field when it changes;\n *   - boot backfill (`kernel:bootstrapped`): fill rows that predate the\n *     switch or arrived via hook-bypassing writes;\n *   - `rebuildSearchCompanion` (exported): explicit reconcile/rebuild entry.\n *\n * When the flag is off the plugin is inert: no hooks, no backfill, and\n * `pinyin-pro` is never imported.\n */\n\n// `IObjectQLEngine` via the core barrel, which re-exports it from\n// `@objectstack/spec/contracts`: this package does not depend on spec directly,\n// and the slot's contract is not a reason to add a dependency.\nimport type { IObjectQLEngine, Plugin, PluginContext } from '@objectstack/core';\nimport { resolveSearchPinyinEnabled } from '@objectstack/types';\nimport {\n  bindSearchCompanionHooks,\n  backfillSearchCompanion,\n} from './companion-projection.js';\n\nexport interface PinyinSearchPluginOptions {\n  /**\n   * Force-enable/disable regardless of `OS_SEARCH_PINYIN_ENABLED` (tests /\n   * embedders). Default: `resolveSearchPinyinEnabled()`.\n   */\n  enabled?: boolean;\n  /** Skip the boot backfill (default: run it once per boot). */\n  backfill?: boolean;\n}\n\nexport class PinyinSearchPlugin implements Plugin {\n  name = 'com.objectstack.plugin.pinyin-search';\n  version = '1.0.0';\n  type = 'standard';\n  dependencies = ['com.objectstack.engine.objectql'];\n\n  private readonly options: PinyinSearchPluginOptions;\n\n  constructor(options: PinyinSearchPluginOptions = {}) {\n    this.options = options;\n  }\n\n  private get enabled(): boolean {\n    return this.options.enabled ?? resolveSearchPinyinEnabled();\n  }\n\n  async init(_ctx: PluginContext): Promise<void> {\n    // Nothing to register: the companion column is provisioned by the\n    // SchemaRegistry's compile-time seam, not injected at runtime.\n  }\n\n  async start(ctx: PluginContext): Promise<void> {\n    if (!this.enabled) {\n      ctx.logger.debug?.('PinyinSearchPlugin: OS_SEARCH_PINYIN_ENABLED is off — inert');\n      return;\n    }\n\n    ctx.hook('kernel:ready', async () => {\n      const engine = this.resolveEngine(ctx);\n      if (!engine) {\n        ctx.logger.warn('PinyinSearchPlugin: no ObjectQL engine — companion hooks NOT bound');\n        return;\n      }\n      try {\n        bindSearchCompanionHooks(engine, ctx.logger as any);\n      } catch (err: any) {\n        ctx.logger.warn('PinyinSearchPlugin: companion hooks not bound', { error: err?.message });\n      }\n    });\n\n    // Backfill AFTER boot settles (`kernel:bootstrapped` fires once every\n    // `kernel:ready` hook — including seed loading — has completed), so\n    // seeded rows written before/around hook binding are reconciled too.\n    if (this.options.backfill !== false) {\n      ctx.hook('kernel:bootstrapped', async () => {\n        const engine = this.resolveEngine(ctx);\n        if (!engine) return;\n        try {\n          await backfillSearchCompanion(engine, ctx.logger as any);\n        } catch (err: any) {\n          ctx.logger.warn('PinyinSearchPlugin: companion backfill failed', { error: err?.message });\n        }\n      });\n    }\n  }\n\n  /**\n   * [#4251 B5] The engine SEEN WHOLE — `bindSearchCompanionHooks` binds\n   * `registerHook`, which lives on `IObjectQLEngine`, not on the data plane.\n   * The ledger records `objectql` as \"the SAME instance as `data`, seen whole\",\n   * so the alias fallback resolves the same object under the same contract.\n   */\n  private resolveEngine(ctx: PluginContext): IObjectQLEngine | null {\n    try {\n      return ctx.getService<IObjectQLEngine>('objectql');\n    } catch {\n      try {\n        return ctx.getService<IObjectQLEngine>('data');\n      } catch {\n        return null;\n      }\n    }\n  }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * `__search` companion-column projection (#2486).\n *\n * The column itself is DECLARED at object compile time by the SchemaRegistry\n * (`provisionSearchCompanion`, gated on `OS_SEARCH_PINYIN_ENABLED`); this\n * module only FILLS the value — the `plugin-sharing` primary-BU projection\n * pattern (column on the object, plugin maintains it via hooks).\n *\n * Write path: global `beforeInsert`/`beforeUpdate` hooks stamp\n * `data.__search` whenever a companion source field (the object's\n * display/name field) is present in the write — i.e. only when the source\n * actually changed, avoiding write amplification. Writes that bypass hooks\n * (bulk import, direct migration) leave the companion empty; the boot\n * backfill and the `rebuildSearchCompanion` reconcile entry cover that.\n */\n\nimport {\n  SEARCH_COMPANION_FIELD,\n  resolveSearchCompanionSources,\n  containsCJK,\n} from '@objectstack/objectql';\nimport { keysetWalk } from '@objectstack/types';\nimport { computeSearchCompanionValue } from './pinyin.js';\n\nconst SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] } as const;\n\nexport const PINYIN_SEARCH_HOOK_PACKAGE = 'plugin-pinyin-search:companion';\n\ninterface MinimalEngine {\n  registerHook(\n    event: string,\n    handler: (ctx: any) => any | Promise<any>,\n    options?: { object?: string | string[]; priority?: number; packageId?: string },\n  ): void;\n  unregisterHooksByPackage(packageId: string): number;\n  find(object: string, query?: any, options?: any): Promise<any[]>;\n  update(object: string, data: any, options?: any): Promise<any>;\n  registry?: {\n    getObject(name: string): any;\n    getAllObjects?(packageId?: string): any[];\n  };\n}\n\ninterface MinimalLogger {\n  info?: (msg: any, ...rest: any[]) => void;\n  warn?: (msg: any, ...rest: any[]) => void;\n  debug?: (msg: any, ...rest: any[]) => void;\n}\n\n/**\n * Stamp `data.__search` on a before-save hook context when a companion source\n * field is part of the write. Recomputes from the NEW value; a non-CJK new\n * value clears the companion (null) so stale pinyin never recalls a renamed\n * record. Never throws — a normalization failure must not fail the write.\n */\nasync function stampCompanion(engine: MinimalEngine, ctx: any, logger?: MinimalLogger): Promise<void> {\n  const object = ctx?.object;\n  if (!object) return;\n  const schema = engine.registry?.getObject?.(object);\n  if (!schema?.fields?.[SEARCH_COMPANION_FIELD]) return;\n\n  const data = ctx?.input?.data;\n  if (!data || typeof data !== 'object' || Array.isArray(data)) return;\n\n  const sources = resolveSearchCompanionSources(schema);\n  if (sources.length === 0) return;\n  const touched = sources.filter((s) => Object.prototype.hasOwnProperty.call(data, s));\n  if (touched.length === 0) return; // source unchanged → no recompute (no write amplification)\n\n  try {\n    data[SEARCH_COMPANION_FIELD] = await computeSearchCompanionValue(sources.map((s) => data[s]));\n  } catch (err: any) {\n    logger?.warn?.('[pinyin-search] companion normalization failed — write proceeds without it', {\n      object,\n      error: err?.message,\n    });\n  }\n}\n\n/**\n * Bind the global before-save hooks that keep `__search` in step. Idempotent\n * (unbinds the package first). Hooks are global (no object filter) with a\n * cheap early-out: objects without a provisioned companion column return\n * immediately. They run for system-context writes too — the projection must\n * stay correct regardless of who writes (seeds, imports, admin UI).\n */\nexport function bindSearchCompanionHooks(engine: MinimalEngine, logger?: MinimalLogger): void {\n  if (typeof engine.registerHook !== 'function') return;\n  if (typeof engine.unregisterHooksByPackage === 'function') {\n    engine.unregisterHooksByPackage(PINYIN_SEARCH_HOOK_PACKAGE);\n  }\n  const opts = { packageId: PINYIN_SEARCH_HOOK_PACKAGE, priority: 150 };\n  const handler = (ctx: any) => stampCompanion(engine, ctx, logger);\n  engine.registerHook('beforeInsert', handler, opts);\n  engine.registerHook('beforeUpdate', handler, opts);\n  logger?.info?.('[pinyin-search] companion hooks bound (beforeInsert/beforeUpdate, all objects)');\n}\n\nexport interface CompanionBackfillOptions {\n  /** Rows fetched per page during the scan. Default 1000. */\n  batchSize?: number;\n  /** Restrict to one object (reconcile entry); default: every provisioned object. */\n  object?: string;\n  /**\n   * Recompute EVERY row's companion, not just missing ones — the periodic\n   * reconcile/rebuild mode. Default false (backfill: only rows whose\n   * companion is empty but whose source has CJK content).\n   */\n  force?: boolean;\n}\n\nexport interface CompanionBackfillResult {\n  objects: number;\n  scanned: number;\n  updated: number;\n}\n\n/**\n * Backfill / reconcile the companion column.\n *\n * Denormalized-on-write columns go stale when writes bypass hooks (bulk\n * import, direct migration) and are empty for rows that predate the switch\n * being enabled. This scans every object that carries the companion column\n * (paged, system context) and fills the gaps; with `force: true` it\n * recomputes unconditionally (the periodic reconcile / rebuild entry).\n * Idempotent; per-row failures are skipped so one bad row never aborts the\n * pass.\n */\nexport async function backfillSearchCompanion(\n  engine: MinimalEngine,\n  logger?: MinimalLogger,\n  options?: CompanionBackfillOptions,\n): Promise<CompanionBackfillResult> {\n  const batchSize = Math.max(1, options?.batchSize ?? 1000);\n  const all = options?.object\n    ? [engine.registry?.getObject?.(options.object)].filter(Boolean)\n    : engine.registry?.getAllObjects?.() ?? [];\n\n  const result: CompanionBackfillResult = { objects: 0, scanned: 0, updated: 0 };\n\n  for (const schema of all) {\n    if (!schema?.name || !schema?.fields?.[SEARCH_COMPANION_FIELD]) continue;\n    const sources = resolveSearchCompanionSources(schema);\n    if (sources.length === 0) continue;\n    result.objects++;\n\n    // Seek by `id` (#4363). This walk UPDATES the rows it reads, and an offset\n    // counts into a set those writes are changing, so rows slide past the\n    // cursor and never get their companion blob — a backfill that reports a\n    // clean pass while leaving records unsearchable.\n    const walk = keysetWalk<any>(\n      (q) => engine.find(schema.name, {\n        ...q,\n        fields: ['id', ...sources, SEARCH_COMPANION_FIELD],\n        context: SYSTEM_CTX,\n      }),\n      { pageSize: batchSize },\n    );\n\n    try {\n      for await (const rows of walk.pages()) {\n      result.scanned += rows.length;\n\n      for (const row of rows) {\n        if (row?.id == null) continue;\n        const hasBlob = typeof row[SEARCH_COMPANION_FIELD] === 'string' && row[SEARCH_COMPANION_FIELD] !== '';\n        const hasCjkSource = sources.some((s) => containsCJK(row[s]));\n        // Backfill mode: touch only rows missing a blob they should have.\n        // Force mode: recompute everything (also clears stale blobs).\n        if (!options?.force && (hasBlob || !hasCjkSource)) continue;\n        try {\n          const value = await computeSearchCompanionValue(sources.map((s) => row[s]));\n          if (!options?.force && value == null) continue;\n          if (value === row[SEARCH_COMPANION_FIELD]) continue;\n          await engine.update(\n            schema.name,\n            { id: row.id, [SEARCH_COMPANION_FIELD]: value },\n            { context: SYSTEM_CTX },\n          );\n          result.updated++;\n        } catch (err: any) {\n          logger?.warn?.('[pinyin-search] backfill row skipped', {\n            object: schema.name,\n            id: row.id,\n            error: err?.message,\n          });\n        }\n      }\n      }\n    } catch (err: any) {\n      logger?.warn?.('[pinyin-search] backfill scan failed', { object: schema.name, error: err?.message });\n      continue;\n    }\n  }\n\n  if (result.updated > 0) {\n    logger?.info?.('[pinyin-search] companion backfill complete', result);\n  }\n  return result;\n}\n\n/**\n * Periodic reconcile / rebuild entry: recompute the companion for every row\n * (optionally one object). Alias for `backfillSearchCompanion` with\n * `force: true` — exposed under its own name so operators/jobs have an\n * explicit \"rebuild the pinyin index\" handle.\n */\nexport function rebuildSearchCompanion(\n  engine: MinimalEngine,\n  logger?: MinimalLogger,\n  options?: Omit<CompanionBackfillOptions, 'force'>,\n): Promise<CompanionBackfillResult> {\n  return backfillSearchCompanion(engine, logger, { ...options, force: true });\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Pinyin normalization for the `__search` companion column (#2486).\n *\n * One normalized blob per record — full pinyin AND initials in the same\n * column — so a single `$contains` recalls every latin input shape:\n *\n *   \"张伟\"  →  \"zhangwei zw\"\n *     `zhang` / `wei` / `zhangwei`  → substring of the full form\n *     `zw`                          → substring of the initials form\n *\n * `pinyin-pro` is loaded lazily on first use: non-Chinese deployments (flag\n * off → hooks never bound) never import it and pay zero cost.\n *\n * Polyphones: pinyin-pro's default heuristics are accepted (issue #2486\n * \"待定\" — surname polyphone dictionaries are a P2 follow-up).\n */\n\nimport { containsCJK } from '@objectstack/objectql';\n\ntype PinyinFn = (text: string, options?: Record<string, unknown>) => string | string[];\n\nlet _pinyin: Promise<PinyinFn> | null = null;\n\n/** Lazy-load `pinyin-pro` (cached module-wide). */\nfunction loadPinyin(): Promise<PinyinFn> {\n  _pinyin ??= import('pinyin-pro').then((m: any) => (m.pinyin ?? m.default?.pinyin) as PinyinFn);\n  return _pinyin;\n}\n\n/** Lowercase and strip everything that is not a latin letter or digit. */\nfunction squash(syllables: string | string[]): string {\n  const joined = Array.isArray(syllables) ? syllables.join('') : String(syllables ?? '');\n  return joined.toLowerCase().replace(/[^a-z0-9]+/g, '');\n}\n\n/**\n * Compute the companion value for the given source-field values.\n *\n * Returns the normalized blob (`\"<full-pinyin> <initials>\"`, deduplicated)\n * when at least one value contains CJK characters, else `null` — a `null`\n * companion means \"nothing pinyin-searchable here\" and clears any stale blob\n * when a name is edited away from CJK. Non-CJK values need no companion:\n * their source column already matches latin input directly.\n */\nexport async function computeSearchCompanionValue(values: ReadonlyArray<unknown>): Promise<string | null> {\n  const cjkValues = values.filter((v): v is string => containsCJK(v));\n  if (cjkValues.length === 0) return null;\n\n  const pinyin = await loadPinyin();\n  const parts: string[] = [];\n  for (const value of cjkValues) {\n    // `nonZh: 'consecutive'` keeps latin/digit runs intact inside mixed\n    // values (\"张伟2号\" → \"zhangwei2hao\"), so mixed names stay one token.\n    const full = squash(pinyin(value, { toneType: 'none', type: 'array', nonZh: 'consecutive' }));\n    const initials = squash(pinyin(value, { pattern: 'first', toneType: 'none', type: 'array', nonZh: 'consecutive' }));\n    if (full) parts.push(full);\n    if (initials && initials !== full) parts.push(initials);\n  }\n  if (parts.length === 0) return null;\n  return [...new Set(parts)].join(' ');\n}\n"],"mappings":"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","names":["import_types","import_objectql"]}

package/dist/index.mjs

@@ -170,6 +170,12 @@ var PinyinSearchPlugin = class {
       });
     }
   }
+  /**
+   * [#4251 B5] The engine SEEN WHOLE — `bindSearchCompanionHooks` binds
+   * `registerHook`, which lives on `IObjectQLEngine`, not on the data plane.
+   * The ledger records `objectql` as "the SAME instance as `data`, seen whole",
+   * so the alias fallback resolves the same object under the same contract.
+   */
   resolveEngine(ctx) {
     try {
       return ctx.getService("objectql");

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/pinyin-search-plugin.ts","../src/companion-projection.ts","../src/pinyin.ts"],"sourcesContent":["// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * PinyinSearchPlugin (#2486) — pinyin recall for `$search`.\n *\n * Pure hook plugin: the `__search` companion column is declared at object\n * compile time by the SchemaRegistry (gated on the SAME\n * `OS_SEARCH_PINYIN_ENABLED` decision point), the engine ORs it into the\n * `$search` filter, and this plugin fills the value:\n *\n *   - before-save hooks: recompute full pinyin + initials of the\n *     display/name field when it changes;\n *   - boot backfill (`kernel:bootstrapped`): fill rows that predate the\n *     switch or arrived via hook-bypassing writes;\n *   - `rebuildSearchCompanion` (exported): explicit reconcile/rebuild entry.\n *\n * When the flag is off the plugin is inert: no hooks, no backfill, and\n * `pinyin-pro` is never imported.\n */\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport { resolveSearchPinyinEnabled } from '@objectstack/types';\nimport {\n  bindSearchCompanionHooks,\n  backfillSearchCompanion,\n} from './companion-projection.js';\n\nexport interface PinyinSearchPluginOptions {\n  /**\n   * Force-enable/disable regardless of `OS_SEARCH_PINYIN_ENABLED` (tests /\n   * embedders). Default: `resolveSearchPinyinEnabled()`.\n   */\n  enabled?: boolean;\n  /** Skip the boot backfill (default: run it once per boot). */\n  backfill?: boolean;\n}\n\nexport class PinyinSearchPlugin implements Plugin {\n  name = 'com.objectstack.plugin.pinyin-search';\n  version = '1.0.0';\n  type = 'standard';\n  dependencies = ['com.objectstack.engine.objectql'];\n\n  private readonly options: PinyinSearchPluginOptions;\n\n  constructor(options: PinyinSearchPluginOptions = {}) {\n    this.options = options;\n  }\n\n  private get enabled(): boolean {\n    return this.options.enabled ?? resolveSearchPinyinEnabled();\n  }\n\n  async init(_ctx: PluginContext): Promise<void> {\n    // Nothing to register: the companion column is provisioned by the\n    // SchemaRegistry's compile-time seam, not injected at runtime.\n  }\n\n  async start(ctx: PluginContext): Promise<void> {\n    if (!this.enabled) {\n      ctx.logger.debug?.('PinyinSearchPlugin: OS_SEARCH_PINYIN_ENABLED is off — inert');\n      return;\n    }\n\n    ctx.hook('kernel:ready', async () => {\n      const engine = this.resolveEngine(ctx);\n      if (!engine) {\n        ctx.logger.warn('PinyinSearchPlugin: no ObjectQL engine — companion hooks NOT bound');\n        return;\n      }\n      try {\n        bindSearchCompanionHooks(engine, ctx.logger as any);\n      } catch (err: any) {\n        ctx.logger.warn('PinyinSearchPlugin: companion hooks not bound', { error: err?.message });\n      }\n    });\n\n    // Backfill AFTER boot settles (`kernel:bootstrapped` fires once every\n    // `kernel:ready` hook — including seed loading — has completed), so\n    // seeded rows written before/around hook binding are reconciled too.\n    if (this.options.backfill !== false) {\n      ctx.hook('kernel:bootstrapped', async () => {\n        const engine = this.resolveEngine(ctx);\n        if (!engine) return;\n        try {\n          await backfillSearchCompanion(engine, ctx.logger as any);\n        } catch (err: any) {\n          ctx.logger.warn('PinyinSearchPlugin: companion backfill failed', { error: err?.message });\n        }\n      });\n    }\n  }\n\n  private resolveEngine(ctx: PluginContext): any {\n    try {\n      return ctx.getService<any>('objectql');\n    } catch {\n      try {\n        return ctx.getService<any>('data');\n      } catch {\n        return null;\n      }\n    }\n  }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * `__search` companion-column projection (#2486).\n *\n * The column itself is DECLARED at object compile time by the SchemaRegistry\n * (`provisionSearchCompanion`, gated on `OS_SEARCH_PINYIN_ENABLED`); this\n * module only FILLS the value — the `plugin-sharing` primary-BU projection\n * pattern (column on the object, plugin maintains it via hooks).\n *\n * Write path: global `beforeInsert`/`beforeUpdate` hooks stamp\n * `data.__search` whenever a companion source field (the object's\n * display/name field) is present in the write — i.e. only when the source\n * actually changed, avoiding write amplification. Writes that bypass hooks\n * (bulk import, direct migration) leave the companion empty; the boot\n * backfill and the `rebuildSearchCompanion` reconcile entry cover that.\n */\n\nimport {\n  SEARCH_COMPANION_FIELD,\n  resolveSearchCompanionSources,\n  containsCJK,\n} from '@objectstack/objectql';\nimport { keysetWalk } from '@objectstack/types';\nimport { computeSearchCompanionValue } from './pinyin.js';\n\nconst SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] } as const;\n\nexport const PINYIN_SEARCH_HOOK_PACKAGE = 'plugin-pinyin-search:companion';\n\ninterface MinimalEngine {\n  registerHook(\n    event: string,\n    handler: (ctx: any) => any | Promise<any>,\n    options?: { object?: string | string[]; priority?: number; packageId?: string },\n  ): void;\n  unregisterHooksByPackage(packageId: string): number;\n  find(object: string, query?: any, options?: any): Promise<any[]>;\n  update(object: string, data: any, options?: any): Promise<any>;\n  registry?: {\n    getObject(name: string): any;\n    getAllObjects?(packageId?: string): any[];\n  };\n}\n\ninterface MinimalLogger {\n  info?: (msg: any, ...rest: any[]) => void;\n  warn?: (msg: any, ...rest: any[]) => void;\n  debug?: (msg: any, ...rest: any[]) => void;\n}\n\n/**\n * Stamp `data.__search` on a before-save hook context when a companion source\n * field is part of the write. Recomputes from the NEW value; a non-CJK new\n * value clears the companion (null) so stale pinyin never recalls a renamed\n * record. Never throws — a normalization failure must not fail the write.\n */\nasync function stampCompanion(engine: MinimalEngine, ctx: any, logger?: MinimalLogger): Promise<void> {\n  const object = ctx?.object;\n  if (!object) return;\n  const schema = engine.registry?.getObject?.(object);\n  if (!schema?.fields?.[SEARCH_COMPANION_FIELD]) return;\n\n  const data = ctx?.input?.data;\n  if (!data || typeof data !== 'object' || Array.isArray(data)) return;\n\n  const sources = resolveSearchCompanionSources(schema);\n  if (sources.length === 0) return;\n  const touched = sources.filter((s) => Object.prototype.hasOwnProperty.call(data, s));\n  if (touched.length === 0) return; // source unchanged → no recompute (no write amplification)\n\n  try {\n    data[SEARCH_COMPANION_FIELD] = await computeSearchCompanionValue(sources.map((s) => data[s]));\n  } catch (err: any) {\n    logger?.warn?.('[pinyin-search] companion normalization failed — write proceeds without it', {\n      object,\n      error: err?.message,\n    });\n  }\n}\n\n/**\n * Bind the global before-save hooks that keep `__search` in step. Idempotent\n * (unbinds the package first). Hooks are global (no object filter) with a\n * cheap early-out: objects without a provisioned companion column return\n * immediately. They run for system-context writes too — the projection must\n * stay correct regardless of who writes (seeds, imports, admin UI).\n */\nexport function bindSearchCompanionHooks(engine: MinimalEngine, logger?: MinimalLogger): void {\n  if (typeof engine.registerHook !== 'function') return;\n  if (typeof engine.unregisterHooksByPackage === 'function') {\n    engine.unregisterHooksByPackage(PINYIN_SEARCH_HOOK_PACKAGE);\n  }\n  const opts = { packageId: PINYIN_SEARCH_HOOK_PACKAGE, priority: 150 };\n  const handler = (ctx: any) => stampCompanion(engine, ctx, logger);\n  engine.registerHook('beforeInsert', handler, opts);\n  engine.registerHook('beforeUpdate', handler, opts);\n  logger?.info?.('[pinyin-search] companion hooks bound (beforeInsert/beforeUpdate, all objects)');\n}\n\nexport interface CompanionBackfillOptions {\n  /** Rows fetched per page during the scan. Default 1000. */\n  batchSize?: number;\n  /** Restrict to one object (reconcile entry); default: every provisioned object. */\n  object?: string;\n  /**\n   * Recompute EVERY row's companion, not just missing ones — the periodic\n   * reconcile/rebuild mode. Default false (backfill: only rows whose\n   * companion is empty but whose source has CJK content).\n   */\n  force?: boolean;\n}\n\nexport interface CompanionBackfillResult {\n  objects: number;\n  scanned: number;\n  updated: number;\n}\n\n/**\n * Backfill / reconcile the companion column.\n *\n * Denormalized-on-write columns go stale when writes bypass hooks (bulk\n * import, direct migration) and are empty for rows that predate the switch\n * being enabled. This scans every object that carries the companion column\n * (paged, system context) and fills the gaps; with `force: true` it\n * recomputes unconditionally (the periodic reconcile / rebuild entry).\n * Idempotent; per-row failures are skipped so one bad row never aborts the\n * pass.\n */\nexport async function backfillSearchCompanion(\n  engine: MinimalEngine,\n  logger?: MinimalLogger,\n  options?: CompanionBackfillOptions,\n): Promise<CompanionBackfillResult> {\n  const batchSize = Math.max(1, options?.batchSize ?? 1000);\n  const all = options?.object\n    ? [engine.registry?.getObject?.(options.object)].filter(Boolean)\n    : engine.registry?.getAllObjects?.() ?? [];\n\n  const result: CompanionBackfillResult = { objects: 0, scanned: 0, updated: 0 };\n\n  for (const schema of all) {\n    if (!schema?.name || !schema?.fields?.[SEARCH_COMPANION_FIELD]) continue;\n    const sources = resolveSearchCompanionSources(schema);\n    if (sources.length === 0) continue;\n    result.objects++;\n\n    // Seek by `id` (#4363). This walk UPDATES the rows it reads, and an offset\n    // counts into a set those writes are changing, so rows slide past the\n    // cursor and never get their companion blob — a backfill that reports a\n    // clean pass while leaving records unsearchable.\n    const walk = keysetWalk<any>(\n      (q) => engine.find(schema.name, {\n        ...q,\n        fields: ['id', ...sources, SEARCH_COMPANION_FIELD],\n        context: SYSTEM_CTX,\n      }),\n      { pageSize: batchSize },\n    );\n\n    try {\n      for await (const rows of walk.pages()) {\n      result.scanned += rows.length;\n\n      for (const row of rows) {\n        if (row?.id == null) continue;\n        const hasBlob = typeof row[SEARCH_COMPANION_FIELD] === 'string' && row[SEARCH_COMPANION_FIELD] !== '';\n        const hasCjkSource = sources.some((s) => containsCJK(row[s]));\n        // Backfill mode: touch only rows missing a blob they should have.\n        // Force mode: recompute everything (also clears stale blobs).\n        if (!options?.force && (hasBlob || !hasCjkSource)) continue;\n        try {\n          const value = await computeSearchCompanionValue(sources.map((s) => row[s]));\n          if (!options?.force && value == null) continue;\n          if (value === row[SEARCH_COMPANION_FIELD]) continue;\n          await engine.update(\n            schema.name,\n            { id: row.id, [SEARCH_COMPANION_FIELD]: value },\n            { context: SYSTEM_CTX },\n          );\n          result.updated++;\n        } catch (err: any) {\n          logger?.warn?.('[pinyin-search] backfill row skipped', {\n            object: schema.name,\n            id: row.id,\n            error: err?.message,\n          });\n        }\n      }\n      }\n    } catch (err: any) {\n      logger?.warn?.('[pinyin-search] backfill scan failed', { object: schema.name, error: err?.message });\n      continue;\n    }\n  }\n\n  if (result.updated > 0) {\n    logger?.info?.('[pinyin-search] companion backfill complete', result);\n  }\n  return result;\n}\n\n/**\n * Periodic reconcile / rebuild entry: recompute the companion for every row\n * (optionally one object). Alias for `backfillSearchCompanion` with\n * `force: true` — exposed under its own name so operators/jobs have an\n * explicit \"rebuild the pinyin index\" handle.\n */\nexport function rebuildSearchCompanion(\n  engine: MinimalEngine,\n  logger?: MinimalLogger,\n  options?: Omit<CompanionBackfillOptions, 'force'>,\n): Promise<CompanionBackfillResult> {\n  return backfillSearchCompanion(engine, logger, { ...options, force: true });\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Pinyin normalization for the `__search` companion column (#2486).\n *\n * One normalized blob per record — full pinyin AND initials in the same\n * column — so a single `$contains` recalls every latin input shape:\n *\n *   \"张伟\"  →  \"zhangwei zw\"\n *     `zhang` / `wei` / `zhangwei`  → substring of the full form\n *     `zw`                          → substring of the initials form\n *\n * `pinyin-pro` is loaded lazily on first use: non-Chinese deployments (flag\n * off → hooks never bound) never import it and pay zero cost.\n *\n * Polyphones: pinyin-pro's default heuristics are accepted (issue #2486\n * \"待定\" — surname polyphone dictionaries are a P2 follow-up).\n */\n\nimport { containsCJK } from '@objectstack/objectql';\n\ntype PinyinFn = (text: string, options?: Record<string, unknown>) => string | string[];\n\nlet _pinyin: Promise<PinyinFn> | null = null;\n\n/** Lazy-load `pinyin-pro` (cached module-wide). */\nfunction loadPinyin(): Promise<PinyinFn> {\n  _pinyin ??= import('pinyin-pro').then((m: any) => (m.pinyin ?? m.default?.pinyin) as PinyinFn);\n  return _pinyin;\n}\n\n/** Lowercase and strip everything that is not a latin letter or digit. */\nfunction squash(syllables: string | string[]): string {\n  const joined = Array.isArray(syllables) ? syllables.join('') : String(syllables ?? '');\n  return joined.toLowerCase().replace(/[^a-z0-9]+/g, '');\n}\n\n/**\n * Compute the companion value for the given source-field values.\n *\n * Returns the normalized blob (`\"<full-pinyin> <initials>\"`, deduplicated)\n * when at least one value contains CJK characters, else `null` — a `null`\n * companion means \"nothing pinyin-searchable here\" and clears any stale blob\n * when a name is edited away from CJK. Non-CJK values need no companion:\n * their source column already matches latin input directly.\n */\nexport async function computeSearchCompanionValue(values: ReadonlyArray<unknown>): Promise<string | null> {\n  const cjkValues = values.filter((v): v is string => containsCJK(v));\n  if (cjkValues.length === 0) return null;\n\n  const pinyin = await loadPinyin();\n  const parts: string[] = [];\n  for (const value of cjkValues) {\n    // `nonZh: 'consecutive'` keeps latin/digit runs intact inside mixed\n    // values (\"张伟2号\" → \"zhangwei2hao\"), so mixed names stay one token.\n    const full = squash(pinyin(value, { toneType: 'none', type: 'array', nonZh: 'consecutive' }));\n    const initials = squash(pinyin(value, { pattern: 'first', toneType: 'none', type: 'array', nonZh: 'consecutive' }));\n    if (full) parts.push(full);\n    if (initials && initials !== full) parts.push(initials);\n  }\n  if (parts.length === 0) return null;\n  return [...new Set(parts)].join(' ');\n}\n"],"mappings":"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","names":["containsCJK","containsCJK"]}
+{"version":3,"sources":["../src/pinyin-search-plugin.ts","../src/companion-projection.ts","../src/pinyin.ts"],"sourcesContent":["// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * PinyinSearchPlugin (#2486) — pinyin recall for `$search`.\n *\n * Pure hook plugin: the `__search` companion column is declared at object\n * compile time by the SchemaRegistry (gated on the SAME\n * `OS_SEARCH_PINYIN_ENABLED` decision point), the engine ORs it into the\n * `$search` filter, and this plugin fills the value:\n *\n *   - before-save hooks: recompute full pinyin + initials of the\n *     display/name field when it changes;\n *   - boot backfill (`kernel:bootstrapped`): fill rows that predate the\n *     switch or arrived via hook-bypassing writes;\n *   - `rebuildSearchCompanion` (exported): explicit reconcile/rebuild entry.\n *\n * When the flag is off the plugin is inert: no hooks, no backfill, and\n * `pinyin-pro` is never imported.\n */\n\n// `IObjectQLEngine` via the core barrel, which re-exports it from\n// `@objectstack/spec/contracts`: this package does not depend on spec directly,\n// and the slot's contract is not a reason to add a dependency.\nimport type { IObjectQLEngine, Plugin, PluginContext } from '@objectstack/core';\nimport { resolveSearchPinyinEnabled } from '@objectstack/types';\nimport {\n  bindSearchCompanionHooks,\n  backfillSearchCompanion,\n} from './companion-projection.js';\n\nexport interface PinyinSearchPluginOptions {\n  /**\n   * Force-enable/disable regardless of `OS_SEARCH_PINYIN_ENABLED` (tests /\n   * embedders). Default: `resolveSearchPinyinEnabled()`.\n   */\n  enabled?: boolean;\n  /** Skip the boot backfill (default: run it once per boot). */\n  backfill?: boolean;\n}\n\nexport class PinyinSearchPlugin implements Plugin {\n  name = 'com.objectstack.plugin.pinyin-search';\n  version = '1.0.0';\n  type = 'standard';\n  dependencies = ['com.objectstack.engine.objectql'];\n\n  private readonly options: PinyinSearchPluginOptions;\n\n  constructor(options: PinyinSearchPluginOptions = {}) {\n    this.options = options;\n  }\n\n  private get enabled(): boolean {\n    return this.options.enabled ?? resolveSearchPinyinEnabled();\n  }\n\n  async init(_ctx: PluginContext): Promise<void> {\n    // Nothing to register: the companion column is provisioned by the\n    // SchemaRegistry's compile-time seam, not injected at runtime.\n  }\n\n  async start(ctx: PluginContext): Promise<void> {\n    if (!this.enabled) {\n      ctx.logger.debug?.('PinyinSearchPlugin: OS_SEARCH_PINYIN_ENABLED is off — inert');\n      return;\n    }\n\n    ctx.hook('kernel:ready', async () => {\n      const engine = this.resolveEngine(ctx);\n      if (!engine) {\n        ctx.logger.warn('PinyinSearchPlugin: no ObjectQL engine — companion hooks NOT bound');\n        return;\n      }\n      try {\n        bindSearchCompanionHooks(engine, ctx.logger as any);\n      } catch (err: any) {\n        ctx.logger.warn('PinyinSearchPlugin: companion hooks not bound', { error: err?.message });\n      }\n    });\n\n    // Backfill AFTER boot settles (`kernel:bootstrapped` fires once every\n    // `kernel:ready` hook — including seed loading — has completed), so\n    // seeded rows written before/around hook binding are reconciled too.\n    if (this.options.backfill !== false) {\n      ctx.hook('kernel:bootstrapped', async () => {\n        const engine = this.resolveEngine(ctx);\n        if (!engine) return;\n        try {\n          await backfillSearchCompanion(engine, ctx.logger as any);\n        } catch (err: any) {\n          ctx.logger.warn('PinyinSearchPlugin: companion backfill failed', { error: err?.message });\n        }\n      });\n    }\n  }\n\n  /**\n   * [#4251 B5] The engine SEEN WHOLE — `bindSearchCompanionHooks` binds\n   * `registerHook`, which lives on `IObjectQLEngine`, not on the data plane.\n   * The ledger records `objectql` as \"the SAME instance as `data`, seen whole\",\n   * so the alias fallback resolves the same object under the same contract.\n   */\n  private resolveEngine(ctx: PluginContext): IObjectQLEngine | null {\n    try {\n      return ctx.getService<IObjectQLEngine>('objectql');\n    } catch {\n      try {\n        return ctx.getService<IObjectQLEngine>('data');\n      } catch {\n        return null;\n      }\n    }\n  }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * `__search` companion-column projection (#2486).\n *\n * The column itself is DECLARED at object compile time by the SchemaRegistry\n * (`provisionSearchCompanion`, gated on `OS_SEARCH_PINYIN_ENABLED`); this\n * module only FILLS the value — the `plugin-sharing` primary-BU projection\n * pattern (column on the object, plugin maintains it via hooks).\n *\n * Write path: global `beforeInsert`/`beforeUpdate` hooks stamp\n * `data.__search` whenever a companion source field (the object's\n * display/name field) is present in the write — i.e. only when the source\n * actually changed, avoiding write amplification. Writes that bypass hooks\n * (bulk import, direct migration) leave the companion empty; the boot\n * backfill and the `rebuildSearchCompanion` reconcile entry cover that.\n */\n\nimport {\n  SEARCH_COMPANION_FIELD,\n  resolveSearchCompanionSources,\n  containsCJK,\n} from '@objectstack/objectql';\nimport { keysetWalk } from '@objectstack/types';\nimport { computeSearchCompanionValue } from './pinyin.js';\n\nconst SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] } as const;\n\nexport const PINYIN_SEARCH_HOOK_PACKAGE = 'plugin-pinyin-search:companion';\n\ninterface MinimalEngine {\n  registerHook(\n    event: string,\n    handler: (ctx: any) => any | Promise<any>,\n    options?: { object?: string | string[]; priority?: number; packageId?: string },\n  ): void;\n  unregisterHooksByPackage(packageId: string): number;\n  find(object: string, query?: any, options?: any): Promise<any[]>;\n  update(object: string, data: any, options?: any): Promise<any>;\n  registry?: {\n    getObject(name: string): any;\n    getAllObjects?(packageId?: string): any[];\n  };\n}\n\ninterface MinimalLogger {\n  info?: (msg: any, ...rest: any[]) => void;\n  warn?: (msg: any, ...rest: any[]) => void;\n  debug?: (msg: any, ...rest: any[]) => void;\n}\n\n/**\n * Stamp `data.__search` on a before-save hook context when a companion source\n * field is part of the write. Recomputes from the NEW value; a non-CJK new\n * value clears the companion (null) so stale pinyin never recalls a renamed\n * record. Never throws — a normalization failure must not fail the write.\n */\nasync function stampCompanion(engine: MinimalEngine, ctx: any, logger?: MinimalLogger): Promise<void> {\n  const object = ctx?.object;\n  if (!object) return;\n  const schema = engine.registry?.getObject?.(object);\n  if (!schema?.fields?.[SEARCH_COMPANION_FIELD]) return;\n\n  const data = ctx?.input?.data;\n  if (!data || typeof data !== 'object' || Array.isArray(data)) return;\n\n  const sources = resolveSearchCompanionSources(schema);\n  if (sources.length === 0) return;\n  const touched = sources.filter((s) => Object.prototype.hasOwnProperty.call(data, s));\n  if (touched.length === 0) return; // source unchanged → no recompute (no write amplification)\n\n  try {\n    data[SEARCH_COMPANION_FIELD] = await computeSearchCompanionValue(sources.map((s) => data[s]));\n  } catch (err: any) {\n    logger?.warn?.('[pinyin-search] companion normalization failed — write proceeds without it', {\n      object,\n      error: err?.message,\n    });\n  }\n}\n\n/**\n * Bind the global before-save hooks that keep `__search` in step. Idempotent\n * (unbinds the package first). Hooks are global (no object filter) with a\n * cheap early-out: objects without a provisioned companion column return\n * immediately. They run for system-context writes too — the projection must\n * stay correct regardless of who writes (seeds, imports, admin UI).\n */\nexport function bindSearchCompanionHooks(engine: MinimalEngine, logger?: MinimalLogger): void {\n  if (typeof engine.registerHook !== 'function') return;\n  if (typeof engine.unregisterHooksByPackage === 'function') {\n    engine.unregisterHooksByPackage(PINYIN_SEARCH_HOOK_PACKAGE);\n  }\n  const opts = { packageId: PINYIN_SEARCH_HOOK_PACKAGE, priority: 150 };\n  const handler = (ctx: any) => stampCompanion(engine, ctx, logger);\n  engine.registerHook('beforeInsert', handler, opts);\n  engine.registerHook('beforeUpdate', handler, opts);\n  logger?.info?.('[pinyin-search] companion hooks bound (beforeInsert/beforeUpdate, all objects)');\n}\n\nexport interface CompanionBackfillOptions {\n  /** Rows fetched per page during the scan. Default 1000. */\n  batchSize?: number;\n  /** Restrict to one object (reconcile entry); default: every provisioned object. */\n  object?: string;\n  /**\n   * Recompute EVERY row's companion, not just missing ones — the periodic\n   * reconcile/rebuild mode. Default false (backfill: only rows whose\n   * companion is empty but whose source has CJK content).\n   */\n  force?: boolean;\n}\n\nexport interface CompanionBackfillResult {\n  objects: number;\n  scanned: number;\n  updated: number;\n}\n\n/**\n * Backfill / reconcile the companion column.\n *\n * Denormalized-on-write columns go stale when writes bypass hooks (bulk\n * import, direct migration) and are empty for rows that predate the switch\n * being enabled. This scans every object that carries the companion column\n * (paged, system context) and fills the gaps; with `force: true` it\n * recomputes unconditionally (the periodic reconcile / rebuild entry).\n * Idempotent; per-row failures are skipped so one bad row never aborts the\n * pass.\n */\nexport async function backfillSearchCompanion(\n  engine: MinimalEngine,\n  logger?: MinimalLogger,\n  options?: CompanionBackfillOptions,\n): Promise<CompanionBackfillResult> {\n  const batchSize = Math.max(1, options?.batchSize ?? 1000);\n  const all = options?.object\n    ? [engine.registry?.getObject?.(options.object)].filter(Boolean)\n    : engine.registry?.getAllObjects?.() ?? [];\n\n  const result: CompanionBackfillResult = { objects: 0, scanned: 0, updated: 0 };\n\n  for (const schema of all) {\n    if (!schema?.name || !schema?.fields?.[SEARCH_COMPANION_FIELD]) continue;\n    const sources = resolveSearchCompanionSources(schema);\n    if (sources.length === 0) continue;\n    result.objects++;\n\n    // Seek by `id` (#4363). This walk UPDATES the rows it reads, and an offset\n    // counts into a set those writes are changing, so rows slide past the\n    // cursor and never get their companion blob — a backfill that reports a\n    // clean pass while leaving records unsearchable.\n    const walk = keysetWalk<any>(\n      (q) => engine.find(schema.name, {\n        ...q,\n        fields: ['id', ...sources, SEARCH_COMPANION_FIELD],\n        context: SYSTEM_CTX,\n      }),\n      { pageSize: batchSize },\n    );\n\n    try {\n      for await (const rows of walk.pages()) {\n      result.scanned += rows.length;\n\n      for (const row of rows) {\n        if (row?.id == null) continue;\n        const hasBlob = typeof row[SEARCH_COMPANION_FIELD] === 'string' && row[SEARCH_COMPANION_FIELD] !== '';\n        const hasCjkSource = sources.some((s) => containsCJK(row[s]));\n        // Backfill mode: touch only rows missing a blob they should have.\n        // Force mode: recompute everything (also clears stale blobs).\n        if (!options?.force && (hasBlob || !hasCjkSource)) continue;\n        try {\n          const value = await computeSearchCompanionValue(sources.map((s) => row[s]));\n          if (!options?.force && value == null) continue;\n          if (value === row[SEARCH_COMPANION_FIELD]) continue;\n          await engine.update(\n            schema.name,\n            { id: row.id, [SEARCH_COMPANION_FIELD]: value },\n            { context: SYSTEM_CTX },\n          );\n          result.updated++;\n        } catch (err: any) {\n          logger?.warn?.('[pinyin-search] backfill row skipped', {\n            object: schema.name,\n            id: row.id,\n            error: err?.message,\n          });\n        }\n      }\n      }\n    } catch (err: any) {\n      logger?.warn?.('[pinyin-search] backfill scan failed', { object: schema.name, error: err?.message });\n      continue;\n    }\n  }\n\n  if (result.updated > 0) {\n    logger?.info?.('[pinyin-search] companion backfill complete', result);\n  }\n  return result;\n}\n\n/**\n * Periodic reconcile / rebuild entry: recompute the companion for every row\n * (optionally one object). Alias for `backfillSearchCompanion` with\n * `force: true` — exposed under its own name so operators/jobs have an\n * explicit \"rebuild the pinyin index\" handle.\n */\nexport function rebuildSearchCompanion(\n  engine: MinimalEngine,\n  logger?: MinimalLogger,\n  options?: Omit<CompanionBackfillOptions, 'force'>,\n): Promise<CompanionBackfillResult> {\n  return backfillSearchCompanion(engine, logger, { ...options, force: true });\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Pinyin normalization for the `__search` companion column (#2486).\n *\n * One normalized blob per record — full pinyin AND initials in the same\n * column — so a single `$contains` recalls every latin input shape:\n *\n *   \"张伟\"  →  \"zhangwei zw\"\n *     `zhang` / `wei` / `zhangwei`  → substring of the full form\n *     `zw`                          → substring of the initials form\n *\n * `pinyin-pro` is loaded lazily on first use: non-Chinese deployments (flag\n * off → hooks never bound) never import it and pay zero cost.\n *\n * Polyphones: pinyin-pro's default heuristics are accepted (issue #2486\n * \"待定\" — surname polyphone dictionaries are a P2 follow-up).\n */\n\nimport { containsCJK } from '@objectstack/objectql';\n\ntype PinyinFn = (text: string, options?: Record<string, unknown>) => string | string[];\n\nlet _pinyin: Promise<PinyinFn> | null = null;\n\n/** Lazy-load `pinyin-pro` (cached module-wide). */\nfunction loadPinyin(): Promise<PinyinFn> {\n  _pinyin ??= import('pinyin-pro').then((m: any) => (m.pinyin ?? m.default?.pinyin) as PinyinFn);\n  return _pinyin;\n}\n\n/** Lowercase and strip everything that is not a latin letter or digit. */\nfunction squash(syllables: string | string[]): string {\n  const joined = Array.isArray(syllables) ? syllables.join('') : String(syllables ?? '');\n  return joined.toLowerCase().replace(/[^a-z0-9]+/g, '');\n}\n\n/**\n * Compute the companion value for the given source-field values.\n *\n * Returns the normalized blob (`\"<full-pinyin> <initials>\"`, deduplicated)\n * when at least one value contains CJK characters, else `null` — a `null`\n * companion means \"nothing pinyin-searchable here\" and clears any stale blob\n * when a name is edited away from CJK. Non-CJK values need no companion:\n * their source column already matches latin input directly.\n */\nexport async function computeSearchCompanionValue(values: ReadonlyArray<unknown>): Promise<string | null> {\n  const cjkValues = values.filter((v): v is string => containsCJK(v));\n  if (cjkValues.length === 0) return null;\n\n  const pinyin = await loadPinyin();\n  const parts: string[] = [];\n  for (const value of cjkValues) {\n    // `nonZh: 'consecutive'` keeps latin/digit runs intact inside mixed\n    // values (\"张伟2号\" → \"zhangwei2hao\"), so mixed names stay one token.\n    const full = squash(pinyin(value, { toneType: 'none', type: 'array', nonZh: 'consecutive' }));\n    const initials = squash(pinyin(value, { pattern: 'first', toneType: 'none', type: 'array', nonZh: 'consecutive' }));\n    if (full) parts.push(full);\n    if (initials && initials !== full) parts.push(initials);\n  }\n  if (parts.length === 0) return null;\n  return [...new Set(parts)].join(' ');\n}\n"],"mappings":"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","names":["containsCJK","containsCJK"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/plugin-pinyin-search",
-  "version": "17.0.0-rc.4",
+  "version": "17.0.0-rc.6",
   "license": "Apache-2.0",
   "description": "Pinyin search recall for ObjectStack — populates the hidden `__search` companion column (full pinyin + initials of the display/name field) so `$search` hits CJK names typed as pinyin. Locale-gated via OS_SEARCH_PINYIN_ENABLED (#2486).",
   "main": "dist/index.js",
@@ -14,9 +14,9 @@
   },
   "dependencies": {
     "pinyin-pro": "^3.28.2",
-    "@objectstack/core": "17.0.0-rc.4",
-    "@objectstack/objectql": "17.0.0-rc.4",
-    "@objectstack/types": "17.0.0-rc.4"
+    "@objectstack/core": "17.0.0-rc.6",
+    "@objectstack/objectql": "17.0.0-rc.6",
+    "@objectstack/types": "17.0.0-rc.6"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",