@objectstack/plugin-pinyin-search 16.1.0 → 17.0.0-rc.1

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 { 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    let offset = 0;\n    for (;;) {\n      let rows: any[] = [];\n      try {\n        rows = await engine.find(schema.name, {\n          fields: ['id', ...sources, SEARCH_COMPANION_FIELD],\n          limit: batchSize,\n          offset,\n          context: SYSTEM_CTX,\n        });\n      } catch (err: any) {\n        logger?.warn?.('[pinyin-search] backfill scan failed', { object: schema.name, error: err?.message });\n        break;\n      }\n      if (!rows?.length) break;\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      if (rows.length < batchSize) break;\n      offset += batchSize;\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\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"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/plugin-pinyin-search",
-  "version": "16.1.0",
+  "version": "17.0.0-rc.1",
   "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",
@@ -13,10 +13,10 @@
     }
   },
   "dependencies": {
-    "pinyin-pro": "^3.28.1",
-    "@objectstack/core": "16.1.0",
-    "@objectstack/objectql": "16.1.0",
-    "@objectstack/types": "16.1.0"
+    "pinyin-pro": "^3.28.2",
+    "@objectstack/core": "17.0.0-rc.1",
+    "@objectstack/objectql": "17.0.0-rc.1",
+    "@objectstack/types": "17.0.0-rc.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",
@@ -30,8 +30,14 @@
     "pinyin",
     "i18n"
   ],
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "scripts": {
     "build": "tsup --config ../../../tsup.config.ts",
-    "test": "vitest run --passWithNoTests"
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
   }
 }

package/.turbo/turbo-build.log

@@ -1,22 +0,0 @@
-
-> @objectstack/plugin-pinyin-search@16.1.0 build /home/runner/work/objectstack/objectstack/packages/plugins/plugin-pinyin-search
-> tsup --config ../../../tsup.config.ts
-
-CLI Building entry: src/index.ts
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.5.1
-CLI Using tsup config: /home/runner/work/objectstack/objectstack/tsup.config.ts
-CLI Target: es2020
-CLI Cleaning output folder
-ESM Build start
-CJS Build start
-CJS dist/index.js     8.92 KB
-CJS dist/index.js.map 19.68 KB
-CJS ⚡️ Build success in 84ms
-ESM dist/index.mjs     6.88 KB
-ESM dist/index.mjs.map 19.09 KB
-ESM ⚡️ Build success in 85ms
-DTS Build start
-DTS ⚡️ Build success in 10824ms
-DTS dist/index.d.mts 5.12 KB
-DTS dist/index.d.ts  5.12 KB

package/src/companion-projection.test.ts

@@ -1,168 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * #2486 — companion projection: before-save stamping, no-write-amplification
- * guard, backfill and rebuild reconcile. Uses a minimal fake engine (the
- * boot-backfill.test.ts pattern) with a stub registry.
- */
-
-import { describe, it, expect, beforeEach } from 'vitest';
-import {
-  bindSearchCompanionHooks,
-  backfillSearchCompanion,
-  rebuildSearchCompanion,
-  PINYIN_SEARCH_HOOK_PACKAGE,
-} from './companion-projection.js';
-
-interface Row { [k: string]: any }
-
-const contactSchema = {
-  name: 'crm_contact',
-  nameField: 'name',
-  fields: {
-    name: { type: 'text' },
-    email: { type: 'email' },
-    __search: { type: 'text', hidden: true, readonly: true, system: true },
-  },
-};
-
-const plainSchema = {
-  name: 'crm_note',
-  fields: { title: { type: 'text' } }, // no companion provisioned
-};
-
-function makeEngine(schemas: any[]) {
-  const tables: Record<string, Row[]> = {};
-  const hooks: Record<string, Array<{ handler: (ctx: any) => any; opts: any }>> = {};
-  const byName = new Map(schemas.map((s) => [s.name, s]));
-  const engine = {
-    _tables: tables,
-    registry: {
-      getObject: (n: string) => byName.get(n),
-      getAllObjects: () => [...byName.values()],
-    },
-    registerHook(event: string, handler: any, opts?: any) {
-      (hooks[event] ??= []).push({ handler, opts });
-    },
-    unregisterHooksByPackage(packageId: string) {
-      let removed = 0;
-      for (const [event, entries] of Object.entries(hooks)) {
-        const kept = entries.filter((e) => e.opts?.packageId !== packageId);
-        removed += entries.length - kept.length;
-        hooks[event] = kept;
-      }
-      return removed;
-    },
-    async trigger(event: string, ctx: any) {
-      for (const { handler } of hooks[event] ?? []) await handler(ctx);
-    },
-    async find(o: string, opts?: any) {
-      const rows = tables[o] ?? [];
-      const offset = opts?.offset ?? 0;
-      return rows.slice(offset, offset + (opts?.limit ?? rows.length));
-    },
-    async insert(o: string, data: Row) {
-      const ctx = { object: o, event: 'beforeInsert', input: { data } };
-      await engine.trigger('beforeInsert', ctx);
-      (tables[o] ??= []).push({ ...ctx.input.data });
-      return ctx.input.data;
-    },
-    async update(o: string, data: Row) {
-      const ctx = { object: o, event: 'beforeUpdate', input: { id: data.id, data } };
-      await engine.trigger('beforeUpdate', ctx);
-      const t = tables[o] ?? [];
-      const i = t.findIndex((r) => r.id === data.id);
-      if (i >= 0) t[i] = { ...t[i], ...ctx.input.data };
-      return t[i];
-    },
-    _hooks: hooks,
-  };
-  return engine;
-}
-
-describe('bindSearchCompanionHooks', () => {
-  let engine: ReturnType<typeof makeEngine>;
-
-  beforeEach(() => {
-    engine = makeEngine([contactSchema, plainSchema]);
-    bindSearchCompanionHooks(engine as any);
-  });
-
-  it('binds beforeInsert + beforeUpdate globally and is idempotent (rebind-safe)', () => {
-    bindSearchCompanionHooks(engine as any); // rebind
-    expect(engine._hooks.beforeInsert).toHaveLength(1);
-    expect(engine._hooks.beforeUpdate).toHaveLength(1);
-    expect(engine._hooks.beforeInsert[0].opts.packageId).toBe(PINYIN_SEARCH_HOOK_PACKAGE);
-    expect(engine._hooks.beforeInsert[0].opts.object).toBeUndefined(); // global
-  });
-
-  it('stamps __search on insert when the name field carries CJK', async () => {
-    const row = await engine.insert('crm_contact', { id: 'c1', name: '张伟' });
-    expect(row.__search).toBe('zhangwei zw');
-  });
-
-  it('leaves __search null for latin names (source column already matches)', async () => {
-    const row = await engine.insert('crm_contact', { id: 'c2', name: 'Ada Lovelace' });
-    expect(row.__search).toBe(null);
-  });
-
-  it('recomputes on update ONLY when the source field is in the patch', async () => {
-    await engine.insert('crm_contact', { id: 'c3', name: '张伟' });
-    // email-only patch: no recompute, no companion key added
-    const patch: Row = { id: 'c3', email: 'zw@example.com' };
-    await engine.update('crm_contact', patch);
-    expect('__search' in patch).toBe(false);
-    // name patch: recompute
-    const updated = await engine.update('crm_contact', { id: 'c3', name: '王芳' });
-    expect(updated.__search).toBe('wangfang wf');
-  });
-
-  it('clears the companion when a CJK name is renamed to latin (no stale recall)', async () => {
-    await engine.insert('crm_contact', { id: 'c4', name: '张伟' });
-    const updated = await engine.update('crm_contact', { id: 'c4', name: 'Victor Zhang' });
-    expect(updated.__search).toBe(null);
-  });
-
-  it('ignores objects without a provisioned companion column', async () => {
-    const row = await engine.insert('crm_note', { id: 'n1', title: '会议纪要' });
-    expect('__search' in row).toBe(false);
-  });
-});
-
-describe('backfillSearchCompanion / rebuildSearchCompanion', () => {
-  it('fills rows missing a blob, in pages, and skips rows that need none', async () => {
-    const engine = makeEngine([contactSchema]);
-    engine._tables.crm_contact = [
-      { id: 'a', name: '张伟', __search: null },            // hook-bypassing write → fill
-      { id: 'b', name: 'Ada', __search: null },              // latin → skip
-      { id: 'c', name: '王芳', __search: 'wangfang wf' },    // already filled → skip
-      { id: 'd', name: '李雷', __search: null },             // fill (second page)
-    ];
-    const result = await backfillSearchCompanion(engine as any, undefined, { batchSize: 2 });
-    expect(result).toEqual({ objects: 1, scanned: 4, updated: 2 });
-    const rows = engine._tables.crm_contact;
-    expect(rows.find((r) => r.id === 'a')!.__search).toBe('zhangwei zw');
-    expect(rows.find((r) => r.id === 'b')!.__search).toBe(null);
-    expect(rows.find((r) => r.id === 'd')!.__search).toBe('lilei ll');
-  });
-
-  it('is idempotent — a second pass updates nothing', async () => {
-    const engine = makeEngine([contactSchema]);
-    engine._tables.crm_contact = [{ id: 'a', name: '张伟', __search: null }];
-    await backfillSearchCompanion(engine as any);
-    const second = await backfillSearchCompanion(engine as any);
-    expect(second.updated).toBe(0);
-  });
-
-  it('rebuild recomputes everything, clearing stale blobs (reconcile entry)', async () => {
-    const engine = makeEngine([contactSchema]);
-    engine._tables.crm_contact = [
-      { id: 'a', name: 'Renamed To Latin', __search: 'zhangwei zw' }, // stale → cleared
-      { id: 'b', name: '王芳', __search: 'wrongblob' },               // wrong → recomputed
-    ];
-    const result = await rebuildSearchCompanion(engine as any);
-    expect(result.updated).toBe(2);
-    expect(engine._tables.crm_contact[0].__search).toBe(null);
-    expect(engine._tables.crm_contact[1].__search).toBe('wangfang wf');
-  });
-});

package/src/companion-projection.ts

@@ -1,214 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * `__search` companion-column projection (#2486).
- *
- * The column itself is DECLARED at object compile time by the SchemaRegistry
- * (`provisionSearchCompanion`, gated on `OS_SEARCH_PINYIN_ENABLED`); this
- * module only FILLS the value — the `plugin-sharing` primary-BU projection
- * pattern (column on the object, plugin maintains it via hooks).
- *
- * Write path: global `beforeInsert`/`beforeUpdate` hooks stamp
- * `data.__search` whenever a companion source field (the object's
- * display/name field) is present in the write — i.e. only when the source
- * actually changed, avoiding write amplification. Writes that bypass hooks
- * (bulk import, direct migration) leave the companion empty; the boot
- * backfill and the `rebuildSearchCompanion` reconcile entry cover that.
- */
-
-import {
-  SEARCH_COMPANION_FIELD,
-  resolveSearchCompanionSources,
-  containsCJK,
-} from '@objectstack/objectql';
-import { computeSearchCompanionValue } from './pinyin.js';
-
-const SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] } as const;
-
-export const PINYIN_SEARCH_HOOK_PACKAGE = 'plugin-pinyin-search:companion';
-
-interface MinimalEngine {
-  registerHook(
-    event: string,
-    handler: (ctx: any) => any | Promise<any>,
-    options?: { object?: string | string[]; priority?: number; packageId?: string },
-  ): void;
-  unregisterHooksByPackage(packageId: string): number;
-  find(object: string, query?: any, options?: any): Promise<any[]>;
-  update(object: string, data: any, options?: any): Promise<any>;
-  registry?: {
-    getObject(name: string): any;
-    getAllObjects?(packageId?: string): any[];
-  };
-}
-
-interface MinimalLogger {
-  info?: (msg: any, ...rest: any[]) => void;
-  warn?: (msg: any, ...rest: any[]) => void;
-  debug?: (msg: any, ...rest: any[]) => void;
-}
-
-/**
- * Stamp `data.__search` on a before-save hook context when a companion source
- * field is part of the write. Recomputes from the NEW value; a non-CJK new
- * value clears the companion (null) so stale pinyin never recalls a renamed
- * record. Never throws — a normalization failure must not fail the write.
- */
-async function stampCompanion(engine: MinimalEngine, ctx: any, logger?: MinimalLogger): Promise<void> {
-  const object = ctx?.object;
-  if (!object) return;
-  const schema = engine.registry?.getObject?.(object);
-  if (!schema?.fields?.[SEARCH_COMPANION_FIELD]) return;
-
-  const data = ctx?.input?.data;
-  if (!data || typeof data !== 'object' || Array.isArray(data)) return;
-
-  const sources = resolveSearchCompanionSources(schema);
-  if (sources.length === 0) return;
-  const touched = sources.filter((s) => Object.prototype.hasOwnProperty.call(data, s));
-  if (touched.length === 0) return; // source unchanged → no recompute (no write amplification)
-
-  try {
-    data[SEARCH_COMPANION_FIELD] = await computeSearchCompanionValue(sources.map((s) => data[s]));
-  } catch (err: any) {
-    logger?.warn?.('[pinyin-search] companion normalization failed — write proceeds without it', {
-      object,
-      error: err?.message,
-    });
-  }
-}
-
-/**
- * Bind the global before-save hooks that keep `__search` in step. Idempotent
- * (unbinds the package first). Hooks are global (no object filter) with a
- * cheap early-out: objects without a provisioned companion column return
- * immediately. They run for system-context writes too — the projection must
- * stay correct regardless of who writes (seeds, imports, admin UI).
- */
-export function bindSearchCompanionHooks(engine: MinimalEngine, logger?: MinimalLogger): void {
-  if (typeof engine.registerHook !== 'function') return;
-  if (typeof engine.unregisterHooksByPackage === 'function') {
-    engine.unregisterHooksByPackage(PINYIN_SEARCH_HOOK_PACKAGE);
-  }
-  const opts = { packageId: PINYIN_SEARCH_HOOK_PACKAGE, priority: 150 };
-  const handler = (ctx: any) => stampCompanion(engine, ctx, logger);
-  engine.registerHook('beforeInsert', handler, opts);
-  engine.registerHook('beforeUpdate', handler, opts);
-  logger?.info?.('[pinyin-search] companion hooks bound (beforeInsert/beforeUpdate, all objects)');
-}
-
-export interface CompanionBackfillOptions {
-  /** Rows fetched per page during the scan. Default 1000. */
-  batchSize?: number;
-  /** Restrict to one object (reconcile entry); default: every provisioned object. */
-  object?: string;
-  /**
-   * Recompute EVERY row's companion, not just missing ones — the periodic
-   * reconcile/rebuild mode. Default false (backfill: only rows whose
-   * companion is empty but whose source has CJK content).
-   */
-  force?: boolean;
-}
-
-export interface CompanionBackfillResult {
-  objects: number;
-  scanned: number;
-  updated: number;
-}
-
-/**
- * Backfill / reconcile the companion column.
- *
- * Denormalized-on-write columns go stale when writes bypass hooks (bulk
- * import, direct migration) and are empty for rows that predate the switch
- * being enabled. This scans every object that carries the companion column
- * (paged, system context) and fills the gaps; with `force: true` it
- * recomputes unconditionally (the periodic reconcile / rebuild entry).
- * Idempotent; per-row failures are skipped so one bad row never aborts the
- * pass.
- */
-export async function backfillSearchCompanion(
-  engine: MinimalEngine,
-  logger?: MinimalLogger,
-  options?: CompanionBackfillOptions,
-): Promise<CompanionBackfillResult> {
-  const batchSize = Math.max(1, options?.batchSize ?? 1000);
-  const all = options?.object
-    ? [engine.registry?.getObject?.(options.object)].filter(Boolean)
-    : engine.registry?.getAllObjects?.() ?? [];
-
-  const result: CompanionBackfillResult = { objects: 0, scanned: 0, updated: 0 };
-
-  for (const schema of all) {
-    if (!schema?.name || !schema?.fields?.[SEARCH_COMPANION_FIELD]) continue;
-    const sources = resolveSearchCompanionSources(schema);
-    if (sources.length === 0) continue;
-    result.objects++;
-
-    let offset = 0;
-    for (;;) {
-      let rows: any[] = [];
-      try {
-        rows = await engine.find(schema.name, {
-          fields: ['id', ...sources, SEARCH_COMPANION_FIELD],
-          limit: batchSize,
-          offset,
-          context: SYSTEM_CTX,
-        });
-      } catch (err: any) {
-        logger?.warn?.('[pinyin-search] backfill scan failed', { object: schema.name, error: err?.message });
-        break;
-      }
-      if (!rows?.length) break;
-      result.scanned += rows.length;
-
-      for (const row of rows) {
-        if (row?.id == null) continue;
-        const hasBlob = typeof row[SEARCH_COMPANION_FIELD] === 'string' && row[SEARCH_COMPANION_FIELD] !== '';
-        const hasCjkSource = sources.some((s) => containsCJK(row[s]));
-        // Backfill mode: touch only rows missing a blob they should have.
-        // Force mode: recompute everything (also clears stale blobs).
-        if (!options?.force && (hasBlob || !hasCjkSource)) continue;
-        try {
-          const value = await computeSearchCompanionValue(sources.map((s) => row[s]));
-          if (!options?.force && value == null) continue;
-          if (value === row[SEARCH_COMPANION_FIELD]) continue;
-          await engine.update(
-            schema.name,
-            { id: row.id, [SEARCH_COMPANION_FIELD]: value },
-            { context: SYSTEM_CTX },
-          );
-          result.updated++;
-        } catch (err: any) {
-          logger?.warn?.('[pinyin-search] backfill row skipped', {
-            object: schema.name,
-            id: row.id,
-            error: err?.message,
-          });
-        }
-      }
-
-      if (rows.length < batchSize) break;
-      offset += batchSize;
-    }
-  }
-
-  if (result.updated > 0) {
-    logger?.info?.('[pinyin-search] companion backfill complete', result);
-  }
-  return result;
-}
-
-/**
- * Periodic reconcile / rebuild entry: recompute the companion for every row
- * (optionally one object). Alias for `backfillSearchCompanion` with
- * `force: true` — exposed under its own name so operators/jobs have an
- * explicit "rebuild the pinyin index" handle.
- */
-export function rebuildSearchCompanion(
-  engine: MinimalEngine,
-  logger?: MinimalLogger,
-  options?: Omit<CompanionBackfillOptions, 'force'>,
-): Promise<CompanionBackfillResult> {
-  return backfillSearchCompanion(engine, logger, { ...options, force: true });
-}

package/src/index.ts

@@ -1,15 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-export { PinyinSearchPlugin } from './pinyin-search-plugin.js';
-export type { PinyinSearchPluginOptions } from './pinyin-search-plugin.js';
-export {
-  bindSearchCompanionHooks,
-  backfillSearchCompanion,
-  rebuildSearchCompanion,
-  PINYIN_SEARCH_HOOK_PACKAGE,
-} from './companion-projection.js';
-export type {
-  CompanionBackfillOptions,
-  CompanionBackfillResult,
-} from './companion-projection.js';
-export { computeSearchCompanionValue } from './pinyin.js';

package/src/pinyin-search-plugin.ts

@@ -1,105 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * PinyinSearchPlugin (#2486) — pinyin recall for `$search`.
- *
- * Pure hook plugin: the `__search` companion column is declared at object
- * compile time by the SchemaRegistry (gated on the SAME
- * `OS_SEARCH_PINYIN_ENABLED` decision point), the engine ORs it into the
- * `$search` filter, and this plugin fills the value:
- *
- *   - before-save hooks: recompute full pinyin + initials of the
- *     display/name field when it changes;
- *   - boot backfill (`kernel:bootstrapped`): fill rows that predate the
- *     switch or arrived via hook-bypassing writes;
- *   - `rebuildSearchCompanion` (exported): explicit reconcile/rebuild entry.
- *
- * When the flag is off the plugin is inert: no hooks, no backfill, and
- * `pinyin-pro` is never imported.
- */
-
-import type { Plugin, PluginContext } from '@objectstack/core';
-import { resolveSearchPinyinEnabled } from '@objectstack/types';
-import {
-  bindSearchCompanionHooks,
-  backfillSearchCompanion,
-} from './companion-projection.js';
-
-export interface PinyinSearchPluginOptions {
-  /**
-   * Force-enable/disable regardless of `OS_SEARCH_PINYIN_ENABLED` (tests /
-   * embedders). Default: `resolveSearchPinyinEnabled()`.
-   */
-  enabled?: boolean;
-  /** Skip the boot backfill (default: run it once per boot). */
-  backfill?: boolean;
-}
-
-export class PinyinSearchPlugin implements Plugin {
-  name = 'com.objectstack.plugin.pinyin-search';
-  version = '1.0.0';
-  type = 'standard';
-  dependencies = ['com.objectstack.engine.objectql'];
-
-  private readonly options: PinyinSearchPluginOptions;
-
-  constructor(options: PinyinSearchPluginOptions = {}) {
-    this.options = options;
-  }
-
-  private get enabled(): boolean {
-    return this.options.enabled ?? resolveSearchPinyinEnabled();
-  }
-
-  async init(_ctx: PluginContext): Promise<void> {
-    // Nothing to register: the companion column is provisioned by the
-    // SchemaRegistry's compile-time seam, not injected at runtime.
-  }
-
-  async start(ctx: PluginContext): Promise<void> {
-    if (!this.enabled) {
-      ctx.logger.debug?.('PinyinSearchPlugin: OS_SEARCH_PINYIN_ENABLED is off — inert');
-      return;
-    }
-
-    ctx.hook('kernel:ready', async () => {
-      const engine = this.resolveEngine(ctx);
-      if (!engine) {
-        ctx.logger.warn('PinyinSearchPlugin: no ObjectQL engine — companion hooks NOT bound');
-        return;
-      }
-      try {
-        bindSearchCompanionHooks(engine, ctx.logger as any);
-      } catch (err: any) {
-        ctx.logger.warn('PinyinSearchPlugin: companion hooks not bound', { error: err?.message });
-      }
-    });
-
-    // Backfill AFTER boot settles (`kernel:bootstrapped` fires once every
-    // `kernel:ready` hook — including seed loading — has completed), so
-    // seeded rows written before/around hook binding are reconciled too.
-    if (this.options.backfill !== false) {
-      ctx.hook('kernel:bootstrapped', async () => {
-        const engine = this.resolveEngine(ctx);
-        if (!engine) return;
-        try {
-          await backfillSearchCompanion(engine, ctx.logger as any);
-        } catch (err: any) {
-          ctx.logger.warn('PinyinSearchPlugin: companion backfill failed', { error: err?.message });
-        }
-      });
-    }
-  }
-
-  private resolveEngine(ctx: PluginContext): any {
-    try {
-      return ctx.getService<any>('objectql');
-    } catch {
-      try {
-        return ctx.getService<any>('data');
-      } catch {
-        return null;
-      }
-    }
-  }
-}