@nicia-ai/typegraph 0.41.0 → 0.42.1

package/dist/interchange/index.d.cts

@@ -1,12 +1,11 @@
 import { z } from 'zod';
-import { G as GraphDef } from '../define-graph-XyJheaFm.cjs';
-import { a as Store } from '../store-view-PCT7vTKH.cjs';
-import '../extension-types-BLEVH4SG.cjs';
-import '../types-ho4DJJb_.cjs';
-import '../temporal-Dn_JADWY.cjs';
-import '../manager-Dm6MCYO7.cjs';
-import '../searchable-aUaKh3_r.cjs';
-import '../materialize-indexes-ExQ6OrAh.cjs';
+import { G as GraphDef } from '../define-graph-Byslw2OO.cjs';
+import { a as Store } from '../store-view-CNcOG8bQ.cjs';
+import '../types-Dh-EgT-w.cjs';
+import '../temporal-CMpigMCW.cjs';
+import '../manager-U9_zopqr.cjs';
+import '../materialize-indexes-DzMCetZe.cjs';
+import '../searchable-B4mUXZT6.cjs';
 
 /**
  * Graph interchange format types.
@@ -89,8 +88,8 @@ type ConflictStrategy = z.infer<typeof ConflictStrategySchema>;
  * - `allow`: Pass through to storage (relies on backend behavior)
  */
 declare const UnknownPropertyStrategySchema: z.ZodEnum<{
-    allow: "allow";
     error: "error";
+    allow: "allow";
     strip: "strip";
 }>;
 type UnknownPropertyStrategy = z.infer<typeof UnknownPropertyStrategySchema>;
@@ -104,8 +103,8 @@ declare const ImportOptionsSchema: z.ZodObject<{
         update: "update";
     }>;
     onUnknownProperty: z.ZodDefault<z.ZodEnum<{
-        allow: "allow";
         error: "error";
+        allow: "allow";
         strip: "strip";
     }>>;
     validateReferences: z.ZodDefault<z.ZodBoolean>;

package/dist/interchange/index.d.ts

@@ -1,12 +1,11 @@
 import { z } from 'zod';
-import { G as GraphDef } from '../define-graph-BSviZubs.js';
-import { a as Store } from '../store-view-BDjGFjpN.js';
-import '../extension-types-BLEVH4SG.js';
-import '../types-D-vOo_pM.js';
-import '../temporal-CyFsSPe8.js';
-import '../manager-C7iC5bk_.js';
-import '../searchable-Cet4Oztt.js';
-import '../materialize-indexes-D4iei4Kp.js';
+import { G as GraphDef } from '../define-graph-DBFnc7u_.js';
+import { a as Store } from '../store-view-6C2vTWqf.js';
+import '../types-Dh-EgT-w.js';
+import '../temporal-BtrTYTiB.js';
+import '../manager-Dl0-er1G.js';
+import '../materialize-indexes-BM3u0aXE.js';
+import '../searchable-C7jmPNLT.js';
 
 /**
  * Graph interchange format types.
@@ -89,8 +88,8 @@ type ConflictStrategy = z.infer<typeof ConflictStrategySchema>;
  * - `allow`: Pass through to storage (relies on backend behavior)
  */
 declare const UnknownPropertyStrategySchema: z.ZodEnum<{
-    allow: "allow";
     error: "error";
+    allow: "allow";
     strip: "strip";
 }>;
 type UnknownPropertyStrategy = z.infer<typeof UnknownPropertyStrategySchema>;
@@ -104,8 +103,8 @@ declare const ImportOptionsSchema: z.ZodObject<{
         update: "update";
     }>;
     onUnknownProperty: z.ZodDefault<z.ZodEnum<{
-        allow: "allow";
         error: "error";
+        allow: "allow";
         strip: "strip";
     }>>;
     validateReferences: z.ZodDefault<z.ZodBoolean>;

package/dist/interchange/index.js

@@ -1,23 +1,23 @@
-export { ConflictStrategySchema, ExportOptionsSchema, ExportStreamOptionsSchema, FORMAT_VERSION, GraphDataHeaderSchema, GraphDataSchema, GraphDataSourceSchema, GraphInterchangeChunkSchema, ImportErrorSchema, ImportOptionsSchema, ImportResultSchema, InterchangeEdgeSchema, InterchangeNodeSchema, UnknownPropertyStrategySchema, exportGraph, exportGraphStream, importGraph, importGraphStream } from '../chunk-XMEYZYGE.js';
-import '../chunk-53BSOG3O.js';
-import { storeBackend } from '../chunk-JHK6NPFV.js';
+export { ConflictStrategySchema, ExportOptionsSchema, ExportStreamOptionsSchema, FORMAT_VERSION, GraphDataHeaderSchema, GraphDataSchema, GraphDataSourceSchema, GraphInterchangeChunkSchema, ImportErrorSchema, ImportOptionsSchema, ImportResultSchema, InterchangeEdgeSchema, InterchangeNodeSchema, UnknownPropertyStrategySchema, exportGraph, exportGraphStream, importGraph, importGraphStream } from '../chunk-WYQILW5V.js';
+import '../chunk-6NB73BXV.js';
+import { storeBackend } from '../chunk-EVFL2ZY5.js';
 import '../chunk-35S6P5ZU.js';
-import '../chunk-YYLMXERH.js';
-import '../chunk-L5ET7FYQ.js';
-import '../chunk-QOHTVDHU.js';
-import '../chunk-ZE6NVENI.js';
+import '../chunk-CDYRPI5U.js';
+import '../chunk-UZLEQFTV.js';
+import '../chunk-2OOY4OYT.js';
+import '../chunk-O3USVVWS.js';
 import '../chunk-UR7W5YQK.js';
-import '../chunk-UUIBACKJ.js';
-import '../chunk-PH4IJ3V5.js';
-import '../chunk-3SHAUJRB.js';
+import '../chunk-CUPJL6TS.js';
+import '../chunk-3V6D5DEC.js';
+import '../chunk-GT7NEXSU.js';
 import '../chunk-2EBMPJBO.js';
-import '../chunk-Y5UC3IXF.js';
-import '../chunk-6N7QBIWN.js';
+import '../chunk-42XYPKZU.js';
+import '../chunk-M4GYQF2H.js';
 import '../chunk-SNXVDZAJ.js';
 import '../chunk-QMQLUA66.js';
 import { getSearchableFields, resolveGraphVectorSlots } from '../chunk-PC2UBAUB.js';
-import '../chunk-XZA3Y4YH.js';
-import { TrustedImportError } from '../chunk-DPNA466P.js';
+import '../chunk-4WYFRACU.js';
+import { TrustedImportError } from '../chunk-OYJSYDIH.js';
 import '../chunk-G6Q5UM7U.js';
 
 // src/interchange/trusted-import.ts

package/dist/{manager-C7iC5bk_.d.ts → manager-Dl0-er1G.d.ts}

@@ -1,6 +1,6 @@
-import { a as NodeType, A as AnyEdgeType, I as IndexEntity } from './extension-types-BLEVH4SG.js';
-import { q as SerializedNodeDef, r as SerializedEdgeDef, I as IndexDeclaration, v as SerializedSchema, C as SchemaVersionRow, G as GraphBackend } from './types-D-vOo_pM.js';
-import { G as GraphDef } from './define-graph-BSviZubs.js';
+import { a as NodeType, b as AnyEdgeType, v as SchemaVersionRow, w as GraphBackend, x as SerializedSchema } from './types-Dh-EgT-w.js';
+import { G as GraphDef } from './define-graph-DBFnc7u_.js';
+import { S as SchemaDiff } from './materialize-indexes-BM3u0aXE.js';
 
 /**
  * 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,6 +400,23 @@ 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.
@@ -577,4 +442,4 @@ declare function getSchemaChanges<G extends GraphDef>(backend: GraphBackend, gra
  */
 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, getCommittedSchemaVersion as j, getMigrationActions as k, getSchemaChanges as l, initializeSchema as m, isBackwardsCompatible as n, isSchemaInitialized as o, loadActiveSchemaWithBootstrap as p, loadAndMergeGraphExtensionDocument as q, migrateSchema as r, parseSerializedSchema as s, rollbackSchema as t };
+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/{manager-Dm6MCYO7.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 { q as SerializedNodeDef, r as SerializedEdgeDef, I as IndexDeclaration, v as SerializedSchema, C as SchemaVersionRow, G as GraphBackend } from './types-ho4DJJb_.cjs';
-import { G as GraphDef } from './define-graph-XyJheaFm.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,6 +400,23 @@ 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.
@@ -577,4 +442,4 @@ declare function getSchemaChanges<G extends GraphDef>(backend: GraphBackend, gra
  */
 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, getCommittedSchemaVersion as j, getMigrationActions as k, getSchemaChanges as l, initializeSchema as m, isBackwardsCompatible as n, isSchemaInitialized as o, loadActiveSchemaWithBootstrap as p, loadAndMergeGraphExtensionDocument as q, migrateSchema as r, parseSerializedSchema as s, rollbackSchema as t };
+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 };