39 lines
1.9 KiB
TypeScript
39 lines
1.9 KiB
TypeScript
|
/**
|
||
|
|
* @module indexReadiness
|
||
|
|
* @description The single honest-readiness classifier shared by the vector,
|
||
|
|
* graph and metadata index sites. It exists to kill "Pattern A" — the dishonest
|
||
|
|
* readiness proxy where `size() > 0` / `isInitialized` is treated as "this index
|
||
|
|
* actually serves queries." A cold native index that loaded its COUNT but not its
|
||
|
|
* SERVING structure passes those proxies and silently returns `[]`.
|
||
|
|
*
|
||
|
|
* This classifier reads ONLY the provider's OPTIONAL, honest `isReady()` signal
|
||
|
|
* (see {@link import('../plugin.js').VectorIndexProvider.isReady},
|
||
|
|
* {@link import('../plugin.js').GraphIndexProvider.isReady},
|
||
|
|
* {@link import('../plugin.js').MetadataIndexProvider.isReady}). It NEVER inspects
|
||
|
|
* `size()` or `isInitialized`. When `isReady()` is absent, callers must fall back
|
||
|
|
* to a KNOWN-ITEM PROBE (a real search/lookup that must return a known-present
|
||
|
|
* datum) before trusting an empty result — never a `size()` proxy.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/** A provider that MAY expose the honest cold-load readiness signal. */
|
||
|
|
export interface MaybeReadyProvider {
|
||
|
|
isReady?: () => boolean
|
||
|
|
}
|
||
|
|
|
||
|
|
/** Three-valued honest-readiness verdict. */
|
||
|
|
export type IndexReadiness = 'ready' | 'not-ready' | 'unknown'
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @description Classify an index provider's honest readiness.
|
||
|
|
* @param provider - Any index provider (vector / graph / metadata) or `null`.
|
||
|
|
* @returns
|
||
|
|
* - `'ready'` when `isReady() === true` (serving structure loaded — trust it);
|
||
|
|
* - `'not-ready'` when `isReady() === false` (count/manifest loaded, NOT serving — rebuild);
|
||
|
|
* - `'unknown'` when the provider exposes no `isReady()` (caller must probe / keep the JS heuristic).
|
||
|
|
*/
|
||
|
|
export function assessIndexReadiness(provider: unknown): IndexReadiness {
|
||
|
|
const p = provider as MaybeReadyProvider | null | undefined
|
||
|
|
if (p == null || typeof p.isReady !== 'function') return 'unknown'
|
||
|
|
return p.isReady() ? 'ready' : 'not-ready'
|
||
|
|
}
|