@nicia-ai/typegraph 0.41.0 → 0.42.0

package/dist/materialize-indexes-ExQ6OrAh.d.cts

@@ -1,90 +0,0 @@
-import { I as IndexEntity } from './extension-types-BLEVH4SG.cjs';
-
-/**
- * Index materialization — runs declared index DDL against the live
- * database and tracks per-deployment status in
- * `typegraph_index_materializations`.
- *
- * Reads `IndexDeclaration[]` from `GraphDef.indexes`, generates DDL via
- * `generateIndexDDL`, executes via `backend.executeDdl` (Postgres path
- * uses `CREATE INDEX CONCURRENTLY`, which cannot run inside a
- * transaction — `executeDdl` runs at the top-level backend, never inside
- * `transaction(...)`), and upserts a status row per index.
- *
- * Caveats baked in to the algorithm:
- *
- * - SQL index names are physical, database-global identifiers.
- *   Cross-graph collisions (two graphs declaring the same name with
- *   different shapes) surface as a `failed` result with reason
- *   "signature drift", because the existing recorded signature won't
- *   match the new one.
- * - On Postgres, `CREATE INDEX CONCURRENTLY IF NOT EXISTS` does NOT
- *   prove the existing physical index has the same shape as ours —
- *   only that something with that name exists. Drift detection here
- *   relies on TypeGraph's recorded signature, not on PG metadata.
- * - Failed `CONCURRENTLY` builds leave invalid indexes behind
- *   (`pg_index.indisvalid = false`). Relational rebuilds self-heal: the
- *   claim-holding materializer drops an invalid leftover with the
- *   declaration's name before rebuilding (see dropInvalidIndexLeftover).
- *   Vector per-field index leftovers remain operator-repair.
- * - Two materializers racing the SAME index name serialize through a
- *   durable claim in the status table (see materializeWithClaim) —
- *   concurrent same-name expression-index CIC builds deadlock on
- *   Postgres (no safe-snapshot exemption).
- */
-
-type MaterializeIndexesOptions = Readonly<{
-    /** Restrict to indexes whose `kind` is in this set. */
-    kinds?: readonly string[];
-    /** Stop on the first failure. Default: false (best-effort). */
-    stopOnError?: boolean;
-    /**
-     * Refresh planner statistics (ANALYZE) after at least one index was
-     * created. A fresh index can be ignored by the planner until statistics
-     * exist. Default: true. Applied on non-concurrent builders (SQLite) and
-     * on concurrent builders that serialize same-index builds via the
-     * cross-caller claim primitive (the bundled Postgres backend); a custom
-     * concurrent backend without the primitive skips the refresh — see
-     * refreshStatisticsAfterCreation — and should call
-     * `store.refreshStatistics()` after materializing.
-     */
-    refreshStatistics?: boolean;
-}>;
-/**
- * Per-index outcome from `materializeIndexes()`.
- *
- * Status values:
- * - `created`: DDL ran successfully and a new physical index now exists.
- * - `alreadyMaterialized`: status table shows a prior successful
- *   materialization with the same signature; no DDL ran.
- * - `failed`: the DDL or status write failed; `error` carries the
- *   captured exception. Best-effort mode continues to the next index;
- *   `stopOnError: true` halts.
- * - `skipped`: the backend can't materialize this index variant in its
- *   current configuration (e.g. vector indexes against SQLite without
- *   sqlite-vec, or `indexType: "none"` declared on an embedding). The
- *   declaration is recognized but intentionally not acted on. Status
- *   table is NOT updated for skipped entries.
- */
-type MaterializeIndexesEntry = Readonly<{
-    indexName: string;
-    entity: IndexEntity;
-    kind: string;
-    status: "created" | "alreadyMaterialized" | "failed" | "skipped";
-    error?: Error;
-    /**
-     * Human-readable reason. Required for `skipped`; optional otherwise.
-     */
-    reason?: string;
-}>;
-type MaterializeIndexesResult = Readonly<{
-    results: readonly MaterializeIndexesEntry[];
-}>;
-type MaterializeSystemIndexesOptions = Readonly<{
-    /** Stop on the first failure. Default: false (best-effort). */
-    stopOnError?: boolean;
-    /** Refresh planner statistics after a creation. Default: true. */
-    refreshStatistics?: boolean;
-}>;
-
-export type { MaterializeIndexesResult as M, MaterializeIndexesEntry as a, MaterializeIndexesOptions as b, MaterializeSystemIndexesOptions as c };