/**
 * @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'
}