feat(8.0): wire the two cor-confirmed metadata-provider contract additions

Both shapes confirmed with cor for the lockstep (cor builds the native side
against these; the JS index is a no-op / unchanged):

- probeConsistency?(): Promise<boolean> — OPTIONAL O(1) cold-open consistency
  sampler on MetadataIndexProvider. brainy calls it ONCE per brain on the first
  read; on `false` it self-heals via detectAndRepairCorruption() — the metadata
  counterpart of the 7.33.2 graph cold-load guard, completing the phantom triad's
  detect-and-repair-on-open. Best-effort: a probe failure never breaks a read
  (the one-shot guard resets so a transient failure retries). The JS index omits
  the method, so it is simply never probed.

- getIdsForFilter(filter, opts?: { limit?; offset? }) — brainy passes a page
  bound on the UNSORTED find({ type, where, limit }) path so a native provider can
  early-stop and return only the [0, limit) prefix, killing the O(N) FFI marshal
  at billion scale (pairs with cor #75). brainy passes offset:0 and ALWAYS
  re-windows the result itself (visibility filter + slice); the JS index ignores
  opts and returns all matches (behaviour unchanged).

New unit tests cover brainy's call behaviour for both (probe→repair on false,
healthy→no-repair, failure-is-best-effort, once-per-brain; opts passed with
offset 0 on the unsorted path). Full gate green: unit 1718, integration 607.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/plugin.ts

@@ -129,7 +129,18 @@ export interface MetadataIndexProvider {
   removeFromIndex(id: string, metadata?: any): Promise<void>
 
   getIds(field: string, value: any): Promise<string[]>
-  getIdsForFilter(filter: any): Promise<string[]>
+  /**
+   * Resolve a `where` filter to its matching ids.
+   * @param filter - The filter shape (eq / allOf / anyOf / ne / range / exists / …).
+   * @param opts - OPTIONAL page bound for the UNSORTED `find({ type, where, limit })`
+   *   path. Brainy passes `{ limit: offset+limit (+hidden over-fetch), offset: 0 }` and
+   *   ALWAYS re-windows the result itself (visibility filter + `slice`), so a provider
+   *   that honors `opts` should early-stop and return the `[0, limit)` PREFIX (it must
+   *   NOT pre-apply `offset`). The JS index ignores `opts` and returns all matches —
+   *   so honoring it is a pure native-side optimization that removes the O(N) FFI
+   *   marshal at billion scale. Pairs with {@link getIdSetForFilter}.
+   */
+  getIdsForFilter(filter: any, opts?: { limit?: number; offset?: number }): Promise<string[]>
   /**
    * @description OPTIONAL: resolve a `where` filter to its matching id universe as
    * an {@link OpaqueIdSet} (a serialized roaring `Buffer`) WITHOUT materializing
@@ -171,6 +182,17 @@ export interface MetadataIndexProvider {
   getAllVFSEntityCounts(): Promise<Map<string, number>>
 
   detectAndRepairCorruption(): Promise<void>
+  /**
+   * OPTIONAL cheap (O(1)) cold-open consistency probe — the counterpart of the
+   * graph cold-load guard. Returns `true` if a sampled `(field, value, int)` is
+   * clean, `false` if it detects the cross-bucket phantom signature (an int whose
+   * current value for `field` no longer equals `value`). Brainy calls it ONCE per
+   * brain on the first read and, on `false`, runs {@link detectAndRepairCorruption}
+   * to self-heal — so an already-poisoned index repairs itself on open without the
+   * cost of the full-scan {@link validateConsistency}. A provider that omits it is
+   * simply never auto-probed (no behavior change).
+   */
+  probeConsistency?(): Promise<boolean>
   validateConsistency(): Promise<{
     healthy: boolean
     avgEntriesPerEntity: number