@nicia-ai/typegraph 0.24.1 → 0.25.0

package/dist/{manager-Vkz28eAC.d.cts → manager-BpjBW1JK.d.cts}

@@ -1,4 +1,5 @@
-import { r as NodeRegistration, f as EdgeRegistration, O as OntologyRelation, b as DeleteBehavior, T as TemporalMode, N as NodeType, A as AnyEdgeType, n as GraphDefaults, W as SerializedNodeDef, X as SerializedEdgeDef, $ as SerializedSchema, G as GraphBackend, a4 as SchemaVersionRow } from './types-Qk2l3IkQ.cjs';
+import { b as NodeRegistration, E as EdgeRegistration, D as DeleteBehavior, T as TemporalMode, G as GraphExtension, N as NodeType, A as AnyEdgeType, c as GraphDefaults, I as IndexEntity } from './extension-types-D07e_NTw.cjs';
+import { O as OntologyRelation, I as IndexDeclaration, S as SerializedNodeDef, d as SerializedEdgeDef, h as SerializedSchema, y as SchemaVersionRow, G as GraphBackend } from './types--0EslBx5.cjs';
 
 /** Brand key for GraphDef */
 declare const GRAPH_DEF_BRAND: "__graphDef";
@@ -31,6 +32,23 @@ type GraphDefConfig<TNodes extends Record<string, NodeRegistration>, TEdges exte
     ontology?: TOntology;
     /** Graph-wide defaults */
     defaults?: GraphDefaults;
+    /**
+     * Index declarations attached to this graph.
+     *
+     * Accepts the outputs of `defineNodeIndex` / `defineEdgeIndex` (which
+     * already return `IndexDeclaration` values) or pre-built declarations
+     * reconstructed from a stored schema or graph extension.
+     *
+     * Validated at definition time: every index must reference a `kind`
+     * that exists in `nodes` / `edges`, and index `name`s must be unique
+     * within the graph.
+     *
+     * Index DDL is **not** generated by `defineGraph`. Indexes flow into
+     * `SerializedSchema.indexes` so they can later be materialized via
+     * `store.materializeIndexes()` — lifting the storage concern out of
+     * the schema-version commit path.
+     */
+    indexes?: readonly IndexDeclaration[];
 }>;
 /**
  * A graph definition.
@@ -48,6 +66,35 @@ type GraphDef<TNodes extends Record<string, NodeRegistration> = Record<string, N
         onNodeDelete: DeleteBehavior;
         temporalMode: TemporalMode;
     }>;
+    /**
+     * Index declarations attached to this graph. Preserves whatever the
+     * caller passed to `defineGraph` (including an explicit empty array)
+     * for introspection purposes.
+     *
+     * The serialized canonical form is order-canonicalized (sorted by
+     * `name`) and treats `undefined` and `[]` as the same "no slice" form
+     * — an empty array does not bump the schema hash, since indexes are
+     * an unordered set keyed by name and `[]` carries no semantic meaning
+     * that an absent slice doesn't.
+     */
+    indexes: readonly IndexDeclaration[] | undefined;
+    /**
+     * Graph extension this graph was merged with, if any. Set by
+     * `mergeGraphExtension`; never set by `defineGraph` directly.
+     * Exists solely so re-serialization is stable — the rest of the
+     * system reads the merged kinds through `nodes` / `edges` /
+     * `ontology` and never inspects this field. Absent on graphs that
+     * have never been extended; legacy graphs hash byte-identically.
+     */
+    extension: GraphExtension | undefined;
+    /**
+     * Soft-deprecated kind names attached to this graph. Set by the
+     * loader from the persisted schema and by `store.deprecateKinds(...)`
+     * / `store.undeprecateKinds(...)`. A purely informational signal
+     * surfaced for introspection — does not gate reads, writes, or
+     * queries. Defaults to the empty set on freshly-defined graphs.
+     */
+    deprecatedKinds: ReadonlySet<string>;
 }>;
 /**
  * Extract node kind names from a GraphDef.
@@ -314,6 +361,56 @@ type OntologyChange = Readonly<{
     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.
  */
@@ -326,6 +423,18 @@ type SchemaDiff = Readonly<{
     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) */
@@ -367,12 +476,59 @@ declare function getMigrationActions(diff: SchemaDiff): readonly string[];
  * - Error reporting for breaking changes
  */
 
+/**
+ * Parses and validates a serialized schema document from the database.
+ *
+ * Uses the Zod schema to validate the full nested structure, catching
+ * corruption, incompatible schema versions, or truncated JSON at the
+ * parse boundary rather than letting invalid data propagate silently.
+ */
+declare function parseSerializedSchema(json: string): SerializedSchema;
+/**
+ * Reads the active schema row, bootstrapping the base tables on the
+ * first call against an empty database.
+ */
+declare function loadActiveSchemaWithBootstrap(backend: GraphBackend, graphId: string): Promise<SchemaVersionRow | undefined>;
+/**
+ * Reads the active schema, parses it, and folds any persisted graph-extension
+ * document into the supplied compile-time graph. Returns the
+ * merged graph alongside the prefetched row + parsed schema so the
+ * caller can pass them through to `ensureSchema` without paying for a
+ * second `getActiveSchema` round trip or a second
+ * `serializedSchemaZod` walk.
+ *
+ * Throws `ConfigurationError` if the persisted graph-extension document
+ * references a compile-time kind that no longer exists (the
+ * startup-conflict case).
+ */
+declare function loadAndMergeGraphExtensionDocument<G extends GraphDef>(backend: GraphBackend, graph: G): Promise<Readonly<{
+    graph: G;
+    activeRow: SchemaVersionRow | undefined;
+    storedSchema: SerializedSchema | undefined;
+}>>;
+/**
+ * Returns a graph carrying the supplied deprecated-kind names. Used by
+ * the loader to propagate `SerializedSchema.deprecatedKinds` onto the
+ * `GraphDef` that the Store sees, and by `Store.deprecateKinds` /
+ * `Store.undeprecateKinds` to construct the next graph.
+ *
+ * Returns the original graph reference when the desired set already
+ * matches `graph.deprecatedKinds` — covers both the no-deprecations
+ * load path (empty equals empty) and the loader's restart-with-same-
+ * persisted-set hot path. Skips a Set allocation + spread + freeze.
+ */
+declare function applyDeprecatedKinds<G extends GraphDef>(graph: G, names: Iterable<string> | undefined): G;
 /**
  * Result of schema validation.
+ *
+ * The `initialized` and `migrated` statuses carry the committed
+ * `SchemaVersionRow` directly so callers building post-commit metadata
+ * (e.g. `Store.deprecateKinds`) can skip a `getActiveSchema` round-trip.
  */
 type SchemaValidationResult = {
     status: "initialized";
     version: number;
+    committedRow: SchemaVersionRow;
 } | {
     status: "unchanged";
     version: number;
@@ -381,6 +537,7 @@ type SchemaValidationResult = {
     fromVersion: number;
     toVersion: number;
     diff: SchemaDiff;
+    committedRow: SchemaVersionRow;
 } | {
     status: "pending";
     version: number;
@@ -431,11 +588,27 @@ type SchemaManagerOptions = Readonly<{
  * @returns The result of schema validation
  * @throws MigrationError if breaking changes detected and throwOnBreaking is true
  */
-declare function ensureSchema<G extends GraphDef>(backend: GraphBackend, graph: G, options?: SchemaManagerOptions): Promise<SchemaValidationResult>;
+declare function ensureSchema<G extends GraphDef>(backend: GraphBackend, graph: G, options?: SchemaManagerOptions & {
+    /**
+     * Pre-fetched active row + parsed stored schema. When the loader
+     * (`createStoreWithSchema`) has already paid for `getActiveSchema`
+     * and `parseSerializedSchema` to peek at `extension`, it
+     * passes the results through here so `ensureSchema` doesn't repeat
+     * the round trip + Zod walk on every Store boot.
+     */
+    preloaded?: Readonly<{
+        activeRow: SchemaVersionRow | undefined;
+        storedSchema: SerializedSchema | undefined;
+    }>;
+}): Promise<SchemaValidationResult>;
 /**
  * Initializes the schema for a new graph.
  *
- * Creates version 1 of the schema and marks it as active.
+ * Creates version 1 of the schema and marks it as active. Goes through
+ * the same `commitSchemaVersion` primitive as `migrateSchema` so the
+ * initial-commit race (two processes booting against an empty database
+ * simultaneously) resolves with `StaleVersionError` or idempotent
+ * success rather than a raw PK violation.
  *
  * @param backend - The database backend
  * @param graph - The graph definition
@@ -445,8 +618,12 @@ declare function initializeSchema<G extends GraphDef>(backend: GraphBackend, gra
 /**
  * Migrates the schema to match the current graph definition.
  *
- * This creates a new schema version and marks it as active.
- * The old version is preserved for history/rollback.
+ * Creates a new schema version and atomically activates it via the
+ * `commitSchemaVersion` backend primitive — insert and activate happen
+ * in a single transactional unit with optimistic compare-and-swap on
+ * the currently-active version. If another writer has advanced the
+ * active version since `currentVersion` was read, this throws
+ * `StaleVersionError`; the caller should refetch and retry.
  *
  * @param backend - The database backend
  * @param graph - The current graph definition
@@ -460,10 +637,16 @@ declare function migrateSchema<G extends GraphDef>(backend: GraphBackend, graph:
  * The target version must already exist in the version history.
  * This does not delete newer versions — it simply switches the active pointer.
  *
+ * Uses the `setActiveVersion` backend primitive, which performs the flip
+ * atomically with optimistic compare-and-swap on the currently-active
+ * version. Concurrent rollbacks or commits surface as
+ * `StaleVersionError`.
+ *
  * @param backend - The database backend
  * @param graphId - The graph ID
  * @param targetVersion - The version to roll back to
  * @throws MigrationError if the target version does not exist
+ * @throws StaleVersionError if another writer changed the active version concurrently
  */
 declare function rollbackSchema(backend: GraphBackend, graphId: string, targetVersion: number): Promise<void>;
 /**
@@ -491,4 +674,4 @@ declare function isSchemaInitialized(backend: GraphBackend, graphId: string): Pr
  */
 declare function getSchemaChanges<G extends GraphDef>(backend: GraphBackend, graph: G): Promise<SchemaDiff | undefined>;
 
-export { type AllEdgeTypes as A, type ChangeSeverity as C, type EdgeKinds as E, type GraphDef as G, KindRegistry as K, type MigrationHookContext as M, type NodeKinds as N, type OntologyChange as O, type SchemaManagerOptions as S, type AllNodeTypes as a, type GetEdgeType as b, type GetNodeType as c, type SchemaValidationResult as d, defineGraph as e, getNodeKinds as f, getEdgeKinds as g, type ChangeType as h, isGraphDef as i, type EdgeChange as j, type NodeChange as k, type SchemaDiff as l, computeSchemaDiff as m, ensureSchema as n, getActiveSchema as o, getMigrationActions as p, getSchemaChanges as q, initializeSchema as r, isBackwardsCompatible as s, isSchemaInitialized as t, migrateSchema as u, rollbackSchema as v };
+export { type AllEdgeTypes as A, isGraphDef as B, type ChangeSeverity as C, type DeprecatedKindsChange as D, type EdgeChange as E, type GraphDef as G, type IndexChange as I, KindRegistry as K, type MigrationHookContext as M, type NodeChange as N, type OntologyChange as O, type SchemaDiff as S, type ChangeType as a, type ExtensionChange as b, type SchemaManagerOptions as c, type SchemaValidationResult as d, applyDeprecatedKinds as e, computeSchemaDiff as f, ensureSchema as g, getActiveSchema as h, getMigrationActions as i, getSchemaChanges as j, initializeSchema as k, isBackwardsCompatible as l, isSchemaInitialized as m, loadActiveSchemaWithBootstrap as n, loadAndMergeGraphExtensionDocument as o, migrateSchema as p, parseSerializedSchema as q, rollbackSchema as r, type AllNodeTypes as s, type EdgeKinds as t, type GetEdgeType as u, type GetNodeType as v, type NodeKinds as w, defineGraph as x, getEdgeKinds as y, getNodeKinds as z };

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

@@ -0,0 +1,68 @@
+import { I as IndexEntity } from './extension-types-D07e_NTw.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`). v1 surfaces this as a `failed`
+ *   result; the operator must drop the invalid index manually before
+ *   retry.
+ */
+
+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;
+}>;
+/**
+ * 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[];
+}>;
+
+export type { MaterializeIndexesResult as M, MaterializeIndexesEntry as a, MaterializeIndexesOptions as b };

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

@@ -0,0 +1,68 @@
+import { I as IndexEntity } from './extension-types-D07e_NTw.js';
+
+/**
+ * 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`). v1 surfaces this as a `failed`
+ *   result; the operator must drop the invalid index manually before
+ *   retry.
+ */
+
+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;
+}>;
+/**
+ * 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[];
+}>;
+
+export type { MaterializeIndexesResult as M, MaterializeIndexesEntry as a, MaterializeIndexesOptions as b };

package/dist/profiler/index.cjs

@@ -1,6 +1,8 @@
 'use strict';
 
-var chunkUVZHTBZ5_cjs = require('../chunk-UVZHTBZ5.cjs');
+var chunkEK6RJ373_cjs = require('../chunk-EK6RJ373.cjs');
+require('../chunk-X3244EKP.cjs');
+var chunk7V335GHG_cjs = require('../chunk-7V335GHG.cjs');
 
 // src/profiler/ast-extractor.ts
 function extractPropertyAccesses(ast) {
@@ -175,7 +177,7 @@ function extractFromSelectiveField(field, ast) {
     kindNames: resolved.kindNames,
     target: {
       __type: "prop",
-      pointer: chunkUVZHTBZ5_cjs.jsonPointer(field.field.split("."))
+      pointer: chunk7V335GHG_cjs.jsonPointer(field.field.split("."))
     },
     context: "select"
   };
@@ -215,7 +217,7 @@ function extractTargetFromFieldRef(ref) {
     return { __type: "prop", pointer: ref.jsonPointer };
   }
   if (ref.path.length > 1 && ref.path[0] === "props") {
-    return { __type: "prop", pointer: chunkUVZHTBZ5_cjs.jsonPointer(ref.path.slice(1)) };
+    return { __type: "prop", pointer: chunk7V335GHG_cjs.jsonPointer(ref.path.slice(1)) };
   }
   if (ref.path.length === 1) {
     return { __type: "system", field: ref.path[0] };
@@ -256,7 +258,7 @@ function keyToPath(key) {
       target: { __type: "system", field: systemField }
     };
   }
-  const pointer = chunkUVZHTBZ5_cjs.normalizeJsonPointer(
+  const pointer = chunk7V335GHG_cjs.normalizeJsonPointer(
     targetPart
   );
   return {
@@ -516,7 +518,7 @@ var QueryProfiler = class {
       );
     }
     this.#attached = true;
-    this.#schemaIntrospector = chunkUVZHTBZ5_cjs.createSchemaIntrospector(
+    this.#schemaIntrospector = chunkEK6RJ373_cjs.createSchemaIntrospector(
       buildNodeSchemaMap(store.graph),
       buildEdgeSchemaMap(store.graph)
     );
@@ -677,7 +679,7 @@ function getNodeEnv() {
   return process.env.NODE_ENV;
 }
 function hasPointerInSchema(schemaIntrospector, entityType, kindName, pointer) {
-  const segments = chunkUVZHTBZ5_cjs.parseJsonPointer(pointer);
+  const segments = chunk7V335GHG_cjs.parseJsonPointer(pointer);
   const [first, ...rest] = segments;
   if (!first) {
     return false;
@@ -690,9 +692,9 @@ function hasPointerInSchema(schemaIntrospector, entityType, kindName, pointer) {
     return true;
   }
   try {
-    const resolved = chunkUVZHTBZ5_cjs.resolveFieldTypeInfoAtJsonPointer(
+    const resolved = chunkEK6RJ373_cjs.resolveFieldTypeInfoAtJsonPointer(
       rootInfo,
-      chunkUVZHTBZ5_cjs.jsonPointer(rest)
+      chunk7V335GHG_cjs.jsonPointer(rest)
     );
     return resolved !== void 0;
   } catch (error) {