@nicia-ai/typegraph 0.40.0 → 0.42.0

package/dist/{manager-mqee5MVB.d.cts → manager-U9_zopqr.d.cts}

@@ -1,6 +1,6 @@
-import { a as NodeType, A as AnyEdgeType, I as IndexEntity } from './extension-types-BLEVH4SG.cjs';
-import { s as SerializedNodeDef, t as SerializedEdgeDef, I as IndexDeclaration, q as SerializedSchema, C as SchemaVersionRow, G as GraphBackend } from './types-C5pZeKTl.cjs';
-import { G as GraphDef } from './define-graph-Cv3CFwKm.cjs';
+import { a as NodeType, b as AnyEdgeType, v as SchemaVersionRow, w as GraphBackend, x as SerializedSchema } from './types-Dh-EgT-w.cjs';
+import { G as GraphDef } from './define-graph-Byslw2OO.cjs';
+import { S as SchemaDiff } from './materialize-indexes-DzMCetZe.cjs';
 
 /**
  * KindRegistry holds precomputed closures for ontological reasoning.
@@ -152,158 +152,6 @@ declare class KindRegistry {
     getEdgeType(name: string): AnyEdgeType | undefined;
 }
 
-/**
- * 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 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[];
-    /** 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;
-/**
- * Gets a list of actions needed for migration.
- */
-declare function getMigrationActions(diff: SchemaDiff): readonly string[];
-
 /**
  * Schema manager for TypeGraph.
  *
@@ -552,5 +400,46 @@ declare function isSchemaInitialized(backend: GraphBackend, graphId: string): Pr
  * @returns The diff, or undefined if schema not initialized
  */
 declare function getSchemaChanges<G extends GraphDef>(backend: GraphBackend, graph: G): Promise<SchemaDiff | undefined>;
+/**
+ * Whether committing `graph` would require a schema migration — a SELECT-only
+ * pre-flight with no DDL and no writes.
+ *
+ * Returns `true` when the schema has not been initialized yet (the privileged
+ * bootstrap is required) and when the committed schema is behind `graph`.
+ * This is the predicate a least-privilege runtime checks to route to the
+ * privileged path *before* a write discovers the migration wall mid-request.
+ *
+ * For the additive-vs-incompatible distinction, use `getSchemaChanges` and
+ * {@link classifySchemaChanges} instead — this collapses both to `true`.
+ *
+ * @param backend - The database backend
+ * @param graph - The current graph definition
+ * @returns Whether a privileged migration/bootstrap is required.
+ */
+declare function requiresMigration<G extends GraphDef>(backend: GraphBackend, graph: G): Promise<boolean>;
+/**
+ * Reads the committed schema version for a graph in a single round-trip — no
+ * schema reconcile, no diff, no materialization-marker reads.
+ *
+ * This is the cross-isolate invalidation probe for a cached reconciled schema:
+ * compare the returned version against the one a verified open recorded
+ * (`store.reconciledSchema.version`); when it has moved, another process
+ * committed a schema change and the cached reconciliation must be refreshed via
+ * `createVerifiedAdapterStore`. One read replaces the three-query verified open
+ * on the steady-state (unchanged) path — the round-trip that saturated the
+ * connection pool under fan-out.
+ *
+ * It reads the active schema *row* (via `backend.getActiveSchema`), so the
+ * committed `schema_doc` is transferred and normalized even though only the
+ * version is used. A version-only backend query would shrink the payload
+ * further; it is a backward-compatible follow-up, not required for the
+ * round-trip win above.
+ *
+ * @param backend - The database backend
+ * @param graphId - The graph ID
+ * @returns The active committed version, or `undefined` if the schema has not
+ *   been initialized for this graph.
+ */
+declare function getCommittedSchemaVersion(backend: GraphBackend, graphId: string): Promise<number | undefined>;
 
-export { type ChangeSeverity as C, type DeprecatedKindsChange as D, type EdgeChange as E, type IndexChange as I, KindRegistry as K, type MigrationHookContext as M, type NodeChange as N, type OntologyChange as O, type SchemaManagerOptions as S, type ChangeType as a, type ExtensionChange as b, type SchemaDiff as c, type SchemaValidationResult as d, applyDeprecatedKinds as e, assertSchemaCurrent as f, computeSchemaDiff as g, ensureSchema as h, getActiveSchema as i, getMigrationActions as j, getSchemaChanges as k, initializeSchema as l, isBackwardsCompatible as m, isSchemaInitialized as n, loadActiveSchemaWithBootstrap as o, loadAndMergeGraphExtensionDocument as p, migrateSchema as q, parseSerializedSchema as r, rollbackSchema as s };
+export { KindRegistry as K, type MigrationHookContext as M, type SchemaManagerOptions as S, type SchemaValidationResult as a, applyDeprecatedKinds as b, assertSchemaCurrent as c, getCommittedSchemaVersion as d, ensureSchema as e, getSchemaChanges as f, getActiveSchema as g, isSchemaInitialized as h, initializeSchema as i, loadAndMergeGraphExtensionDocument as j, rollbackSchema as k, loadActiveSchemaWithBootstrap as l, migrateSchema as m, parseSerializedSchema as p, requiresMigration as r };

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

@@ -0,0 +1,258 @@
+import { y as SerializedNodeDef, z as SerializedEdgeDef, C as IndexEntity, I as IndexDeclaration, x as SerializedSchema } from './types-Dh-EgT-w.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 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[];
+    /** 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 IndexChange 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 SchemaChangeClassification as c, classifySchemaChanges as d, computeSchemaDiff as e, type MaterializeIndexesEntry as f, getMigrationActions as g, type MaterializeIndexesOptions as h, isBackwardsCompatible as i, type MaterializeSystemIndexesOptions as j };