@utaba/deep-memory 0.15.0 → 0.17.0

package/dist/index.d.cts

@@ -1,15 +1,15 @@
-import { G as GovernanceConfig, M as MemoryVocabulary, x as ResolvedVocabulary, C as CreateEntityInput, y as ValidationResult, U as UpdateEntityInput, z as CreateRelationshipInput, A as EntityTypeDefinition, F as VocabularyProposal, H as VocabularyProposalResult, J as ProvenanceContext, K as Provenance, E as Entity, D as DetailLevel, a as EntitySummary, b as EntityBrief, L as FindEntitiesQuery, e as PaginatedResult, N as DeleteEntitiesResult, O as ReembedResult, Q as Relationship, T as RemoveRelationshipsResult, P as PropertyFilter, R as RelationshipSummary, W as GraphResult, X as ExploreOptions, Y as Neighborhood, Z as PathOptions, _ as PathResult, $ as ConceptSearchOptions, a0 as ScoredEntity, a1 as TimelineOptions, a2 as TimelineResult, i as RepositoryStats, a3 as ValidateEntitiesOptions, a4 as EntityValidationPage, a5 as ValidateRelationshipsOptions, a6 as RelationshipValidationPage, a7 as RepositoryConfig, c as StoredRepository, d as RepositoryFilter, a8 as RepositorySummary, g as RepositoryUpdate, a9 as ExportOptions, aa as ExportArchive, ab as ImportOptions, ac as ImportResult, ad as ExportStreamItem, ae as ImportStreamHeader, I as ImportChunk, k as StoredEntity, S as StorageRepositoryConfig, f as StoredRepositorySummary, h as DeleteProgressCallback, j as PaginationOptions, V as VocabularyChangeRecord, l as StoredEntityUpdate, m as StorageFindQuery, n as StoredRelationship, o as RelationshipQueryOptions, p as StorageExploreOptions, q as StorageNeighborhood, r as StoragePathOptions, s as StoragePathResult, t as StorageTimelineOptions, u as StorageTimelineResult, v as ExportChunk, B as BulkImportOptions, w as BulkImportResult, af as SearchOptions, ag as SearchHit } from './portability-P1hL-bOa.cjs';
-export { ah as AdaptiveConcurrencyAdjustEvent, ai as AdaptiveConcurrencyAdjustReason, aj as AdaptiveConcurrencyHandle, ak as AdaptiveConcurrencyOptions, al as EnrichedRelationship, am as EntityMap, an as EntityTypeInput, ao as EntityValidationIssue, ap as ExportLegalMetadata, aq as ExportManifest, ar as ExportPipelineMetadata, as as GetEntitiesOptions, at as GetEntityOptions, au as GovernanceMode, av as ImportWarning, aw as NeighborhoodCenter, ax as NeighborhoodGroup, ay as NeighborhoodLayer, az as Path, aA as PropertySchema, aB as PropertyType, aC as ProvenanceFilter, aD as RelationshipDirection, aE as RelationshipTypeDefinition, aF as RelationshipTypeInput, aG as RelationshipValidationIssue, aH as RepositoryMetadata, aI as StorageNeighborhoodGroup, aJ as StorageNeighborhoodLayer, aK as StoragePath, aL as StorageTimelineEvent, aM as TimelineEntityRef, aN as TimelineEvent, aO as TimelineRelationshipDetail, aP as VocabularyInput } from './portability-P1hL-bOa.cjs';
+import { z as GovernanceConfig, O as MemoryVocabulary, ai as ResolvedVocabulary, e as CreateEntityInput, aL as ValidationResult, aI as UpdateEntityInput, f as CreateRelationshipInput, m as EntityTypeDefinition, aO as VocabularyProposal, aP as VocabularyProposalResult, a0 as ProvenanceContext, $ as Provenance, i as Entity, h as DetailLevel, l as EntitySummary, j as EntityBrief, F as FindEntitiesQuery, T as PaginatedResult, D as DeleteEntitiesResult, a2 as ReembedResult, a3 as Relationship, ab as RemoveRelationshipsResult, Y as PropertyFilter, a6 as RelationshipSummary, I as GraphResult, q as ExploreOptions, P as Neighborhood, W as PathOptions, X as PathResult, C as ConceptSearchOptions, aj as ScoredEntity, aF as TimelineOptions, aH as TimelineResult, af as RepositoryStats, aJ as ValidateEntitiesOptions, p as EntityValidationPage, aK as ValidateRelationshipsOptions, aa as RelationshipValidationPage, ac as RepositoryConfig, aB as StoredRepository, ad as RepositoryFilter, ag as RepositorySummary, ah as RepositoryUpdate, v as ExportOptions, r as ExportArchive, K as ImportOptions, L as ImportResult, x as ExportStreamItem, M as ImportStreamHeader, J as ImportChunk, ay as StoredEntity, au as StorageRepositoryConfig, aC as StoredRepositorySummary, g as DeleteProgressCallback, U as PaginationOptions, aM as VocabularyChangeRecord, az as StoredEntityUpdate, an as StorageFindQuery, aA as StoredRelationship, a5 as RelationshipQueryOptions, am as StorageExploreOptions, ao as StorageNeighborhood, as as StoragePathOptions, at as StoragePathResult, aw as StorageTimelineOptions, ax as StorageTimelineResult, s as ExportChunk, B as BulkImportOptions, d as BulkImportResult, al as SearchOptions, ak as SearchHit } from './portability-Dbm6vCdD.cjs';
+export { A as AdaptiveConcurrencyAdjustEvent, a as AdaptiveConcurrencyAdjustReason, b as AdaptiveConcurrencyHandle, c as AdaptiveConcurrencyOptions, E as EnrichedRelationship, k as EntityMap, n as EntityTypeInput, o as EntityValidationIssue, t as ExportLegalMetadata, u as ExportManifest, w as ExportPipelineMetadata, G as GetEntitiesOptions, y as GetEntityOptions, H as GovernanceMode, N as ImportWarning, Q as NeighborhoodCenter, R as NeighborhoodGroup, S as NeighborhoodLayer, V as Path, Z as PropertySchema, _ as PropertyType, a1 as ProvenanceFilter, a4 as RelationshipDirection, a7 as RelationshipTypeDefinition, a8 as RelationshipTypeInput, a9 as RelationshipValidationIssue, ae as RepositoryMetadata, ap as StorageNeighborhoodGroup, aq as StorageNeighborhoodLayer, ar as StoragePath, av as StorageTimelineEvent, aD as TimelineEntityRef, aE as TimelineEvent, aG as TimelineRelationshipDetail, aN as VocabularyInput } from './portability-Dbm6vCdD.cjs';
 import { DeepMemoryEventType, EventHandler, Unsubscribe, DeepMemoryEvent, HookResult, EventPayload, UsageSink } from './types/index.cjs';
 export { OperationUsage } from './types/index.cjs';
-import { T as TraversalSpec, a as TraversalResult } from './traversal-CBE5h5ob.cjs';
-export { Q as QueryMetadata, b as TraversalAggregation, c as TraversalPath, d as TraversalProjection, e as TraversalRelationship, f as TraversalReturnMode, g as TraversalStart, h as TraversalStep } from './traversal-CBE5h5ob.cjs';
-import { S as StorageProvider, E as EnsureSchemaResult } from './StorageProvider-BGtKZZt4.cjs';
+import { f as TraversalSpec, d as TraversalResult } from './traversal-1f35drOx.cjs';
+export { Q as QueryMetadata, T as TraversalAggregation, a as TraversalPath, b as TraversalProjection, c as TraversalRelationship, e as TraversalReturnMode, g as TraversalStart, h as TraversalStep } from './traversal-1f35drOx.cjs';
+import { S as StorageProvider, E as EnsureSchemaResult, a as EntityReadOptions } from './StorageProvider-DGH7bVuK.cjs';
 import { EmbeddingProvider, SearchProvider, EmbeddingProviderFactory, GraphTraversalProvider, LockProvider, SearchableEntity } from './providers/index.cjs';
 export { GraphTraversalCapabilities, LockHandle, LockOptions } from './providers/index.cjs';
 
 /** Error codes for all Deep Memory errors */
-type DeepMemoryErrorCode = 'INVALID_INPUT' | 'ENTITY_NOT_FOUND' | 'ENTITY_ALREADY_EXISTS' | 'RELATIONSHIP_NOT_FOUND' | 'RELATIONSHIP_ALREADY_EXISTS' | 'REPOSITORY_NOT_FOUND' | 'REPOSITORY_ALREADY_EXISTS' | 'VOCABULARY_VALIDATION_FAILED' | 'RELATIONSHIP_CONSTRAINT_FAILED' | 'SELF_REFERENTIAL_RELATIONSHIP' | 'GOVERNANCE_DENIED' | 'OPERATION_CANCELLED' | 'OPERATION_ABORTED' | 'EMBEDDING_PROVIDER_REQUIRED' | 'IMPORT_ERROR' | 'EXPORT_ERROR' | 'PROVIDER_ERROR' | 'GRAPH_TRAVERSAL_PROVIDER_REQUIRED' | 'TRAVERSAL_VALIDATION_FAILED' | 'TRAVERSAL_VOCABULARY_ERROR' | 'TRAVERSAL_TIMEOUT';
+type DeepMemoryErrorCode = 'INVALID_INPUT' | 'ENTITY_NOT_FOUND' | 'ENTITY_ALREADY_EXISTS' | 'RELATIONSHIP_NOT_FOUND' | 'RELATIONSHIP_ALREADY_EXISTS' | 'REPOSITORY_NOT_FOUND' | 'REPOSITORY_ALREADY_EXISTS' | 'VOCABULARY_VALIDATION_FAILED' | 'RELATIONSHIP_CONSTRAINT_FAILED' | 'SELF_REFERENTIAL_RELATIONSHIP' | 'GOVERNANCE_DENIED' | 'OPERATION_CANCELLED' | 'OPERATION_ABORTED' | 'EMBEDDING_PROVIDER_REQUIRED' | 'IMPORT_ERROR' | 'EXPORT_ERROR' | 'PROVIDER_ERROR' | 'GRAPH_TRAVERSAL_PROVIDER_REQUIRED' | 'TRAVERSAL_VALIDATION_FAILED' | 'TRAVERSAL_VOCABULARY_ERROR' | 'TRAVERSAL_TIMEOUT' | 'UNSUPPORTED_QUERY';
 /** Base error class for all Deep Memory errors */
 declare class DeepMemoryError extends Error {
     readonly code: DeepMemoryErrorCode;
@@ -146,6 +146,17 @@ declare class TraversalTimeoutError extends DeepMemoryError {
     readonly timeoutMs: number;
     constructor(timeoutMs: number);
 }
+/**
+ * Thrown when a query is syntactically valid but the active provider cannot
+ * execute it efficiently or correctly — e.g. a substring search on a backend
+ * with no server-side text predicate, where the only safe implementation would
+ * fan out across the entire partition. The caller should adjust the query
+ * (add type filters, narrow the scope) or use a provider-specific alternative.
+ */
+declare class UnsupportedQueryError extends DeepMemoryError {
+    readonly provider: string;
+    constructor(provider: string, message: string, suggestion?: string);
+}
 
 interface VocabularyEngineConfig {
     repositoryId: string;
@@ -187,7 +198,14 @@ declare class VocabularyEngine {
     proposeChange(proposal: VocabularyProposal, proposedBy: string): Promise<VocabularyProposalResult>;
     /** @deprecated Use proposeChange instead */
     proposeExtension(proposal: VocabularyProposal, proposedBy: string): Promise<VocabularyProposalResult>;
-    /** Cascade-delete all data for a deleted vocabulary type */
+    /**
+     * Cascade-delete all data for a deleted vocabulary type.
+     *
+     * `deletedRelationships` may be `undefined` when the underlying provider
+     * does not count cascaded edges (see StorageProvider.deleteEntitiesByType).
+     * The return value is currently discarded by the only caller; the type is
+     * preserved for symmetry with the storage contract.
+     */
     private cascadeDeleteData;
     /** Validate all property schemas in a proposal — returns a rejected result on the first invalid schema, or undefined if all pass */
     private validateProposalPropertySchemas;
@@ -318,11 +336,26 @@ declare class MemoryRepository {
          * Called after each batch completes. Internal plumbing — the {@link DeepMemory}
          * facade wires this to `globalEventBus.emit('reembed:progress', ...)`.
          */
+        /**
+         * `totalEntities` is `number | undefined` because it derives from
+         * PaginatedResult.total, which may be undefined for some provider/query
+         * combinations. The {@link DeepMemory.reembedAll} facade coerces it to
+         * a number via the cached RepositoryStats before emitting an event.
+         */
         onProgress?: (progress: {
             processed: number;
-            totalEntities: number;
+            totalEntities: number | undefined;
             failed: number;
         }) => void | Promise<void>;
+        /**
+         * Called for every entity that fails to re-embed (embedBatch retries
+         * exhausted, or storage write failure). Internal plumbing — the facade
+         * wires this to `globalEventBus.emit('reembed:item-failed', ...)`.
+         */
+        onItemFailed?: (failure: {
+            entityId: string;
+            error: string;
+        }) => void | Promise<void>;
         /**
          * Caller-supplied abort signal. Honoured at batch boundaries.
          * Any vectors already written by completed batches are left in place.
@@ -536,6 +569,31 @@ interface CompiledQuery {
     estimatedFanOut: number;
 }
 
+/**
+ * Stored-field name lists exposed for the cross-package sync test in
+ * @utaba/deep-memory-storage-cosmosdb. Excludes synthetic projection-only
+ * fields (`__kind`) — those are emission detail, not data the mapper reads.
+ */
+declare const GREMLIN_VERTEX_PROJECTION_FIELDS: ReadonlyArray<string>;
+declare const GREMLIN_EDGE_PROJECTION_FIELDS: ReadonlyArray<string>;
+/**
+ * Build a Gremlin `.project(...).by(...)...` chain expression for a stored
+ * entity vertex, with no leading dot. Append after a vertex predicate
+ * (e.g. `g.V().has('repositoryId', rid).hasId(p0)`) to read only the keys
+ * `entityFromGremlin` consumes — avoiding `valueMap(true)` and its
+ * ~30 KB-per-row embedding payload.
+ *
+ * The default omits `embedding`. Pass `{ withEmbedding: true }` only from
+ * legitimate consumers of stored embeddings on read (the vector-search path).
+ */
+declare function buildVertexProjectChain(opts?: {
+    withEmbedding?: boolean;
+}): string;
+/**
+ * Build a Gremlin `.project(...).by(...)...` chain expression for a stored
+ * relationship edge, with no leading dot. Edges never carry embeddings.
+ */
+declare function buildEdgeProjectChain(): string;
 declare class GremlinCompiler implements TraversalCompiler {
     readonly language: "gremlin";
     compile(spec: TraversalSpec, _vocabulary: MemoryVocabulary): CompiledQuery;
@@ -565,16 +623,16 @@ declare class InMemoryStorageProvider implements StorageProvider {
     saveVocabulary(repositoryId: string, vocabulary: MemoryVocabulary): Promise<void>;
     getVocabularyChangeLog(repositoryId: string, options?: PaginationOptions): Promise<PaginatedResult<VocabularyChangeRecord>>;
     createEntity(repositoryId: string, entity: StoredEntity): Promise<StoredEntity>;
-    getEntity(repositoryId: string, entityId: string): Promise<StoredEntity | null>;
-    getEntityBySlug(repositoryId: string, slug: string): Promise<StoredEntity | null>;
-    getEntities(repositoryId: string, entityIds: string[]): Promise<Map<string, StoredEntity>>;
+    getEntity(repositoryId: string, entityId: string, _options?: EntityReadOptions): Promise<StoredEntity | null>;
+    getEntityBySlug(repositoryId: string, slug: string, _options?: EntityReadOptions): Promise<StoredEntity | null>;
+    getEntities(repositoryId: string, entityIds: string[], _options?: EntityReadOptions): Promise<Map<string, StoredEntity>>;
     updateEntity(repositoryId: string, entityId: string, updates: StoredEntityUpdate): Promise<StoredEntity>;
     deleteEntity(repositoryId: string, entityId: string): Promise<void>;
     deleteEntitiesByType(repositoryId: string, entityType: string): Promise<{
         deletedEntities: number;
         deletedRelationships: number;
     }>;
-    findEntities(repositoryId: string, query: StorageFindQuery): Promise<PaginatedResult<StoredEntity>>;
+    findEntities(repositoryId: string, query: StorageFindQuery, _options?: EntityReadOptions): Promise<PaginatedResult<StoredEntity>>;
     createRelationship(repositoryId: string, relationship: StoredRelationship): Promise<StoredRelationship>;
     getRelationship(repositoryId: string, relationshipId: string): Promise<StoredRelationship | null>;
     getEntityRelationships(repositoryId: string, entityId: string, options?: RelationshipQueryOptions): Promise<PaginatedResult<StoredRelationship>>;
@@ -613,4 +671,4 @@ declare class NoOpEmbeddingProvider implements EmbeddingProvider {
     modelId(): string;
 }
 
-export { BulkImportOptions, BulkImportResult, type CompiledQuery, ConceptSearchOptions, CreateEntityInput, CreateRelationshipInput, CypherCompiler, DeepMemory, type DeepMemoryConfig, DeepMemoryError, type DeepMemoryErrorCode, DeepMemoryEvent, DeepMemoryEventType, DeleteEntitiesResult, DeleteProgressCallback, DetailLevel, DuplicateEntityError, DuplicateRelationshipError, DuplicateRepositoryError, EmbeddingProvider, EmbeddingProviderFactory, EmbeddingProviderRequiredError, EnsureSchemaResult, Entity, EntityBrief, EntityNotFoundError, EntitySummary, EntityTypeDefinition, EntityValidationPage, EventHandler, EventPayload, ExploreOptions, ExportArchive, ExportChunk, ExportError, ExportOptions, ExportStreamItem, FindEntitiesQuery, GovernanceConfig, GovernanceDeniedError, GraphResult, GraphTraversalProvider, GraphTraversalProviderRequiredError, GremlinCompiler, HookResult, ImportChunk, ImportError, ImportOptions, ImportResult, ImportStreamHeader, ImportThrottleAbortError, InMemorySearchProvider, InMemoryStorageProvider, InvalidInputError, LockProvider, MemoryRepository, MemoryVocabulary, Neighborhood, NoOpEmbeddingProvider, OperationAbortedError, OperationCancelledError, PaginatedResult, PaginationOptions, PathOptions, PathResult, PropertyFilter, Provenance, ProvenanceContext, ProviderError, ReembedResult, Relationship, RelationshipConstraintError, RelationshipNotFoundError, RelationshipQueryOptions, RelationshipSummary, RelationshipValidationPage, RemoveRelationshipsResult, RepositoryConfig, RepositoryFilter, RepositoryNotFoundError, RepositoryStats, RepositorySummary, RepositoryUpdate, RepositoryValidator, ResolvedVocabulary, ScoredEntity, SearchHit, SearchOptions, SearchProvider, SearchableEntity, SelfReferentialRelationshipError, StorageExploreOptions, StorageFindQuery, StorageNeighborhood, StoragePathOptions, StoragePathResult, StorageProvider, StorageRepositoryConfig, StorageTimelineOptions, StorageTimelineResult, StoredEntity, StoredEntityUpdate, StoredRelationship, StoredRepository, StoredRepositorySummary, TimelineOptions, TimelineResult, type TraversalCompiler, TraversalResult, TraversalSpec, TraversalTimeoutError, TraversalValidationError, TraversalVocabularyError, Unsubscribe, UpdateEntityInput, UsageSink, ValidateEntitiesOptions, ValidateRelationshipsOptions, VocabularyChangeRecord, VocabularyProposal, VocabularyProposalResult, VocabularyValidationError, createSafeSink, generateId, isValidUuid, matchesPropertyFilters, projectEntity };
+export { BulkImportOptions, BulkImportResult, type CompiledQuery, ConceptSearchOptions, CreateEntityInput, CreateRelationshipInput, CypherCompiler, DeepMemory, type DeepMemoryConfig, DeepMemoryError, type DeepMemoryErrorCode, DeepMemoryEvent, DeepMemoryEventType, DeleteEntitiesResult, DeleteProgressCallback, DetailLevel, DuplicateEntityError, DuplicateRelationshipError, DuplicateRepositoryError, EmbeddingProvider, EmbeddingProviderFactory, EmbeddingProviderRequiredError, EnsureSchemaResult, Entity, EntityBrief, EntityNotFoundError, EntityReadOptions, EntitySummary, EntityTypeDefinition, EntityValidationPage, EventHandler, EventPayload, ExploreOptions, ExportArchive, ExportChunk, ExportError, ExportOptions, ExportStreamItem, FindEntitiesQuery, GREMLIN_EDGE_PROJECTION_FIELDS, GREMLIN_VERTEX_PROJECTION_FIELDS, GovernanceConfig, GovernanceDeniedError, GraphResult, GraphTraversalProvider, GraphTraversalProviderRequiredError, GremlinCompiler, HookResult, ImportChunk, ImportError, ImportOptions, ImportResult, ImportStreamHeader, ImportThrottleAbortError, InMemorySearchProvider, InMemoryStorageProvider, InvalidInputError, LockProvider, MemoryRepository, MemoryVocabulary, Neighborhood, NoOpEmbeddingProvider, OperationAbortedError, OperationCancelledError, PaginatedResult, PaginationOptions, PathOptions, PathResult, PropertyFilter, Provenance, ProvenanceContext, ProviderError, ReembedResult, Relationship, RelationshipConstraintError, RelationshipNotFoundError, RelationshipQueryOptions, RelationshipSummary, RelationshipValidationPage, RemoveRelationshipsResult, RepositoryConfig, RepositoryFilter, RepositoryNotFoundError, RepositoryStats, RepositorySummary, RepositoryUpdate, RepositoryValidator, ResolvedVocabulary, ScoredEntity, SearchHit, SearchOptions, SearchProvider, SearchableEntity, SelfReferentialRelationshipError, StorageExploreOptions, StorageFindQuery, StorageNeighborhood, StoragePathOptions, StoragePathResult, StorageProvider, StorageRepositoryConfig, StorageTimelineOptions, StorageTimelineResult, StoredEntity, StoredEntityUpdate, StoredRelationship, StoredRepository, StoredRepositorySummary, TimelineOptions, TimelineResult, type TraversalCompiler, TraversalResult, TraversalSpec, TraversalTimeoutError, TraversalValidationError, TraversalVocabularyError, Unsubscribe, UnsupportedQueryError, UpdateEntityInput, UsageSink, ValidateEntitiesOptions, ValidateRelationshipsOptions, VocabularyChangeRecord, VocabularyProposal, VocabularyProposalResult, VocabularyValidationError, buildEdgeProjectChain, buildVertexProjectChain, createSafeSink, generateId, isValidUuid, matchesPropertyFilters, projectEntity };

package/dist/index.d.ts

@@ -1,15 +1,15 @@
-import { G as GovernanceConfig, M as MemoryVocabulary, x as ResolvedVocabulary, C as CreateEntityInput, y as ValidationResult, U as UpdateEntityInput, z as CreateRelationshipInput, A as EntityTypeDefinition, F as VocabularyProposal, H as VocabularyProposalResult, J as ProvenanceContext, K as Provenance, E as Entity, D as DetailLevel, a as EntitySummary, b as EntityBrief, L as FindEntitiesQuery, e as PaginatedResult, N as DeleteEntitiesResult, O as ReembedResult, Q as Relationship, T as RemoveRelationshipsResult, P as PropertyFilter, R as RelationshipSummary, W as GraphResult, X as ExploreOptions, Y as Neighborhood, Z as PathOptions, _ as PathResult, $ as ConceptSearchOptions, a0 as ScoredEntity, a1 as TimelineOptions, a2 as TimelineResult, i as RepositoryStats, a3 as ValidateEntitiesOptions, a4 as EntityValidationPage, a5 as ValidateRelationshipsOptions, a6 as RelationshipValidationPage, a7 as RepositoryConfig, c as StoredRepository, d as RepositoryFilter, a8 as RepositorySummary, g as RepositoryUpdate, a9 as ExportOptions, aa as ExportArchive, ab as ImportOptions, ac as ImportResult, ad as ExportStreamItem, ae as ImportStreamHeader, I as ImportChunk, k as StoredEntity, S as StorageRepositoryConfig, f as StoredRepositorySummary, h as DeleteProgressCallback, j as PaginationOptions, V as VocabularyChangeRecord, l as StoredEntityUpdate, m as StorageFindQuery, n as StoredRelationship, o as RelationshipQueryOptions, p as StorageExploreOptions, q as StorageNeighborhood, r as StoragePathOptions, s as StoragePathResult, t as StorageTimelineOptions, u as StorageTimelineResult, v as ExportChunk, B as BulkImportOptions, w as BulkImportResult, af as SearchOptions, ag as SearchHit } from './portability-P1hL-bOa.js';
-export { ah as AdaptiveConcurrencyAdjustEvent, ai as AdaptiveConcurrencyAdjustReason, aj as AdaptiveConcurrencyHandle, ak as AdaptiveConcurrencyOptions, al as EnrichedRelationship, am as EntityMap, an as EntityTypeInput, ao as EntityValidationIssue, ap as ExportLegalMetadata, aq as ExportManifest, ar as ExportPipelineMetadata, as as GetEntitiesOptions, at as GetEntityOptions, au as GovernanceMode, av as ImportWarning, aw as NeighborhoodCenter, ax as NeighborhoodGroup, ay as NeighborhoodLayer, az as Path, aA as PropertySchema, aB as PropertyType, aC as ProvenanceFilter, aD as RelationshipDirection, aE as RelationshipTypeDefinition, aF as RelationshipTypeInput, aG as RelationshipValidationIssue, aH as RepositoryMetadata, aI as StorageNeighborhoodGroup, aJ as StorageNeighborhoodLayer, aK as StoragePath, aL as StorageTimelineEvent, aM as TimelineEntityRef, aN as TimelineEvent, aO as TimelineRelationshipDetail, aP as VocabularyInput } from './portability-P1hL-bOa.js';
+import { z as GovernanceConfig, O as MemoryVocabulary, ai as ResolvedVocabulary, e as CreateEntityInput, aL as ValidationResult, aI as UpdateEntityInput, f as CreateRelationshipInput, m as EntityTypeDefinition, aO as VocabularyProposal, aP as VocabularyProposalResult, a0 as ProvenanceContext, $ as Provenance, i as Entity, h as DetailLevel, l as EntitySummary, j as EntityBrief, F as FindEntitiesQuery, T as PaginatedResult, D as DeleteEntitiesResult, a2 as ReembedResult, a3 as Relationship, ab as RemoveRelationshipsResult, Y as PropertyFilter, a6 as RelationshipSummary, I as GraphResult, q as ExploreOptions, P as Neighborhood, W as PathOptions, X as PathResult, C as ConceptSearchOptions, aj as ScoredEntity, aF as TimelineOptions, aH as TimelineResult, af as RepositoryStats, aJ as ValidateEntitiesOptions, p as EntityValidationPage, aK as ValidateRelationshipsOptions, aa as RelationshipValidationPage, ac as RepositoryConfig, aB as StoredRepository, ad as RepositoryFilter, ag as RepositorySummary, ah as RepositoryUpdate, v as ExportOptions, r as ExportArchive, K as ImportOptions, L as ImportResult, x as ExportStreamItem, M as ImportStreamHeader, J as ImportChunk, ay as StoredEntity, au as StorageRepositoryConfig, aC as StoredRepositorySummary, g as DeleteProgressCallback, U as PaginationOptions, aM as VocabularyChangeRecord, az as StoredEntityUpdate, an as StorageFindQuery, aA as StoredRelationship, a5 as RelationshipQueryOptions, am as StorageExploreOptions, ao as StorageNeighborhood, as as StoragePathOptions, at as StoragePathResult, aw as StorageTimelineOptions, ax as StorageTimelineResult, s as ExportChunk, B as BulkImportOptions, d as BulkImportResult, al as SearchOptions, ak as SearchHit } from './portability-Dbm6vCdD.js';
+export { A as AdaptiveConcurrencyAdjustEvent, a as AdaptiveConcurrencyAdjustReason, b as AdaptiveConcurrencyHandle, c as AdaptiveConcurrencyOptions, E as EnrichedRelationship, k as EntityMap, n as EntityTypeInput, o as EntityValidationIssue, t as ExportLegalMetadata, u as ExportManifest, w as ExportPipelineMetadata, G as GetEntitiesOptions, y as GetEntityOptions, H as GovernanceMode, N as ImportWarning, Q as NeighborhoodCenter, R as NeighborhoodGroup, S as NeighborhoodLayer, V as Path, Z as PropertySchema, _ as PropertyType, a1 as ProvenanceFilter, a4 as RelationshipDirection, a7 as RelationshipTypeDefinition, a8 as RelationshipTypeInput, a9 as RelationshipValidationIssue, ae as RepositoryMetadata, ap as StorageNeighborhoodGroup, aq as StorageNeighborhoodLayer, ar as StoragePath, av as StorageTimelineEvent, aD as TimelineEntityRef, aE as TimelineEvent, aG as TimelineRelationshipDetail, aN as VocabularyInput } from './portability-Dbm6vCdD.js';
 import { DeepMemoryEventType, EventHandler, Unsubscribe, DeepMemoryEvent, HookResult, EventPayload, UsageSink } from './types/index.js';
 export { OperationUsage } from './types/index.js';
-import { T as TraversalSpec, a as TraversalResult } from './traversal-B_84kGaO.js';
-export { Q as QueryMetadata, b as TraversalAggregation, c as TraversalPath, d as TraversalProjection, e as TraversalRelationship, f as TraversalReturnMode, g as TraversalStart, h as TraversalStep } from './traversal-B_84kGaO.js';
-import { S as StorageProvider, E as EnsureSchemaResult } from './StorageProvider-D_o2Hksf.js';
+import { f as TraversalSpec, d as TraversalResult } from './traversal-OkXViSTI.js';
+export { Q as QueryMetadata, T as TraversalAggregation, a as TraversalPath, b as TraversalProjection, c as TraversalRelationship, e as TraversalReturnMode, g as TraversalStart, h as TraversalStep } from './traversal-OkXViSTI.js';
+import { S as StorageProvider, E as EnsureSchemaResult, a as EntityReadOptions } from './StorageProvider-DDTLUcuj.js';
 import { EmbeddingProvider, SearchProvider, EmbeddingProviderFactory, GraphTraversalProvider, LockProvider, SearchableEntity } from './providers/index.js';
 export { GraphTraversalCapabilities, LockHandle, LockOptions } from './providers/index.js';
 
 /** Error codes for all Deep Memory errors */
-type DeepMemoryErrorCode = 'INVALID_INPUT' | 'ENTITY_NOT_FOUND' | 'ENTITY_ALREADY_EXISTS' | 'RELATIONSHIP_NOT_FOUND' | 'RELATIONSHIP_ALREADY_EXISTS' | 'REPOSITORY_NOT_FOUND' | 'REPOSITORY_ALREADY_EXISTS' | 'VOCABULARY_VALIDATION_FAILED' | 'RELATIONSHIP_CONSTRAINT_FAILED' | 'SELF_REFERENTIAL_RELATIONSHIP' | 'GOVERNANCE_DENIED' | 'OPERATION_CANCELLED' | 'OPERATION_ABORTED' | 'EMBEDDING_PROVIDER_REQUIRED' | 'IMPORT_ERROR' | 'EXPORT_ERROR' | 'PROVIDER_ERROR' | 'GRAPH_TRAVERSAL_PROVIDER_REQUIRED' | 'TRAVERSAL_VALIDATION_FAILED' | 'TRAVERSAL_VOCABULARY_ERROR' | 'TRAVERSAL_TIMEOUT';
+type DeepMemoryErrorCode = 'INVALID_INPUT' | 'ENTITY_NOT_FOUND' | 'ENTITY_ALREADY_EXISTS' | 'RELATIONSHIP_NOT_FOUND' | 'RELATIONSHIP_ALREADY_EXISTS' | 'REPOSITORY_NOT_FOUND' | 'REPOSITORY_ALREADY_EXISTS' | 'VOCABULARY_VALIDATION_FAILED' | 'RELATIONSHIP_CONSTRAINT_FAILED' | 'SELF_REFERENTIAL_RELATIONSHIP' | 'GOVERNANCE_DENIED' | 'OPERATION_CANCELLED' | 'OPERATION_ABORTED' | 'EMBEDDING_PROVIDER_REQUIRED' | 'IMPORT_ERROR' | 'EXPORT_ERROR' | 'PROVIDER_ERROR' | 'GRAPH_TRAVERSAL_PROVIDER_REQUIRED' | 'TRAVERSAL_VALIDATION_FAILED' | 'TRAVERSAL_VOCABULARY_ERROR' | 'TRAVERSAL_TIMEOUT' | 'UNSUPPORTED_QUERY';
 /** Base error class for all Deep Memory errors */
 declare class DeepMemoryError extends Error {
     readonly code: DeepMemoryErrorCode;
@@ -146,6 +146,17 @@ declare class TraversalTimeoutError extends DeepMemoryError {
     readonly timeoutMs: number;
     constructor(timeoutMs: number);
 }
+/**
+ * Thrown when a query is syntactically valid but the active provider cannot
+ * execute it efficiently or correctly — e.g. a substring search on a backend
+ * with no server-side text predicate, where the only safe implementation would
+ * fan out across the entire partition. The caller should adjust the query
+ * (add type filters, narrow the scope) or use a provider-specific alternative.
+ */
+declare class UnsupportedQueryError extends DeepMemoryError {
+    readonly provider: string;
+    constructor(provider: string, message: string, suggestion?: string);
+}
 
 interface VocabularyEngineConfig {
     repositoryId: string;
@@ -187,7 +198,14 @@ declare class VocabularyEngine {
     proposeChange(proposal: VocabularyProposal, proposedBy: string): Promise<VocabularyProposalResult>;
     /** @deprecated Use proposeChange instead */
     proposeExtension(proposal: VocabularyProposal, proposedBy: string): Promise<VocabularyProposalResult>;
-    /** Cascade-delete all data for a deleted vocabulary type */
+    /**
+     * Cascade-delete all data for a deleted vocabulary type.
+     *
+     * `deletedRelationships` may be `undefined` when the underlying provider
+     * does not count cascaded edges (see StorageProvider.deleteEntitiesByType).
+     * The return value is currently discarded by the only caller; the type is
+     * preserved for symmetry with the storage contract.
+     */
     private cascadeDeleteData;
     /** Validate all property schemas in a proposal — returns a rejected result on the first invalid schema, or undefined if all pass */
     private validateProposalPropertySchemas;
@@ -318,11 +336,26 @@ declare class MemoryRepository {
          * Called after each batch completes. Internal plumbing — the {@link DeepMemory}
          * facade wires this to `globalEventBus.emit('reembed:progress', ...)`.
          */
+        /**
+         * `totalEntities` is `number | undefined` because it derives from
+         * PaginatedResult.total, which may be undefined for some provider/query
+         * combinations. The {@link DeepMemory.reembedAll} facade coerces it to
+         * a number via the cached RepositoryStats before emitting an event.
+         */
         onProgress?: (progress: {
             processed: number;
-            totalEntities: number;
+            totalEntities: number | undefined;
             failed: number;
         }) => void | Promise<void>;
+        /**
+         * Called for every entity that fails to re-embed (embedBatch retries
+         * exhausted, or storage write failure). Internal plumbing — the facade
+         * wires this to `globalEventBus.emit('reembed:item-failed', ...)`.
+         */
+        onItemFailed?: (failure: {
+            entityId: string;
+            error: string;
+        }) => void | Promise<void>;
         /**
          * Caller-supplied abort signal. Honoured at batch boundaries.
          * Any vectors already written by completed batches are left in place.
@@ -536,6 +569,31 @@ interface CompiledQuery {
     estimatedFanOut: number;
 }
 
+/**
+ * Stored-field name lists exposed for the cross-package sync test in
+ * @utaba/deep-memory-storage-cosmosdb. Excludes synthetic projection-only
+ * fields (`__kind`) — those are emission detail, not data the mapper reads.
+ */
+declare const GREMLIN_VERTEX_PROJECTION_FIELDS: ReadonlyArray<string>;
+declare const GREMLIN_EDGE_PROJECTION_FIELDS: ReadonlyArray<string>;
+/**
+ * Build a Gremlin `.project(...).by(...)...` chain expression for a stored
+ * entity vertex, with no leading dot. Append after a vertex predicate
+ * (e.g. `g.V().has('repositoryId', rid).hasId(p0)`) to read only the keys
+ * `entityFromGremlin` consumes — avoiding `valueMap(true)` and its
+ * ~30 KB-per-row embedding payload.
+ *
+ * The default omits `embedding`. Pass `{ withEmbedding: true }` only from
+ * legitimate consumers of stored embeddings on read (the vector-search path).
+ */
+declare function buildVertexProjectChain(opts?: {
+    withEmbedding?: boolean;
+}): string;
+/**
+ * Build a Gremlin `.project(...).by(...)...` chain expression for a stored
+ * relationship edge, with no leading dot. Edges never carry embeddings.
+ */
+declare function buildEdgeProjectChain(): string;
 declare class GremlinCompiler implements TraversalCompiler {
     readonly language: "gremlin";
     compile(spec: TraversalSpec, _vocabulary: MemoryVocabulary): CompiledQuery;
@@ -565,16 +623,16 @@ declare class InMemoryStorageProvider implements StorageProvider {
     saveVocabulary(repositoryId: string, vocabulary: MemoryVocabulary): Promise<void>;
     getVocabularyChangeLog(repositoryId: string, options?: PaginationOptions): Promise<PaginatedResult<VocabularyChangeRecord>>;
     createEntity(repositoryId: string, entity: StoredEntity): Promise<StoredEntity>;
-    getEntity(repositoryId: string, entityId: string): Promise<StoredEntity | null>;
-    getEntityBySlug(repositoryId: string, slug: string): Promise<StoredEntity | null>;
-    getEntities(repositoryId: string, entityIds: string[]): Promise<Map<string, StoredEntity>>;
+    getEntity(repositoryId: string, entityId: string, _options?: EntityReadOptions): Promise<StoredEntity | null>;
+    getEntityBySlug(repositoryId: string, slug: string, _options?: EntityReadOptions): Promise<StoredEntity | null>;
+    getEntities(repositoryId: string, entityIds: string[], _options?: EntityReadOptions): Promise<Map<string, StoredEntity>>;
     updateEntity(repositoryId: string, entityId: string, updates: StoredEntityUpdate): Promise<StoredEntity>;
     deleteEntity(repositoryId: string, entityId: string): Promise<void>;
     deleteEntitiesByType(repositoryId: string, entityType: string): Promise<{
         deletedEntities: number;
         deletedRelationships: number;
     }>;
-    findEntities(repositoryId: string, query: StorageFindQuery): Promise<PaginatedResult<StoredEntity>>;
+    findEntities(repositoryId: string, query: StorageFindQuery, _options?: EntityReadOptions): Promise<PaginatedResult<StoredEntity>>;
     createRelationship(repositoryId: string, relationship: StoredRelationship): Promise<StoredRelationship>;
     getRelationship(repositoryId: string, relationshipId: string): Promise<StoredRelationship | null>;
     getEntityRelationships(repositoryId: string, entityId: string, options?: RelationshipQueryOptions): Promise<PaginatedResult<StoredRelationship>>;
@@ -613,4 +671,4 @@ declare class NoOpEmbeddingProvider implements EmbeddingProvider {
     modelId(): string;
 }
 
-export { BulkImportOptions, BulkImportResult, type CompiledQuery, ConceptSearchOptions, CreateEntityInput, CreateRelationshipInput, CypherCompiler, DeepMemory, type DeepMemoryConfig, DeepMemoryError, type DeepMemoryErrorCode, DeepMemoryEvent, DeepMemoryEventType, DeleteEntitiesResult, DeleteProgressCallback, DetailLevel, DuplicateEntityError, DuplicateRelationshipError, DuplicateRepositoryError, EmbeddingProvider, EmbeddingProviderFactory, EmbeddingProviderRequiredError, EnsureSchemaResult, Entity, EntityBrief, EntityNotFoundError, EntitySummary, EntityTypeDefinition, EntityValidationPage, EventHandler, EventPayload, ExploreOptions, ExportArchive, ExportChunk, ExportError, ExportOptions, ExportStreamItem, FindEntitiesQuery, GovernanceConfig, GovernanceDeniedError, GraphResult, GraphTraversalProvider, GraphTraversalProviderRequiredError, GremlinCompiler, HookResult, ImportChunk, ImportError, ImportOptions, ImportResult, ImportStreamHeader, ImportThrottleAbortError, InMemorySearchProvider, InMemoryStorageProvider, InvalidInputError, LockProvider, MemoryRepository, MemoryVocabulary, Neighborhood, NoOpEmbeddingProvider, OperationAbortedError, OperationCancelledError, PaginatedResult, PaginationOptions, PathOptions, PathResult, PropertyFilter, Provenance, ProvenanceContext, ProviderError, ReembedResult, Relationship, RelationshipConstraintError, RelationshipNotFoundError, RelationshipQueryOptions, RelationshipSummary, RelationshipValidationPage, RemoveRelationshipsResult, RepositoryConfig, RepositoryFilter, RepositoryNotFoundError, RepositoryStats, RepositorySummary, RepositoryUpdate, RepositoryValidator, ResolvedVocabulary, ScoredEntity, SearchHit, SearchOptions, SearchProvider, SearchableEntity, SelfReferentialRelationshipError, StorageExploreOptions, StorageFindQuery, StorageNeighborhood, StoragePathOptions, StoragePathResult, StorageProvider, StorageRepositoryConfig, StorageTimelineOptions, StorageTimelineResult, StoredEntity, StoredEntityUpdate, StoredRelationship, StoredRepository, StoredRepositorySummary, TimelineOptions, TimelineResult, type TraversalCompiler, TraversalResult, TraversalSpec, TraversalTimeoutError, TraversalValidationError, TraversalVocabularyError, Unsubscribe, UpdateEntityInput, UsageSink, ValidateEntitiesOptions, ValidateRelationshipsOptions, VocabularyChangeRecord, VocabularyProposal, VocabularyProposalResult, VocabularyValidationError, createSafeSink, generateId, isValidUuid, matchesPropertyFilters, projectEntity };
+export { BulkImportOptions, BulkImportResult, type CompiledQuery, ConceptSearchOptions, CreateEntityInput, CreateRelationshipInput, CypherCompiler, DeepMemory, type DeepMemoryConfig, DeepMemoryError, type DeepMemoryErrorCode, DeepMemoryEvent, DeepMemoryEventType, DeleteEntitiesResult, DeleteProgressCallback, DetailLevel, DuplicateEntityError, DuplicateRelationshipError, DuplicateRepositoryError, EmbeddingProvider, EmbeddingProviderFactory, EmbeddingProviderRequiredError, EnsureSchemaResult, Entity, EntityBrief, EntityNotFoundError, EntityReadOptions, EntitySummary, EntityTypeDefinition, EntityValidationPage, EventHandler, EventPayload, ExploreOptions, ExportArchive, ExportChunk, ExportError, ExportOptions, ExportStreamItem, FindEntitiesQuery, GREMLIN_EDGE_PROJECTION_FIELDS, GREMLIN_VERTEX_PROJECTION_FIELDS, GovernanceConfig, GovernanceDeniedError, GraphResult, GraphTraversalProvider, GraphTraversalProviderRequiredError, GremlinCompiler, HookResult, ImportChunk, ImportError, ImportOptions, ImportResult, ImportStreamHeader, ImportThrottleAbortError, InMemorySearchProvider, InMemoryStorageProvider, InvalidInputError, LockProvider, MemoryRepository, MemoryVocabulary, Neighborhood, NoOpEmbeddingProvider, OperationAbortedError, OperationCancelledError, PaginatedResult, PaginationOptions, PathOptions, PathResult, PropertyFilter, Provenance, ProvenanceContext, ProviderError, ReembedResult, Relationship, RelationshipConstraintError, RelationshipNotFoundError, RelationshipQueryOptions, RelationshipSummary, RelationshipValidationPage, RemoveRelationshipsResult, RepositoryConfig, RepositoryFilter, RepositoryNotFoundError, RepositoryStats, RepositorySummary, RepositoryUpdate, RepositoryValidator, ResolvedVocabulary, ScoredEntity, SearchHit, SearchOptions, SearchProvider, SearchableEntity, SelfReferentialRelationshipError, StorageExploreOptions, StorageFindQuery, StorageNeighborhood, StoragePathOptions, StoragePathResult, StorageProvider, StorageRepositoryConfig, StorageTimelineOptions, StorageTimelineResult, StoredEntity, StoredEntityUpdate, StoredRelationship, StoredRepository, StoredRepositorySummary, TimelineOptions, TimelineResult, type TraversalCompiler, TraversalResult, TraversalSpec, TraversalTimeoutError, TraversalValidationError, TraversalVocabularyError, Unsubscribe, UnsupportedQueryError, UpdateEntityInput, UsageSink, ValidateEntitiesOptions, ValidateRelationshipsOptions, VocabularyChangeRecord, VocabularyProposal, VocabularyProposalResult, VocabularyValidationError, buildEdgeProjectChain, buildVertexProjectChain, createSafeSink, generateId, isValidUuid, matchesPropertyFilters, projectEntity };