@infino-ai/infino 0.8.10 → 0.9.1

package/infino/index.d.ts

@@ -101,6 +101,75 @@ export interface OptimizeOptions {
      * compaction still runs). Omit for `"auto"`. */
     recalibrate?: "auto" | "force" | "skip";
 }
+/** How much a reindex repairs. `"auto"` gives each superfile the cheapest
+ * repair that makes it current; `"rewrite"` brings layouts current and leaves
+ * superfiles whose terms are stale (reported); `"reanalyze"` re-tokenizes every
+ * stale superfile from its stored text. */
+export type ReindexMode = "auto" | "rewrite" | "reanalyze";
+/** Options for `reindex`, `reindexPlan` and `indexStaleness`; all fields
+ * optional (omitted ⇒ engine default). Repairs the full-text index. */
+export interface ReindexOptions {
+    /** How much to repair; omit for `"auto"`. */
+    mode?: ReindexMode;
+    /** How old a sealed tombstone sidecar has to be, in milliseconds, before a
+     * rewrite takes it over. Omit to use the table's compaction setting. */
+    staleSealTimeoutMs?: number;
+    /**
+     * Credit a superfile that records no analysis revision with the one its
+     * writer emitted (default `false`). **Only sound when the table never held
+     * superfiles older than that writer**: an older compaction can have folded
+     * stale terms into a newer-stamped file, and crediting it reports the table
+     * migrated with those terms still in place. Leave unset unless the table's
+     * whole history is known.
+     */
+    trustWriterAnalysis?: boolean;
+}
+/** What a `reindex` did. */
+export interface ReindexReport {
+    /** Superfiles rewritten into the current format. */
+    rewritten: number;
+    /** Superfiles already current when the run planned. */
+    alreadyCurrent: number;
+    /** Superfiles holding terms from an older analysis that this run's mode
+     * cannot repair (non-zero only under `"rewrite"`). */
+    awaitingReanalysis: number;
+    /** Stale superfiles another run held; run again to finish them. */
+    heldByAnotherRun: number;
+    /** Columns whose text was never stored, so no repair can fix their terms;
+     * only re-ingesting them from source can. */
+    unrepairableColumns: string[];
+    /** Superfiles left untouched because their footer places a blob where
+     * the file or its manifest entry contradicts; they need inspection. */
+    inconsistentFooters: string[];
+}
+/** What a `reindex` would do, and what it would cost. */
+export interface StalenessReport {
+    /** Superfiles in the table, stale or not. */
+    superfiles: number;
+    /** Superfiles whose layout is behind — what `"rewrite"` would rewrite. */
+    needingRewrite: number;
+    /** Superfiles holding terms from an older analysis, which only
+     * re-analysis repairs. */
+    awaitingReanalysis: number;
+    /** Live bytes a `"rewrite"` would read and write again. */
+    bytesToRewrite: number;
+    /** Columns no repair can fix, because their text was never stored. */
+    unrepairableColumns: string[];
+    /** Superfiles whose footer places a blob where the file or its manifest
+     * entry contradicts. A reindex reports these and never rewrites them. */
+    inconsistentFooters: string[];
+    /** Whether a reindex would do nothing at all. */
+    isCurrent: boolean;
+}
+/** One superfile a `reindex` would repair, and how. */
+export interface PlannedRepair {
+    /** The superfile the run reads and replaces. */
+    superfileId: string;
+    /** The repair it gets — never `"auto"`, which the plan has resolved. */
+    mode: Exclude<ReindexMode, "auto">;
+    /** Live bytes in the superfile. */
+    liveBytes: number;
+}
 export interface Bm25SearchOptions {
     mode?: BoolMode;
     /** BM25 statistics scope: `"global"` (default) or `"per_superfile"`. */
@@ -237,6 +306,24 @@ export declare class Table {
      * calling this on a hosted connection throws.
      */
     gc(graceSecs: number): GcReport;
+    /**
+     * Repair every superfile whose full-text index is behind what this engine
+     * writes. Rows, their order and their `_id`s are unchanged.
+     *
+     * Throws an Error whose message starts with `AlreadyRunningError:` while an
+     * `optimize` or another reindex holds the table — retry later.
+     *
+     * **Local durable connections only.** A `memory://` table has nothing to
+     * repair and a hosted table's storage is the service's, so on either this —
+     * and `reindexPlan` / `indexStaleness` — throws with `code` `"InvalidArg"`.
+     */
+    reindex(options?: ReindexOptions): ReindexReport;
+    /** The superfiles {@link Table.reindex} would repair under `options`, and
+     * the repair each gets — without repairing anything. Writes nothing. */
+    reindexPlan(options?: ReindexOptions): PlannedRepair[];
+    /** What is behind and what repairing it would cost. Writes nothing, so it is
+     * safe against a live table. */
+    indexStaleness(options?: ReindexOptions): StalenessReport;
 }
 /** A catalog connection. Create one with {@link connect}. */
 export declare class Connection {
@@ -253,6 +340,7 @@ export declare class Connection {
     /** Create a table from an apache-arrow `Schema` or `{ column: type }`. */
     createTable(name: string, schema: arrow.Schema | SchemaDescriptor | Buffer, indexes: IndexSpec): Table;
     openTable(name: string): Table;
+    /** Drop a table. `purge` defaults to `true`, which also deletes the table's storage; pass `false` to only unregister it and keep the bytes. */
     dropTable(name: string, purge?: boolean): void;
     listTables(): string[];
     /** SQL across the catalog; rows as records (or an Arrow `Table`). */

package/infino/index.js

@@ -322,6 +322,30 @@ class Table {
     gc(graceSecs) {
         return guard(this.remote, () => this.inner.gc(graceSecs));
     }
+    /**
+     * Repair every superfile whose full-text index is behind what this engine
+     * writes. Rows, their order and their `_id`s are unchanged.
+     *
+     * Throws an Error whose message starts with `AlreadyRunningError:` while an
+     * `optimize` or another reindex holds the table — retry later.
+     *
+     * **Local durable connections only.** A `memory://` table has nothing to
+     * repair and a hosted table's storage is the service's, so on either this —
+     * and `reindexPlan` / `indexStaleness` — throws with `code` `"InvalidArg"`.
+     */
+    reindex(options) {
+        return guard(this.remote, () => this.inner.reindex(options));
+    }
+    /** The superfiles {@link Table.reindex} would repair under `options`, and
+     * the repair each gets — without repairing anything. Writes nothing. */
+    reindexPlan(options) {
+        return guard(this.remote, () => this.inner.reindexPlan(options));
+    }
+    /** What is behind and what repairing it would cost. Writes nothing, so it is
+     * safe against a live table. */
+    indexStaleness(options) {
+        return guard(this.remote, () => this.inner.indexStaleness(options));
+    }
 }
 exports.Table = Table;
 /** A catalog connection. Create one with {@link connect}. */
@@ -349,6 +373,7 @@ class Connection {
     openTable(name) {
         return new Table(guard(this.remote, () => this.inner.openTable(name)), this.remote);
     }
+    /** Drop a table. `purge` defaults to `true`, which also deletes the table's storage; pass `false` to only unregister it and keep the bytes. */
     dropTable(name, purge) {
         guard(this.remote, () => this.inner.dropTable(name, purge));
     }

package/infino/native.d.ts

@@ -84,6 +84,90 @@ export interface GcReport {
   /** Objects that failed to delete (left for the next sweep). */
   deleteErrors: number
 }
+/**
+ * Options for `reindex`, `reindexPlan` and `indexStaleness`; all fields
+ * optional (omitted ⇒ engine default). Repairs the full-text index, the only
+ * index with a repair today.
+ */
+export interface ReindexOptions {
+  /**
+   * How much to repair: `"auto"` (default — the cheapest repair that makes
+   * each superfile current), `"rewrite"` (layout only; superfiles whose
+   * terms are stale are left and reported), or `"reanalyze"` (re-tokenize
+   * every stale superfile from its stored text).
+   */
+  mode?: string
+  /**
+   * How old a sealed tombstone sidecar has to be, in milliseconds, before a
+   * rewrite takes it over. Omit to use the table's compaction setting.
+   */
+  staleSealTimeoutMs?: number
+  /**
+   * Credit a superfile that records no analysis revision with the one its
+   * writer emitted (default `false`). **Only sound when the table never held
+   * superfiles older than that writer**: an older compaction can have folded
+   * stale terms into a newer-stamped file, and crediting it reports the
+   * table migrated with those terms still in place. Leave unset unless the
+   * table's whole history is known.
+   */
+  trustWriterAnalysis?: boolean
+}
+/** What a `reindex` did. */
+export interface ReindexReport {
+  /** Superfiles rewritten into the current format. */
+  rewritten: number
+  /** Superfiles already current when the run planned. */
+  alreadyCurrent: number
+  /**
+   * Superfiles holding terms from an older analysis that this run's mode
+   * cannot repair (non-zero only under `"rewrite"`).
+   */
+  awaitingReanalysis: number
+  /** Stale superfiles another run held; run again to finish them. */
+  heldByAnotherRun: number
+  /**
+   * Columns whose text was never stored, so no repair can fix their terms;
+   * only re-ingesting them from source can.
+   */
+  unrepairableColumns: Array<string>
+  /**
+   * Superfiles left untouched because their footer places a blob where
+   * the file or its manifest entry contradicts; they need inspection.
+   */
+  inconsistentFooters: Array<string>
+}
+/** What a `reindex` would do, and what it would cost. */
+export interface StalenessReport {
+  /** Superfiles in the table, stale or not. */
+  superfiles: number
+  /** Superfiles whose layout is behind — what `"rewrite"` would rewrite. */
+  needingRewrite: number
+  /**
+   * Superfiles holding terms from an older analysis, which only
+   * re-analysis repairs.
+   */
+  awaitingReanalysis: number
+  /** Live bytes a `"rewrite"` would read and write again. */
+  bytesToRewrite: number
+  /** Columns no repair can fix, because their text was never stored. */
+  unrepairableColumns: Array<string>
+  /**
+   * Superfiles whose footer places a blob where the file or its manifest
+   * entry contradicts. A reindex reports these and never rewrites them.
+   */
+  inconsistentFooters: Array<string>
+  /** Whether a reindex would do nothing at all. */
+  isCurrent: boolean
+}
+/** One superfile a `reindex` would repair, and how. */
+export interface PlannedRepair {
+  /** The superfile the run reads and replaces. */
+  superfileId: string
+  /** The repair it gets: `"rewrite"` or `"reanalyze"`, never `"auto"`. */
+  mode: string
+  /** Live bytes in the superfile. */
+  liveBytes: number
+}
 /**
  * Text-predicate filter for `vectorSearch` — a pushdown pre-filter, not a
  * post-filter: kNN ranks only among rows whose FTS-indexed `column` matches
@@ -229,6 +313,7 @@ export declare class Connection {
    * the JS side reads with `tableFromIPC`. Search is available in SQL
    * via the TVFs, e.g.
    * `SELECT _id, score FROM bm25_search('docs', 'body', 'q', 10)`.
+   * Read-only, one statement per call: a write throws `InvalidArg`.
    */
   querySql(sql: string): Buffer
 }
@@ -327,6 +412,19 @@ export declare class Table {
    * racing readers/writers) are removed. Requires durable storage.
    */
   gc(graceSecs: number): GcReport
+  /**
+   * Repair every superfile whose full-text index is behind what this engine
+   * writes. Rows, their order and their `_id`s are unchanged. Requires
+   * durable storage and takes the table's compaction slot.
+   */
+  reindex(options?: ReindexOptions | undefined | null): ReindexReport
+  /**
+   * The superfiles `reindex` would repair under `options`, and the repair
+   * each gets — without repairing anything. Writes nothing.
+   */
+  reindexPlan(options?: ReindexOptions | undefined | null): Array<PlannedRepair>
+  /** What is behind and what repairing it would cost. Writes nothing. */
+  indexStaleness(options?: ReindexOptions | undefined | null): StalenessReport
   /**
    * The user-facing Arrow schema, as an Arrow IPC `Buffer` (an empty
    * table carrying the schema; read with `tableFromIPC`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infino-ai/infino",
-  "version": "0.8.10",
+  "version": "0.9.1",
   "description": "Fast search on object storage — SQL, full-text, and vector search.",
   "license": "Apache-2.0",
   "publishConfig": {
@@ -82,12 +82,12 @@
     "apache-arrow": "^17"
   },
   "optionalDependencies": {
-    "infx-darwin-x64": "0.8.10",
-    "infx-darwin-arm64": "0.8.10",
-    "infx-linux-x64-gnu": "0.8.10",
-    "infx-linux-arm64-gnu": "0.8.10",
-    "infx-linux-x64-musl": "0.8.10",
-    "infx-linux-arm64-musl": "0.8.10"
+    "infx-darwin-x64": "0.9.1",
+    "infx-darwin-arm64": "0.9.1",
+    "infx-linux-x64-gnu": "0.9.1",
+    "infx-linux-arm64-gnu": "0.9.1",
+    "infx-linux-x64-musl": "0.9.1",
+    "infx-linux-arm64-musl": "0.9.1"
   },
   "devDependencies": {
     "@napi-rs/cli": "^2.18.0",