@nicia-ai/typegraph 0.50.0 → 0.51.0

package/dist/materialize-indexes-C9GG3O3C.d.ts

@@ -1,266 +0,0 @@
-import { c6 as SerializedNodeDef, c4 as SerializedEdgeDef, ba as IndexEntity, I as IndexDeclaration, c9 as SerializedSchema } from './types-CWg4dTjj.js';
-
-/**
- * Schema migration utilities.
- *
- * Provides diff detection between schema versions to identify
- * what has changed and what migrations might be needed.
- */
-
-/**
- * Types of changes that can occur in a schema.
- */
-type ChangeType = "added" | "removed" | "modified" | "renamed";
-/**
- * Severity of a change for migration purposes.
- */
-type ChangeSeverity = "safe" | "warning" | "breaking";
-/**
- * A change to a node definition.
- */
-type NodeChange = Readonly<{
-    type: ChangeType;
-    kind: string;
-    severity: ChangeSeverity;
-    details: string;
-    before?: SerializedNodeDef | undefined;
-    after?: SerializedNodeDef | undefined;
-}>;
-/**
- * A change to an edge definition.
- */
-type EdgeChange = Readonly<{
-    type: ChangeType;
-    kind: string;
-    severity: ChangeSeverity;
-    details: string;
-    before?: SerializedEdgeDef | undefined;
-    after?: SerializedEdgeDef | undefined;
-}>;
-/**
- * A change to the ontology.
- */
-type OntologyChange = Readonly<{
-    type: ChangeType;
-    entity: "metaEdge" | "relation";
-    name: string;
-    severity: ChangeSeverity;
-    details: string;
-}>;
-/** A durable graph-level Operational Identity capability change. */
-type IdentityChange = Readonly<{
-    type: ChangeType;
-    severity: ChangeSeverity;
-    details: string;
-}>;
-/**
- * A change to an index declaration.
- *
- * Index changes are always `safe`-severity: index DDL is materialized
- * separately and never blocks schema-version commits or migrations.
- * Adding, removing, or modifying an index never invalidates existing
- * data — it only changes which physical indexes the deployment will
- * materialize on its next pass.
- */
-type IndexChange = Readonly<{
-    type: ChangeType;
-    /** Index name (the diffing identity key). */
-    name: string;
-    /**
-     * Whether this index is on a node, edge, or vector field. Vector
-     * index changes flow through the same diff classification as
-     * relational ones.
-     */
-    entity: IndexEntity;
-    severity: ChangeSeverity;
-    details: string;
-    before?: IndexDeclaration | undefined;
-    after?: IndexDeclaration | undefined;
-}>;
-/**
- * A change to the persisted graph-extension document.
- *
- * Graph-extension document changes are committed only through the
- * graph-extension lifecycle verbs (`evolve` and `removeKinds`), so the
- * extension-slice change itself is `safe`-severity. The detailed
- * per-kind effect is captured in the corresponding node/edge/ontology
- * changes the merged document produced.
- */
-type ExtensionChange = Readonly<{
-    type: ChangeType;
-    severity: ChangeSeverity;
-    details: string;
-}>;
-/**
- * Change to the soft-deprecated kind set. `safe`-severity by
- * construction — deprecation is a metadata signal that doesn't gate
- * reads, writes, or queries. The `added` and `removed` arrays carry
- * the per-name deltas so consumers can render granular diffs.
- */
-type DeprecatedKindsChange = Readonly<{
-    added: readonly string[];
-    removed: readonly string[];
-    severity: ChangeSeverity;
-    details: string;
-}>;
-/**
- * A complete diff between two schema versions.
- */
-type SchemaDiff = Readonly<{
-    fromVersion: number;
-    toVersion: number;
-    /** Changes to node definitions */
-    nodes: readonly NodeChange[];
-    /** Changes to edge definitions */
-    edges: readonly EdgeChange[];
-    /** Changes to ontology */
-    ontology: readonly OntologyChange[];
-    /** Change to the graph-level identity capability, if any. */
-    identity?: IdentityChange;
-    /** Changes to index declarations */
-    indexes: readonly IndexChange[];
-    /**
-     * Change to the graph-extension document, if any. `undefined` when
-     * the slice is unchanged on both sides (the common case).
-     */
-    extension?: ExtensionChange;
-    /**
-     * Change to the soft-deprecated kind set, if any. `undefined` when
-     * the set is unchanged on both sides.
-     */
-    deprecatedKinds?: DeprecatedKindsChange;
-    /** Whether any breaking changes exist */
-    hasBreakingChanges: boolean;
-    /** Whether the change is backwards compatible (no breaking changes) */
-    isBackwardsCompatible: boolean;
-    /** Whether any changes exist at all */
-    hasChanges: boolean;
-    /** Summary of changes */
-    summary: string;
-}>;
-/**
- * Computes the diff between two schema versions.
- *
- * @param before - The previous schema version
- * @param after - The new schema version
- * @returns A diff describing all changes
- */
-declare function computeSchemaDiff(before: SerializedSchema, after: SerializedSchema): SchemaDiff;
-/**
- * Checks if a schema change is backwards compatible.
- *
- * A change is backwards compatible if:
- * - No nodes or edges were removed
- * - No required properties were added
- * - No existing properties were removed
- */
-declare function isBackwardsCompatible(diff: SchemaDiff): boolean;
-/**
- * How a proposed graph relates to the committed schema.
- *
- * - `identical` — a semantic no-op; committing it changes nothing.
- * - `additive` — changes exist and are all backwards compatible.
- * - `incompatible` — at least one breaking change; needs a deliberate
- *   migration decision.
- */
-type SchemaChangeClassification = "identical" | "additive" | "incompatible";
-/**
- * Classifies a schema diff into the three outcomes a caller actually branches
- * on. Pure — no I/O, no DDL. Pair with `getSchemaChanges(backend, graph)` (or
- * `store.schemaChanges()`) to pre-flight a proposal *before* touching a
- * privileged, migration-gated path.
- */
-declare function classifySchemaChanges(diff: SchemaDiff): SchemaChangeClassification;
-/**
- * Gets a list of actions needed for migration.
- */
-declare function getMigrationActions(diff: SchemaDiff): readonly string[];
-
-/**
- * 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 ChangeSeverity as C, type DeprecatedKindsChange as D, type EdgeChange as E, type IdentityChange as I, type MaterializeIndexesResult as M, type NodeChange as N, type OntologyChange as O, type SchemaDiff as S, type ChangeType as a, type ExtensionChange as b, type IndexChange as c, type SchemaChangeClassification as d, classifySchemaChanges as e, computeSchemaDiff as f, getMigrationActions as g, type MaterializeIndexesEntry as h, isBackwardsCompatible as i, type MaterializeIndexesOptions as j, type MaterializeSystemIndexesOptions as k };

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

@@ -1,266 +0,0 @@
-import { c6 as SerializedNodeDef, c4 as SerializedEdgeDef, ba as IndexEntity, I as IndexDeclaration, c9 as SerializedSchema } from './types-CWg4dTjj.cjs';
-
-/**
- * Schema migration utilities.
- *
- * Provides diff detection between schema versions to identify
- * what has changed and what migrations might be needed.
- */
-
-/**
- * Types of changes that can occur in a schema.
- */
-type ChangeType = "added" | "removed" | "modified" | "renamed";
-/**
- * Severity of a change for migration purposes.
- */
-type ChangeSeverity = "safe" | "warning" | "breaking";
-/**
- * A change to a node definition.
- */
-type NodeChange = Readonly<{
-    type: ChangeType;
-    kind: string;
-    severity: ChangeSeverity;
-    details: string;
-    before?: SerializedNodeDef | undefined;
-    after?: SerializedNodeDef | undefined;
-}>;
-/**
- * A change to an edge definition.
- */
-type EdgeChange = Readonly<{
-    type: ChangeType;
-    kind: string;
-    severity: ChangeSeverity;
-    details: string;
-    before?: SerializedEdgeDef | undefined;
-    after?: SerializedEdgeDef | undefined;
-}>;
-/**
- * A change to the ontology.
- */
-type OntologyChange = Readonly<{
-    type: ChangeType;
-    entity: "metaEdge" | "relation";
-    name: string;
-    severity: ChangeSeverity;
-    details: string;
-}>;
-/** A durable graph-level Operational Identity capability change. */
-type IdentityChange = Readonly<{
-    type: ChangeType;
-    severity: ChangeSeverity;
-    details: string;
-}>;
-/**
- * A change to an index declaration.
- *
- * Index changes are always `safe`-severity: index DDL is materialized
- * separately and never blocks schema-version commits or migrations.
- * Adding, removing, or modifying an index never invalidates existing
- * data — it only changes which physical indexes the deployment will
- * materialize on its next pass.
- */
-type IndexChange = Readonly<{
-    type: ChangeType;
-    /** Index name (the diffing identity key). */
-    name: string;
-    /**
-     * Whether this index is on a node, edge, or vector field. Vector
-     * index changes flow through the same diff classification as
-     * relational ones.
-     */
-    entity: IndexEntity;
-    severity: ChangeSeverity;
-    details: string;
-    before?: IndexDeclaration | undefined;
-    after?: IndexDeclaration | undefined;
-}>;
-/**
- * A change to the persisted graph-extension document.
- *
- * Graph-extension document changes are committed only through the
- * graph-extension lifecycle verbs (`evolve` and `removeKinds`), so the
- * extension-slice change itself is `safe`-severity. The detailed
- * per-kind effect is captured in the corresponding node/edge/ontology
- * changes the merged document produced.
- */
-type ExtensionChange = Readonly<{
-    type: ChangeType;
-    severity: ChangeSeverity;
-    details: string;
-}>;
-/**
- * Change to the soft-deprecated kind set. `safe`-severity by
- * construction — deprecation is a metadata signal that doesn't gate
- * reads, writes, or queries. The `added` and `removed` arrays carry
- * the per-name deltas so consumers can render granular diffs.
- */
-type DeprecatedKindsChange = Readonly<{
-    added: readonly string[];
-    removed: readonly string[];
-    severity: ChangeSeverity;
-    details: string;
-}>;
-/**
- * A complete diff between two schema versions.
- */
-type SchemaDiff = Readonly<{
-    fromVersion: number;
-    toVersion: number;
-    /** Changes to node definitions */
-    nodes: readonly NodeChange[];
-    /** Changes to edge definitions */
-    edges: readonly EdgeChange[];
-    /** Changes to ontology */
-    ontology: readonly OntologyChange[];
-    /** Change to the graph-level identity capability, if any. */
-    identity?: IdentityChange;
-    /** Changes to index declarations */
-    indexes: readonly IndexChange[];
-    /**
-     * Change to the graph-extension document, if any. `undefined` when
-     * the slice is unchanged on both sides (the common case).
-     */
-    extension?: ExtensionChange;
-    /**
-     * Change to the soft-deprecated kind set, if any. `undefined` when
-     * the set is unchanged on both sides.
-     */
-    deprecatedKinds?: DeprecatedKindsChange;
-    /** Whether any breaking changes exist */
-    hasBreakingChanges: boolean;
-    /** Whether the change is backwards compatible (no breaking changes) */
-    isBackwardsCompatible: boolean;
-    /** Whether any changes exist at all */
-    hasChanges: boolean;
-    /** Summary of changes */
-    summary: string;
-}>;
-/**
- * Computes the diff between two schema versions.
- *
- * @param before - The previous schema version
- * @param after - The new schema version
- * @returns A diff describing all changes
- */
-declare function computeSchemaDiff(before: SerializedSchema, after: SerializedSchema): SchemaDiff;
-/**
- * Checks if a schema change is backwards compatible.
- *
- * A change is backwards compatible if:
- * - No nodes or edges were removed
- * - No required properties were added
- * - No existing properties were removed
- */
-declare function isBackwardsCompatible(diff: SchemaDiff): boolean;
-/**
- * How a proposed graph relates to the committed schema.
- *
- * - `identical` — a semantic no-op; committing it changes nothing.
- * - `additive` — changes exist and are all backwards compatible.
- * - `incompatible` — at least one breaking change; needs a deliberate
- *   migration decision.
- */
-type SchemaChangeClassification = "identical" | "additive" | "incompatible";
-/**
- * Classifies a schema diff into the three outcomes a caller actually branches
- * on. Pure — no I/O, no DDL. Pair with `getSchemaChanges(backend, graph)` (or
- * `store.schemaChanges()`) to pre-flight a proposal *before* touching a
- * privileged, migration-gated path.
- */
-declare function classifySchemaChanges(diff: SchemaDiff): SchemaChangeClassification;
-/**
- * Gets a list of actions needed for migration.
- */
-declare function getMigrationActions(diff: SchemaDiff): readonly string[];
-
-/**
- * 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 ChangeSeverity as C, type DeprecatedKindsChange as D, type EdgeChange as E, type IdentityChange as I, type MaterializeIndexesResult as M, type NodeChange as N, type OntologyChange as O, type SchemaDiff as S, type ChangeType as a, type ExtensionChange as b, type IndexChange as c, type SchemaChangeClassification as d, classifySchemaChanges as e, computeSchemaDiff as f, getMigrationActions as g, type MaterializeIndexesEntry as h, isBackwardsCompatible as i, type MaterializeIndexesOptions as j, type MaterializeSystemIndexesOptions as k };