@objectstack/plugin-pinyin-search 17.0.0-rc.0 → 17.0.0-rc.2

package/CHANGELOG.md

@@ -1,5 +1,202 @@
 # @objectstack/plugin-pinyin-search
 
+## 17.0.0-rc.2
+
+### Patch Changes
+
+- Updated dependencies [ce5242c]
+- Updated dependencies [257d97a]
+- Updated dependencies [98877c9]
+- Updated dependencies [c44dd5e]
+- Updated dependencies [20b1a9e]
+- Updated dependencies [f2445c9]
+- Updated dependencies [462b713]
+- Updated dependencies [63b33e6]
+- Updated dependencies [a52e2ef]
+- Updated dependencies [4c45be1]
+- Updated dependencies [ce92674]
+- Updated dependencies [ec975f1]
+- Updated dependencies [eb4204b]
+- Updated dependencies [cb5a75e]
+- Updated dependencies [84b6e58]
+- Updated dependencies [f160ba4]
+- Updated dependencies [b25a116]
+- Updated dependencies [127f091]
+- Updated dependencies [833b512]
+- Updated dependencies [071d0dc]
+- Updated dependencies [1ee48bc]
+- Updated dependencies [26bb053]
+- Updated dependencies [50185a8]
+- Updated dependencies [d6bd5a1]
+- Updated dependencies [ad5fe25]
+  - @objectstack/objectql@17.0.0-rc.2
+  - @objectstack/core@17.0.0-rc.2
+  - @objectstack/types@17.0.0-rc.2
+
+## 17.0.0-rc.1
+
+### Patch Changes
+
+- 2e836de: chore(packaging): CHANGELOG.md ships in every npm tarball (#4261)
+
+  The AGENTS.md post-task checklist requires breaking changesets to carry their
+  FROM → TO migration because "this text ships to consumers as `CHANGELOG.md`
+  inside the npm package and is what an upgrading agent greps after the tombstone
+  error." That delivery path was severed for 68 of the 69 publishable packages:
+  npm packs `package.json` / `README*` / `LICENSE*` unconditionally but — unlike
+  older npm versions — not `CHANGELOG.md`, and the canonical
+  `"files": ["dist", "README.md"]` whitelist never named it. Measured on npm
+  10.9.7: `npm pack --dry-run` on `@objectstack/types` shipped 3 files while its
+  70KB `CHANGELOG.md` stayed behind. Only `@objectstack/spec` listed it
+  explicitly.
+
+  The tombstone-error scenario is precisely the one where the repo is out of
+  reach — the upgrading agent has `node_modules` and nothing else — so the
+  migration text has to ride in the tarball. Every publishable package now
+  declares `CHANGELOG.md` in `files`, and the canonical whitelist is
+  `["dist", "README.md", "CHANGELOG.md"]`.
+
+  The other half is the gate: `check:published-files` gains a fifth invariant,
+  COMPLETE — a whitelist that fails to cover `CHANGELOG.md` fails the
+  always-required lint job, so the next package cannot silently sever the path
+  again. `@objectstack/spec`'s per-package EXTRA_ENTRIES exemption dissolves
+  into the canonical set.
+
+  Consumer-visible change: one more file per install (the package's changelog,
+  e.g. 70.8KB for `@objectstack/types`), and `grep -r "removed key"
+node_modules/@objectstack/*/CHANGELOG.md` now finds the migration it was
+  promised.
+
+- 9881074: fix(batch): the background walks seek instead of counting, so they stop skipping rows (#4363)
+
+  #4363 made a single paged read a partition of its result set. It could not make
+  a _walk_ one: seven background scans paged with a growing `offset` while writing
+  to the very rows they were reading, and an offset counts into a set those writes
+  are changing. Rows slide past the cursor and are never visited.
+
+  That is not a slow page in any of these — it is a wrong answer wearing the shape
+  of a clean run:
+
+  - **`rebuildApproverIndex`** built its desired state by walking
+    `sys_approval_request WHERE status = 'pending'` with no `orderBy` at all, then
+    **deleted** every index row that state did not explain. A skipped request
+    meant an approver silently dropped from someone's queue. (The loop beside it
+    ordered by `created_at` — not unique, so its pages were never a partition
+    either.)
+  - **`verifyFileReferences`** decides which files nothing references. A record it
+    never visits is reported as an unreferenced file.
+  - **`backfillFileReferences`** and the **pinyin companion backfill** rewrite
+    each row they read, so their own writes were shifting the set out from under
+    the cursor. Records were left unconverted and unsearchable by a run that
+    reported success.
+  - **`scanValueShapes`** exists to vouch that no stored value is off-shape, and
+    it opens a migration gate on that evidence.
+
+  All of them now go through `keysetWalk` (`@objectstack/types`): order by a
+  unique key, and seek past the last one instead of counting from the start. A
+  row's key does not move when the row is updated, and cannot be shifted when
+  another is deleted, so the walk is stable under exactly the mutation these
+  functions perform. It is also O(n) rather than O(n²/page) — measured on
+  Postgres over 2M rows, deep pages cost ~1.1 s by offset against ~0.09 s by seek.
+
+  One deliberate non-conversion: the REST **export** stream keeps its offset. It
+  honors a caller-chosen sort, and a keyset walk would have to re-order the export
+  by `id` to seek — changing what the user asked for to fix a cost. Its pages are
+  already a partition since #4363; only the depth cost remains.
+
+  `keysetWalk` merges the cursor with `$and` rather than spreading it into the
+  caller's filter, so a walk whose own `where` constrains the key column
+  (`{ id: { $in: [...] } }`) keeps that constraint instead of having it silently
+  overwritten. When a `max` cap is set it reads one row beyond the cap to tell
+  "the cap stopped us" from "the source ended exactly there" — without that, a
+  walk that read everything still reports `truncated`, and a caller acting on it
+  goes looking for rows that were never withheld.
+
+  The storage suites' fake engines now **throw** on an `offset` instead of serving
+  one, so the conversion is pinned rather than merely passing.
+
+- cc2de0e: chore(packaging): 20 packages stop publishing their sources, tests and build tooling (#4248)
+
+  These 20 packages declared no `files` field, so npm fell back to packing the
+  whole package directory. `npm pack --dry-run` on `@objectstack/plugin-webhooks`
+  listed **21 files** — 15 under `src/`, three of them unit tests
+  (`auto-enqueuer.test.ts`, `bootstrap-declared-webhooks.test.ts`, …), plus the
+  build-time `scripts/i18n-extract.config.ts`. `dist/` lands on top of that at
+  publish time rather than instead of it, so consumers were installing the
+  TypeScript sources and the test suite alongside the artifact they asked for.
+
+  Each now declares `"files": ["dist", "README.md"]`, matching the 29 packages
+  that already did. Nothing a consumer imports moves: every `main` / `types` /
+  `exports` target in all 20 already resolved inside `dist/`, which the new
+  `check:published-files` guard verifies rather than assumes. The visible change
+  is a smaller install and a smaller dependency-scanning surface — `npm pack` on
+  `@objectstack/plugin-webhooks` now yields 2 files plus `dist/`.
+
+  The other half of the fix is the gate. Half the packages declaring `files` and
+  half not was the #3786 shape — a hand-copied convention with nothing enforcing
+  it, where whoever forgets the line gets no signal at all. `check:published-files`
+  (new, wired into the always-required `lint` job) holds every non-private
+  workspace package to four invariants: `files` is **declared**; it is
+  **sufficient** (covers every entry point, so tightening a whitelist cannot ship
+  a package that fails to resolve); it is **minimal** (admits no test, test-harness
+  config or build script); and anything beyond `dist` + `README.md` is
+  **registered** with a reason, reconciled in both directions so a stale exemption
+  is an error rather than dead text. `@objectstack/spec` is the one package with
+  registered extras — its `.zod.ts` sources, JSON Schemas, liveness ledgers and
+  `CHANGELOG.md` are product, not build input.
+
+  This also closes an assumption #4206 was resting on. Excluding `<pkg>/scripts/**`
+  from the docs-drift implementation test is sound only while no package publishes
+  `scripts/` as runtime code; that held, but it held because someone read all three
+  offenders by hand. It is now checked on every PR.
+
+- Updated dependencies [48fcf70]
+- Updated dependencies [3ec8186]
+- Updated dependencies [b1863a5]
+- Updated dependencies [270650f]
+- Updated dependencies [956e7f9]
+- Updated dependencies [3aef718]
+- Updated dependencies [ffb003c]
+- Updated dependencies [32ccb23]
+- Updated dependencies [2d3e255]
+- Updated dependencies [7d7521f]
+- Updated dependencies [8d895ff]
+- Updated dependencies [2af1988]
+- Updated dependencies [0af50a3]
+- Updated dependencies [2e836de]
+- Updated dependencies [c20b875]
+- Updated dependencies [2a37694]
+- Updated dependencies [3c628ce]
+- Updated dependencies [ed77493]
+- Updated dependencies [58a03d2]
+- Updated dependencies [c39d713]
+- Updated dependencies [91f4c78]
+- Updated dependencies [45dc446]
+- Updated dependencies [ab9fb5c]
+- Updated dependencies [f985b3f]
+- Updated dependencies [9881074]
+- Updated dependencies [7777e8f]
+- Updated dependencies [507b92a]
+- Updated dependencies [39eb01b]
+- Updated dependencies [55bbefc]
+- Updated dependencies [7ce02eb]
+- Updated dependencies [d13004a]
+- Updated dependencies [be7360c]
+- Updated dependencies [8675db6]
+- Updated dependencies [b09d8d9]
+- Updated dependencies [af2a095]
+- Updated dependencies [bf478e1]
+- Updated dependencies [77fadbf]
+- Updated dependencies [5c13368]
+- Updated dependencies [857a6cf]
+- Updated dependencies [d5749d7]
+- Updated dependencies [d92c72d]
+- Updated dependencies [5d21a48]
+- Updated dependencies [e4c2dc8]
+  - @objectstack/objectql@17.0.0-rc.1
+  - @objectstack/core@17.0.0-rc.1
+  - @objectstack/types@17.0.0-rc.1
+
 ## 17.0.0-rc.0
 
 ### Patch Changes

package/dist/index.js

@@ -40,10 +40,11 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/pinyin-search-plugin.ts
-var import_types = require("@objectstack/types");
+var import_types2 = require("@objectstack/types");
 
 // src/companion-projection.ts
 var import_objectql2 = require("@objectstack/objectql");
+var import_types = require("@objectstack/types");
 
 // src/pinyin.ts
 var import_objectql = require("@objectstack/objectql");
@@ -114,47 +115,44 @@ async function backfillSearchCompanion(engine, logger, options) {
     const sources = (0, import_objectql2.resolveSearchCompanionSources)(schema);
     if (sources.length === 0) continue;
     result.objects++;
-    let offset = 0;
-    for (; ; ) {
-      let rows = [];
-      try {
-        rows = await engine.find(schema.name, {
-          fields: ["id", ...sources, import_objectql2.SEARCH_COMPANION_FIELD],
-          limit: batchSize,
-          offset,
-          context: SYSTEM_CTX
-        });
-      } catch (err) {
-        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[import_objectql2.SEARCH_COMPANION_FIELD] === "string" && row[import_objectql2.SEARCH_COMPANION_FIELD] !== "";
-        const hasCjkSource = sources.some((s) => (0, import_objectql2.containsCJK)(row[s]));
-        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[import_objectql2.SEARCH_COMPANION_FIELD]) continue;
-          await engine.update(
-            schema.name,
-            { id: row.id, [import_objectql2.SEARCH_COMPANION_FIELD]: value },
-            { context: SYSTEM_CTX }
-          );
-          result.updated++;
-        } catch (err) {
-          logger?.warn?.("[pinyin-search] backfill row skipped", {
-            object: schema.name,
-            id: row.id,
-            error: err?.message
-          });
+    const walk = (0, import_types.keysetWalk)(
+      (q) => engine.find(schema.name, {
+        ...q,
+        fields: ["id", ...sources, import_objectql2.SEARCH_COMPANION_FIELD],
+        context: SYSTEM_CTX
+      }),
+      { pageSize: batchSize }
+    );
+    try {
+      for await (const rows of walk.pages()) {
+        result.scanned += rows.length;
+        for (const row of rows) {
+          if (row?.id == null) continue;
+          const hasBlob = typeof row[import_objectql2.SEARCH_COMPANION_FIELD] === "string" && row[import_objectql2.SEARCH_COMPANION_FIELD] !== "";
+          const hasCjkSource = sources.some((s) => (0, import_objectql2.containsCJK)(row[s]));
+          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[import_objectql2.SEARCH_COMPANION_FIELD]) continue;
+            await engine.update(
+              schema.name,
+              { id: row.id, [import_objectql2.SEARCH_COMPANION_FIELD]: value },
+              { context: SYSTEM_CTX }
+            );
+            result.updated++;
+          } catch (err) {
+            logger?.warn?.("[pinyin-search] backfill row skipped", {
+              object: schema.name,
+              id: row.id,
+              error: err?.message
+            });
+          }
         }
       }
-      if (rows.length < batchSize) break;
-      offset += batchSize;
+    } catch (err) {
+      logger?.warn?.("[pinyin-search] backfill scan failed", { object: schema.name, error: err?.message });
+      continue;
     }
   }
   if (result.updated > 0) {
@@ -176,7 +174,7 @@ var PinyinSearchPlugin = class {
     this.options = options;
   }
   get enabled() {
-    return this.options.enabled ?? (0, import_types.resolveSearchPinyinEnabled)();
+    return this.options.enabled ?? (0, import_types2.resolveSearchPinyinEnabled)();
   }
   async init(_ctx) {
   }

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 { 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":["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\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":["import_types","import_objectql"]}

package/dist/index.mjs

@@ -7,6 +7,7 @@ import {
   resolveSearchCompanionSources,
   containsCJK as containsCJK2
 } from "@objectstack/objectql";
+import { keysetWalk } from "@objectstack/types";
 
 // src/pinyin.ts
 import { containsCJK } from "@objectstack/objectql";
@@ -77,47 +78,44 @@ async function backfillSearchCompanion(engine, logger, options) {
     const sources = resolveSearchCompanionSources(schema);
     if (sources.length === 0) continue;
     result.objects++;
-    let offset = 0;
-    for (; ; ) {
-      let rows = [];
-      try {
-        rows = await engine.find(schema.name, {
-          fields: ["id", ...sources, SEARCH_COMPANION_FIELD],
-          limit: batchSize,
-          offset,
-          context: SYSTEM_CTX
-        });
-      } catch (err) {
-        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) => containsCJK2(row[s]));
-        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) {
-          logger?.warn?.("[pinyin-search] backfill row skipped", {
-            object: schema.name,
-            id: row.id,
-            error: err?.message
-          });
+    const walk = keysetWalk(
+      (q) => engine.find(schema.name, {
+        ...q,
+        fields: ["id", ...sources, SEARCH_COMPANION_FIELD],
+        context: SYSTEM_CTX
+      }),
+      { pageSize: batchSize }
+    );
+    try {
+      for await (const rows of walk.pages()) {
+        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) => containsCJK2(row[s]));
+          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) {
+            logger?.warn?.("[pinyin-search] backfill row skipped", {
+              object: schema.name,
+              id: row.id,
+              error: err?.message
+            });
+          }
         }
       }
-      if (rows.length < batchSize) break;
-      offset += batchSize;
+    } catch (err) {
+      logger?.warn?.("[pinyin-search] backfill scan failed", { object: schema.name, error: err?.message });
+      continue;
     }
   }
   if (result.updated > 0) {

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":";AAqBA,SAAS,kCAAkC;;;ACH3C;AAAA,EACE;AAAA,EACA;AAAA,EACA,eAAAA;AAAA,OACK;;;ACHP,SAAS,mBAAmB;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,MAAmB,YAAY,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;;;ADrCA,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,sBAAsB,EAAG;AAE/C,QAAM,OAAO,KAAK,OAAO;AACzB,MAAI,CAAC,QAAQ,OAAO,SAAS,YAAY,MAAM,QAAQ,IAAI,EAAG;AAE9D,QAAM,UAAU,8BAA8B,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,sBAAsB,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,sBAAsB,EAAG;AAChE,UAAM,UAAU,8BAA8B,MAAM;AACpD,QAAI,QAAQ,WAAW,EAAG;AAC1B,WAAO;AAEP,QAAI,SAAS;AACb,eAAS;AACP,UAAI,OAAc,CAAC;AACnB,UAAI;AACF,eAAO,MAAM,OAAO,KAAK,OAAO,MAAM;AAAA,UACpC,QAAQ,CAAC,MAAM,GAAG,SAAS,sBAAsB;AAAA,UACjD,OAAO;AAAA,UACP;AAAA,UACA,SAAS;AAAA,QACX,CAAC;AAAA,MACH,SAAS,KAAU;AACjB,gBAAQ,OAAO,wCAAwC,EAAE,QAAQ,OAAO,MAAM,OAAO,KAAK,QAAQ,CAAC;AACnG;AAAA,MACF;AACA,UAAI,CAAC,MAAM,OAAQ;AACnB,aAAO,WAAW,KAAK;AAEvB,iBAAW,OAAO,MAAM;AACtB,YAAI,KAAK,MAAM,KAAM;AACrB,cAAM,UAAU,OAAO,IAAI,sBAAsB,MAAM,YAAY,IAAI,sBAAsB,MAAM;AACnG,cAAM,eAAe,QAAQ,KAAK,CAAC,MAAMC,aAAY,IAAI,CAAC,CAAC,CAAC;AAG5D,YAAI,CAAC,SAAS,UAAU,WAAW,CAAC,cAAe;AACnD,YAAI;AACF,gBAAM,QAAQ,MAAM,4BAA4B,QAAQ,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC;AAC1E,cAAI,CAAC,SAAS,SAAS,SAAS,KAAM;AACtC,cAAI,UAAU,IAAI,sBAAsB,EAAG;AAC3C,gBAAM,OAAO;AAAA,YACX,OAAO;AAAA,YACP,EAAE,IAAI,IAAI,IAAI,CAAC,sBAAsB,GAAG,MAAM;AAAA,YAC9C,EAAE,SAAS,WAAW;AAAA,UACxB;AACA,iBAAO;AAAA,QACT,SAAS,KAAU;AACjB,kBAAQ,OAAO,wCAAwC;AAAA,YACrD,QAAQ,OAAO;AAAA,YACf,IAAI,IAAI;AAAA,YACR,OAAO,KAAK;AAAA,UACd,CAAC;AAAA,QACH;AAAA,MACF;AAEA,UAAI,KAAK,SAAS,UAAW;AAC7B,gBAAU;AAAA,IACZ;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;;;ADhLO,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,WAAW,2BAA2B;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":["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": "17.0.0-rc.0",
+  "version": "17.0.0-rc.2",
   "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,12 +14,12 @@
   },
   "dependencies": {
     "pinyin-pro": "^3.28.2",
-    "@objectstack/core": "17.0.0-rc.0",
-    "@objectstack/objectql": "17.0.0-rc.0",
-    "@objectstack/types": "17.0.0-rc.0"
+    "@objectstack/core": "17.0.0-rc.2",
+    "@objectstack/objectql": "17.0.0-rc.2",
+    "@objectstack/types": "17.0.0-rc.2"
   },
   "devDependencies": {
-    "@types/node": "^26.1.1",
+    "@types/node": "^26.1.2",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   },
@@ -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@17.0.0-rc.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 54ms
-ESM dist/index.mjs     6.88 KB
-ESM dist/index.mjs.map 19.09 KB
-ESM ⚡️ Build success in 57ms
-DTS Build start
-DTS ⚡️ Build success in 8808ms
-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;
-      }
-    }
-  }
-}

package/src/pinyin.test.ts

@@ -1,39 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { describe, it, expect } from 'vitest';
-import { computeSearchCompanionValue } from './pinyin.js';
-
-describe('computeSearchCompanionValue (#2486)', () => {
-  it('stores full pinyin + initials in one blob ("张伟" → "zhangwei zw")', async () => {
-    expect(await computeSearchCompanionValue(['张伟'])).toBe('zhangwei zw');
-  });
-
-  it('recalls every documented input shape as a substring of the blob', async () => {
-    const blob = (await computeSearchCompanionValue(['张伟']))!;
-    for (const typed of ['zhang', 'wei', 'zhangwei', 'zw']) {
-      expect(blob.includes(typed)).toBe(true);
-    }
-  });
-
-  it('handles multi-word and mixed CJK/latin values', async () => {
-    const blob = (await computeSearchCompanionValue(['上海分公司']))!;
-    expect(blob).toBe('shanghaifengongsi shfgs');
-
-    const mixed = (await computeSearchCompanionValue(['张伟2号']))!;
-    expect(mixed.includes('zhangwei2hao')).toBe(true);
-  });
-
-  it('returns null for non-CJK / empty / non-string values (companion cleared)', async () => {
-    expect(await computeSearchCompanionValue(['Zhang Wei'])).toBe(null);
-    expect(await computeSearchCompanionValue([''])).toBe(null);
-    expect(await computeSearchCompanionValue([null, undefined, 42])).toBe(null);
-    expect(await computeSearchCompanionValue([])).toBe(null);
-  });
-
-  it('deduplicates when initials equal the full form (single-char name)', async () => {
-    const blob = (await computeSearchCompanionValue(['张']))!;
-    expect(blob).toBe('zhang z');
-    // no duplicated tokens
-    expect(new Set(blob.split(' ')).size).toBe(blob.split(' ').length);
-  });
-});

package/src/pinyin.ts

@@ -1,63 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * Pinyin normalization for the `__search` companion column (#2486).
- *
- * One normalized blob per record — full pinyin AND initials in the same
- * column — so a single `$contains` recalls every latin input shape:
- *
- *   "张伟"  →  "zhangwei zw"
- *     `zhang` / `wei` / `zhangwei`  → substring of the full form
- *     `zw`                          → substring of the initials form
- *
- * `pinyin-pro` is loaded lazily on first use: non-Chinese deployments (flag
- * off → hooks never bound) never import it and pay zero cost.
- *
- * Polyphones: pinyin-pro's default heuristics are accepted (issue #2486
- * "待定" — surname polyphone dictionaries are a P2 follow-up).
- */
-
-import { containsCJK } from '@objectstack/objectql';
-
-type PinyinFn = (text: string, options?: Record<string, unknown>) => string | string[];
-
-let _pinyin: Promise<PinyinFn> | null = null;
-
-/** Lazy-load `pinyin-pro` (cached module-wide). */
-function loadPinyin(): Promise<PinyinFn> {
-  _pinyin ??= import('pinyin-pro').then((m: any) => (m.pinyin ?? m.default?.pinyin) as PinyinFn);
-  return _pinyin;
-}
-
-/** Lowercase and strip everything that is not a latin letter or digit. */
-function squash(syllables: string | string[]): string {
-  const joined = Array.isArray(syllables) ? syllables.join('') : String(syllables ?? '');
-  return joined.toLowerCase().replace(/[^a-z0-9]+/g, '');
-}
-
-/**
- * Compute the companion value for the given source-field values.
- *
- * Returns the normalized blob (`"<full-pinyin> <initials>"`, deduplicated)
- * when at least one value contains CJK characters, else `null` — a `null`
- * companion means "nothing pinyin-searchable here" and clears any stale blob
- * when a name is edited away from CJK. Non-CJK values need no companion:
- * their source column already matches latin input directly.
- */
-export async function computeSearchCompanionValue(values: ReadonlyArray<unknown>): Promise<string | null> {
-  const cjkValues = values.filter((v): v is string => containsCJK(v));
-  if (cjkValues.length === 0) return null;
-
-  const pinyin = await loadPinyin();
-  const parts: string[] = [];
-  for (const value of cjkValues) {
-    // `nonZh: 'consecutive'` keeps latin/digit runs intact inside mixed
-    // values ("张伟2号" → "zhangwei2hao"), so mixed names stay one token.
-    const full = squash(pinyin(value, { toneType: 'none', type: 'array', nonZh: 'consecutive' }));
-    const initials = squash(pinyin(value, { pattern: 'first', toneType: 'none', type: 'array', nonZh: 'consecutive' }));
-    if (full) parts.push(full);
-    if (initials && initials !== full) parts.push(initials);
-  }
-  if (parts.length === 0) return null;
-  return [...new Set(parts)].join(' ');
-}

package/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "extends": "../../../tsconfig.json",
-  "compilerOptions": {
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "types": ["node"]
-  },
-  "include": ["src/**/*"],
-  "exclude": ["dist", "node_modules", "**/*.test.ts"]
-}