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

package/CHANGELOG.md

@@ -1,5 +1,257 @@
 # @objectstack/plugin-pinyin-search
 
+## 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
+
+- 9f060e5: chore(deps)!: better-auth 1.7.0-rc.2 (account identity restructuring) + the
+  production-dependency batch from #3517
+
+  **better-auth 1.7.0-rc.1 → 1.7.0-rc.2** across the family (`better-auth`,
+  `@better-auth/core`, `@better-auth/oauth-provider`, `@better-auth/sso`, and the
+  adapter/telemetry overrides). `@better-auth/scim` deliberately stays on
+  1.7.0-rc.1 — rc.2 replaces its whole model (code-defined connections; the
+  `scimProvider` model and the generate-token endpoint are gone), which is a
+  feature migration, not a version bump. Its peer range accepts rc.2 core, and the
+  advisory that forced the original pin (GHSA-j8v8-g9cx-5qf4) is still fixed.
+
+  **BREAKING — account identity.** better-auth renamed `account.accountId` to
+  `account.providerAccountId` and added a REQUIRED `account.issuer`; sign-in now
+  resolves accounts by `(issuer, providerAccountId)`.
+
+  - FROM `fields: { accountId: 'account_id' }` → TO
+    `fields: { issuer: 'issuer', providerAccountId: 'account_id' }`. The provider
+    account id keeps its `account_id` column — only the better-auth-side name
+    moved — and `sys_account` gains an `issuer` column.
+  - FROM `internalAdapter.createAccount({ providerId, accountId, … })` → TO
+    `createAccount({ providerId, issuer, providerAccountId, … })`. A local
+    password account carries the issuer better-auth mints for itself,
+    `local:credential`.
+  - FROM `client.auth.accounts.unlink({ providerId, accountId })` → TO
+    `unlink({ accountId })`, where `accountId` is now the account ROW id (the `id`
+    from `accounts.list()`), matching better-auth's narrowed body.
+    `accounts.list()` returns `issuer` + `providerAccountId` in place of
+    `accountId`.
+
+  **Existing deployments:** rows written before 1.7 have no issuer and are
+  invisible to sign-in until stamped. The auth plugin now runs an idempotent
+  boot-time backfill that stamps what it can derive — `local:credential` for
+  password accounts, `local:oauth:<providerId>` for configured social providers,
+  and the registered IdP's real `iss` from `sys_sso_provider` for federated ones.
+  Accounts from a federated IdP that is no longer registered cannot be derived;
+  they are logged with their provider id and row count rather than guessed, and
+  those users cannot sign in through that provider until the row is stamped with
+  the IdP's issuer or removed so a fresh login re-links it.
+
+  **Also required by 1.7:** `SecondaryStorage` gained two mandatory methods, both
+  now implemented over the kernel cache service — `getAndDelete` (single-use
+  verification values) and `increment` (fixed-window rate-limit counter;
+  `rateLimit.storage: 'secondary-storage'` throws at boot without it).
+
+  The rest of #3517's production-dependency batch rides along: `@oclif/core`
+  4.13.0, `@hono/node-server` 2.0.12, `hono` 4.12.32, `tar` 7.5.22, `jose` 6.2.4,
+  `pinyin-pro` 3.28.2, plus the private docs app's fumadocs/next/react bumps.
+
+- Updated dependencies [6169615]
+- Updated dependencies [fa3d0cf]
+- Updated dependencies [a749273]
+- Updated dependencies [fdb4f50]
+- Updated dependencies [879ea13]
+- Updated dependencies [840ee4b]
+- Updated dependencies [ad4af62]
+- Updated dependencies [d44dbfa]
+- Updated dependencies [b949059]
+- Updated dependencies [c5ff96d]
+- Updated dependencies [48c110e]
+- Updated dependencies [87aca93]
+- Updated dependencies [32d3800]
+- Updated dependencies [a227ed7]
+- Updated dependencies [763931e]
+- Updated dependencies [de9af8a]
+- Updated dependencies [5d4de37]
+- Updated dependencies [0e3a226]
+- Updated dependencies [4cca74c]
+- Updated dependencies [81ce41a]
+- Updated dependencies [85e1e4e]
+- Updated dependencies [e1fa8d5]
+- Updated dependencies [402f534]
+- Updated dependencies [030125b]
+- Updated dependencies [8e08bc3]
+- Updated dependencies [0c302a7]
+- Updated dependencies [5f0852f]
+- Updated dependencies [cde1975]
+- Updated dependencies [20cb232]
+- Updated dependencies [e231abb]
+- Updated dependencies [b95577a]
+- Updated dependencies [54f479a]
+  - @objectstack/objectql@17.0.0-rc.0
+  - @objectstack/core@17.0.0-rc.0
+  - @objectstack/types@17.0.0-rc.0
+
 ## 16.1.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) {