@utaba/deep-memory 0.1.0 → 0.2.0

package/dist/{portability-DdlNYXGX.d.cts → portability-DdjsCB07.d.cts}

@@ -812,6 +812,44 @@ interface ExportManifest {
         dimensions: number;
         note: string;
     };
+    /** Legal and copyright metadata — set by the publisher of the archive */
+    legal?: ExportLegalMetadata;
+    /** Indexing pipeline metadata — present when archive was produced by the indexer */
+    pipeline?: ExportPipelineMetadata;
+}
+/** Legal and copyright metadata for an export archive */
+interface ExportLegalMetadata {
+    /** Copyright holder (e.g. "© 2026 Caterpillar Inc.") */
+    copyright: string;
+    /** SPDX license identifier or custom license name (e.g. "Apache-2.0", "LicenseRef-Proprietary") */
+    license?: string;
+    /** Full license text or URL pointing to license terms */
+    licenseUrl?: string;
+    /** Human-readable usage terms or restrictions summary */
+    terms?: string;
+    /** Organization that published this archive */
+    publisher?: string;
+    /** Contact for licensing questions (e.g. email address) */
+    contact?: string;
+}
+/** Pipeline metadata describing how the data was produced */
+interface ExportPipelineMetadata {
+    /** LLM model used for extraction (e.g. "claude-sonnet-4-20250514") */
+    extractionModel: string;
+    /** LLM provider name (e.g. "anthropic", "vllm") */
+    extractionProvider?: string;
+    /** Embeddings model used (e.g. "Qwen/Qwen3-Embedding-8B") */
+    embeddingsModel?: string;
+    /** Number of source documents processed */
+    sourceCount: number;
+    /** Source document names or paths */
+    sources: string[];
+    /** Extraction parameters used */
+    parameters?: {
+        chunkSize?: number;
+        chunkOverlap?: number;
+        maxOutputTokens?: number;
+    };
 }
 /** A complete repository export archive */
 interface ExportArchive {
@@ -845,6 +883,11 @@ type ExportStreamItem = {
     sequence: number;
     isLast: boolean;
 };
+/** Options for exporting a repository */
+interface ExportOptions {
+    /** Legal/copyright metadata to embed in the export manifest */
+    legal?: ExportLegalMetadata;
+}
 /** Options for importing a repository archive */
 interface ImportOptions {
     /** How to handle the target repository */
@@ -894,4 +937,4 @@ interface ImportResult {
     warnings: ImportWarning[];
 }
 
-export type { RepositorySummary as $, ReembedResult as A, BulkImportResult as B, CreateEntityInput as C, DetailLevel as D, ExportChunk as E, FindEntitiesQuery as F, GovernanceConfig as G, Relationship as H, ImportChunk as I, PropertyFilter as J, RelationshipSummary as K, GraphResult as L, MemoryVocabulary as M, ExploreOptions as N, Neighbourhood as O, PaginatedResult as P, PathOptions as Q, RepositoryFilter as R, StorageRepositoryConfig as S, PathResult as T, UpdateEntityInput as U, VocabularyChangeRecord as V, ConceptSearchOptions as W, ScoredEntity as X, TimelineOptions as Y, TimelineResult as Z, RepositoryConfig as _, StoredRepository as a, ExportArchive as a0, ImportOptions as a1, ImportResult as a2, ExportStreamItem as a3, ImportStreamHeader as a4, SearchOptions as a5, SearchHit as a6, EnrichedRelationship as a7, EntityMap as a8, EntityTypeInput as a9, ExportManifest as aa, GetEntitiesOptions as ab, GetEntityOptions as ac, GovernanceMode as ad, ImportWarning as ae, NeighbourhoodCentre as af, NeighbourhoodGroup as ag, NeighbourhoodLayer as ah, Path as ai, PropertySchema as aj, PropertyType as ak, ProvenanceFilter as al, RelationshipDirection as am, RelationshipTypeDefinition as an, RelationshipTypeInput as ao, RepositoryMetadata as ap, StorageNeighbourhoodGroup as aq, StorageNeighbourhoodLayer as ar, StoragePath as as, StorageTimelineEvent as at, TimelineEntityRef as au, TimelineEvent as av, TimelineRelationshipDetail as aw, VocabularyInput as ax, StoredRepositorySummary as b, RepositoryUpdate as c, RepositoryStats as d, PaginationOptions as e, StoredEntity as f, StoredEntityUpdate as g, StorageFindQuery as h, StoredRelationship as i, RelationshipQueryOptions as j, StorageExploreOptions as k, StorageNeighbourhood as l, StoragePathOptions as m, StoragePathResult as n, StorageTimelineOptions as o, StorageTimelineResult as p, ResolvedVocabulary as q, CreateRelationshipInput as r, EntityTypeDefinition as s, VocabularyProposal as t, VocabularyProposalResult as u, ProvenanceContext as v, Provenance as w, Entity as x, EntitySummary as y, EntityBrief as z };
+export type { RepositorySummary as $, Provenance as A, BulkImportResult as B, CreateEntityInput as C, DetailLevel as D, Entity as E, FindEntitiesQuery as F, GovernanceConfig as G, ReembedResult as H, ImportChunk as I, Relationship as J, RelationshipSummary as K, GraphResult as L, MemoryVocabulary as M, ExploreOptions as N, Neighbourhood as O, PropertyFilter as P, PathOptions as Q, RepositoryFilter as R, StorageRepositoryConfig as S, PathResult as T, UpdateEntityInput as U, VocabularyChangeRecord as V, ConceptSearchOptions as W, ScoredEntity as X, TimelineOptions as Y, TimelineResult as Z, RepositoryConfig as _, EntitySummary as a, ExportOptions as a0, ExportArchive as a1, ImportOptions as a2, ImportResult as a3, ExportStreamItem as a4, ImportStreamHeader as a5, SearchOptions as a6, SearchHit as a7, EnrichedRelationship as a8, EntityMap as a9, VocabularyInput as aA, EntityTypeInput as aa, ExportLegalMetadata as ab, ExportManifest as ac, ExportPipelineMetadata as ad, GetEntitiesOptions as ae, GetEntityOptions as af, GovernanceMode as ag, ImportWarning as ah, NeighbourhoodCentre as ai, NeighbourhoodGroup as aj, NeighbourhoodLayer as ak, Path as al, PropertySchema as am, PropertyType as an, ProvenanceFilter as ao, RelationshipDirection as ap, RelationshipTypeDefinition as aq, RelationshipTypeInput as ar, RepositoryMetadata as as, StorageNeighbourhoodGroup as at, StorageNeighbourhoodLayer as au, StoragePath as av, StorageTimelineEvent as aw, TimelineEntityRef as ax, TimelineEvent as ay, TimelineRelationshipDetail as az, EntityBrief as b, StoredRepository as c, PaginatedResult as d, StoredRepositorySummary as e, RepositoryUpdate as f, RepositoryStats as g, PaginationOptions as h, StoredEntity as i, StoredEntityUpdate as j, StorageFindQuery as k, StoredRelationship as l, RelationshipQueryOptions as m, StorageExploreOptions as n, StorageNeighbourhood as o, StoragePathOptions as p, StoragePathResult as q, StorageTimelineOptions as r, StorageTimelineResult as s, ExportChunk as t, ResolvedVocabulary as u, CreateRelationshipInput as v, EntityTypeDefinition as w, VocabularyProposal as x, VocabularyProposalResult as y, ProvenanceContext as z };

package/dist/{portability-DdlNYXGX.d.ts → portability-DdjsCB07.d.ts}

@@ -812,6 +812,44 @@ interface ExportManifest {
         dimensions: number;
         note: string;
     };
+    /** Legal and copyright metadata — set by the publisher of the archive */
+    legal?: ExportLegalMetadata;
+    /** Indexing pipeline metadata — present when archive was produced by the indexer */
+    pipeline?: ExportPipelineMetadata;
+}
+/** Legal and copyright metadata for an export archive */
+interface ExportLegalMetadata {
+    /** Copyright holder (e.g. "© 2026 Caterpillar Inc.") */
+    copyright: string;
+    /** SPDX license identifier or custom license name (e.g. "Apache-2.0", "LicenseRef-Proprietary") */
+    license?: string;
+    /** Full license text or URL pointing to license terms */
+    licenseUrl?: string;
+    /** Human-readable usage terms or restrictions summary */
+    terms?: string;
+    /** Organization that published this archive */
+    publisher?: string;
+    /** Contact for licensing questions (e.g. email address) */
+    contact?: string;
+}
+/** Pipeline metadata describing how the data was produced */
+interface ExportPipelineMetadata {
+    /** LLM model used for extraction (e.g. "claude-sonnet-4-20250514") */
+    extractionModel: string;
+    /** LLM provider name (e.g. "anthropic", "vllm") */
+    extractionProvider?: string;
+    /** Embeddings model used (e.g. "Qwen/Qwen3-Embedding-8B") */
+    embeddingsModel?: string;
+    /** Number of source documents processed */
+    sourceCount: number;
+    /** Source document names or paths */
+    sources: string[];
+    /** Extraction parameters used */
+    parameters?: {
+        chunkSize?: number;
+        chunkOverlap?: number;
+        maxOutputTokens?: number;
+    };
 }
 /** A complete repository export archive */
 interface ExportArchive {
@@ -845,6 +883,11 @@ type ExportStreamItem = {
     sequence: number;
     isLast: boolean;
 };
+/** Options for exporting a repository */
+interface ExportOptions {
+    /** Legal/copyright metadata to embed in the export manifest */
+    legal?: ExportLegalMetadata;
+}
 /** Options for importing a repository archive */
 interface ImportOptions {
     /** How to handle the target repository */
@@ -894,4 +937,4 @@ interface ImportResult {
     warnings: ImportWarning[];
 }
 
-export type { RepositorySummary as $, ReembedResult as A, BulkImportResult as B, CreateEntityInput as C, DetailLevel as D, ExportChunk as E, FindEntitiesQuery as F, GovernanceConfig as G, Relationship as H, ImportChunk as I, PropertyFilter as J, RelationshipSummary as K, GraphResult as L, MemoryVocabulary as M, ExploreOptions as N, Neighbourhood as O, PaginatedResult as P, PathOptions as Q, RepositoryFilter as R, StorageRepositoryConfig as S, PathResult as T, UpdateEntityInput as U, VocabularyChangeRecord as V, ConceptSearchOptions as W, ScoredEntity as X, TimelineOptions as Y, TimelineResult as Z, RepositoryConfig as _, StoredRepository as a, ExportArchive as a0, ImportOptions as a1, ImportResult as a2, ExportStreamItem as a3, ImportStreamHeader as a4, SearchOptions as a5, SearchHit as a6, EnrichedRelationship as a7, EntityMap as a8, EntityTypeInput as a9, ExportManifest as aa, GetEntitiesOptions as ab, GetEntityOptions as ac, GovernanceMode as ad, ImportWarning as ae, NeighbourhoodCentre as af, NeighbourhoodGroup as ag, NeighbourhoodLayer as ah, Path as ai, PropertySchema as aj, PropertyType as ak, ProvenanceFilter as al, RelationshipDirection as am, RelationshipTypeDefinition as an, RelationshipTypeInput as ao, RepositoryMetadata as ap, StorageNeighbourhoodGroup as aq, StorageNeighbourhoodLayer as ar, StoragePath as as, StorageTimelineEvent as at, TimelineEntityRef as au, TimelineEvent as av, TimelineRelationshipDetail as aw, VocabularyInput as ax, StoredRepositorySummary as b, RepositoryUpdate as c, RepositoryStats as d, PaginationOptions as e, StoredEntity as f, StoredEntityUpdate as g, StorageFindQuery as h, StoredRelationship as i, RelationshipQueryOptions as j, StorageExploreOptions as k, StorageNeighbourhood as l, StoragePathOptions as m, StoragePathResult as n, StorageTimelineOptions as o, StorageTimelineResult as p, ResolvedVocabulary as q, CreateRelationshipInput as r, EntityTypeDefinition as s, VocabularyProposal as t, VocabularyProposalResult as u, ProvenanceContext as v, Provenance as w, Entity as x, EntitySummary as y, EntityBrief as z };
+export type { RepositorySummary as $, Provenance as A, BulkImportResult as B, CreateEntityInput as C, DetailLevel as D, Entity as E, FindEntitiesQuery as F, GovernanceConfig as G, ReembedResult as H, ImportChunk as I, Relationship as J, RelationshipSummary as K, GraphResult as L, MemoryVocabulary as M, ExploreOptions as N, Neighbourhood as O, PropertyFilter as P, PathOptions as Q, RepositoryFilter as R, StorageRepositoryConfig as S, PathResult as T, UpdateEntityInput as U, VocabularyChangeRecord as V, ConceptSearchOptions as W, ScoredEntity as X, TimelineOptions as Y, TimelineResult as Z, RepositoryConfig as _, EntitySummary as a, ExportOptions as a0, ExportArchive as a1, ImportOptions as a2, ImportResult as a3, ExportStreamItem as a4, ImportStreamHeader as a5, SearchOptions as a6, SearchHit as a7, EnrichedRelationship as a8, EntityMap as a9, VocabularyInput as aA, EntityTypeInput as aa, ExportLegalMetadata as ab, ExportManifest as ac, ExportPipelineMetadata as ad, GetEntitiesOptions as ae, GetEntityOptions as af, GovernanceMode as ag, ImportWarning as ah, NeighbourhoodCentre as ai, NeighbourhoodGroup as aj, NeighbourhoodLayer as ak, Path as al, PropertySchema as am, PropertyType as an, ProvenanceFilter as ao, RelationshipDirection as ap, RelationshipTypeDefinition as aq, RelationshipTypeInput as ar, RepositoryMetadata as as, StorageNeighbourhoodGroup as at, StorageNeighbourhoodLayer as au, StoragePath as av, StorageTimelineEvent as aw, TimelineEntityRef as ax, TimelineEvent as ay, TimelineRelationshipDetail as az, EntityBrief as b, StoredRepository as c, PaginatedResult as d, StoredRepositorySummary as e, RepositoryUpdate as f, RepositoryStats as g, PaginationOptions as h, StoredEntity as i, StoredEntityUpdate as j, StorageFindQuery as k, StoredRelationship as l, RelationshipQueryOptions as m, StorageExploreOptions as n, StorageNeighbourhood as o, StoragePathOptions as p, StoragePathResult as q, StorageTimelineOptions as r, StorageTimelineResult as s, ExportChunk as t, ResolvedVocabulary as u, CreateRelationshipInput as v, EntityTypeDefinition as w, VocabularyProposal as x, VocabularyProposalResult as y, ProvenanceContext as z };

package/dist/providers/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/providers/index.ts"],"sourcesContent":["// Provider interface re-exports — @utaba/deep-memory/providers\n\nexport type { StorageProvider } from './StorageProvider.js';\nexport type { EmbeddingProvider } from './EmbeddingProvider.js';\nexport type {\n  SearchProvider,\n  SearchableEntity,\n} from './SearchProvider.js';\nexport type {\n  LockProvider,\n  LockOptions,\n  LockHandle,\n} from './LockProvider.js';\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../../src/providers/index.ts"],"sourcesContent":["// Provider interface re-exports — @utaba/deep-memory/providers\n\nexport type { StorageProvider, EnsureSchemaResult } from './StorageProvider.js';\nexport type { EmbeddingProvider } from './EmbeddingProvider.js';\nexport type {\n  SearchProvider,\n  SearchableEntity,\n} from './SearchProvider.js';\nexport type {\n  LockProvider,\n  LockOptions,\n  LockHandle,\n} from './LockProvider.js';\nexport type {\n  GraphTraversalProvider,\n  GraphTraversalCapabilities,\n} from './GraphTraversalProvider.js';\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/providers/index.d.cts

@@ -1,5 +1,6 @@
-export { S as StorageProvider } from '../StorageProvider-CkFjdboX.cjs';
-import { a5 as SearchOptions, P as PaginatedResult, a6 as SearchHit } from '../portability-DdlNYXGX.cjs';
+export { E as EnsureSchemaResult, S as StorageProvider } from '../StorageProvider-C3tKhfuw.cjs';
+import { a6 as SearchOptions, d as PaginatedResult, a7 as SearchHit } from '../portability-DdjsCB07.cjs';
+import { T as TraversalSpec, a as TraversalResult } from '../traversal-BB_yERbf.cjs';
 
 /**
  * EmbeddingProvider — enables semantic search and vocabulary deduplication.
@@ -72,4 +73,56 @@ interface LockHandle {
     extend(additionalMs: number): Promise<void>;
 }
 
-export type { EmbeddingProvider, LockHandle, LockOptions, LockProvider, SearchProvider, SearchableEntity };
+/**
+ * Optional provider for native graph traversal.
+ * When registered, enables multi-hop traversal queries and native graph
+ * query pass-through. When absent, the library falls back to application-level
+ * BFS over StorageProvider for structured traversals.
+ */
+interface GraphTraversalProvider {
+    /**
+     * Execute a structured traversal compiled from a TraversalSpec.
+     * The library may pass both the spec and a pre-compiled query string.
+     * The provider can use either — the compiled query is a suggestion,
+     * not a requirement.
+     */
+    traverse(repositoryId: string, spec: TraversalSpec, compiledQuery?: string): Promise<TraversalResult>;
+    /**
+     * Execute a native graph query (Gremlin, Cypher, etc.).
+     * The library passes the query string through without modification.
+     * The provider is responsible for execution and result mapping.
+     *
+     * Implementers decide whether to expose this to agents.
+     * The library does not add safety guards — that is the implementer's
+     * responsibility.
+     */
+    executeNativeQuery(repositoryId: string, query: string, params?: Record<string, unknown>): Promise<TraversalResult>;
+    /**
+     * Report provider capabilities so the library can adapt
+     * DSL compilation and validate traversal specs accordingly.
+     */
+    getCapabilities(): GraphTraversalCapabilities;
+    /** Optional lifecycle hooks, matching StorageProvider pattern. */
+    initialise?(): Promise<void>;
+    dispose?(): Promise<void>;
+}
+interface GraphTraversalCapabilities {
+    /** Whether executeNativeQuery() is implemented. */
+    supportsNativeQuery: boolean;
+    /** The native query language, for DSL compilation targeting. */
+    nativeQueryLanguage: 'gremlin' | 'cypher' | 'sql' | 'other';
+    /** Maximum traversal depth the provider supports. */
+    maxTraversalDepth: number;
+    /** Whether the provider supports property filters on relationships during traversal. */
+    supportsRelationshipPropertyFilters: boolean;
+    /** Whether the provider supports property filters on entities during traversal. */
+    supportsEntityPropertyFilters: boolean;
+    /** Whether the provider supports aggregation (count, sum, avg) on terminal results. */
+    supportsAggregation: boolean;
+    /** Whether the provider supports repeat/loop traversal steps. */
+    supportsRepeat: boolean;
+    /** Whether the provider supports dedup across traversal results. */
+    supportsDedup: boolean;
+}
+
+export type { EmbeddingProvider, GraphTraversalCapabilities, GraphTraversalProvider, LockHandle, LockOptions, LockProvider, SearchProvider, SearchableEntity };

package/dist/providers/index.d.ts

@@ -1,5 +1,6 @@
-export { S as StorageProvider } from '../StorageProvider-CJjz8uBY.js';
-import { a5 as SearchOptions, P as PaginatedResult, a6 as SearchHit } from '../portability-DdlNYXGX.js';
+export { E as EnsureSchemaResult, S as StorageProvider } from '../StorageProvider-DR9HLYHJ.js';
+import { a6 as SearchOptions, d as PaginatedResult, a7 as SearchHit } from '../portability-DdjsCB07.js';
+import { T as TraversalSpec, a as TraversalResult } from '../traversal-9JdiqjZ9.js';
 
 /**
  * EmbeddingProvider — enables semantic search and vocabulary deduplication.
@@ -72,4 +73,56 @@ interface LockHandle {
     extend(additionalMs: number): Promise<void>;
 }
 
-export type { EmbeddingProvider, LockHandle, LockOptions, LockProvider, SearchProvider, SearchableEntity };
+/**
+ * Optional provider for native graph traversal.
+ * When registered, enables multi-hop traversal queries and native graph
+ * query pass-through. When absent, the library falls back to application-level
+ * BFS over StorageProvider for structured traversals.
+ */
+interface GraphTraversalProvider {
+    /**
+     * Execute a structured traversal compiled from a TraversalSpec.
+     * The library may pass both the spec and a pre-compiled query string.
+     * The provider can use either — the compiled query is a suggestion,
+     * not a requirement.
+     */
+    traverse(repositoryId: string, spec: TraversalSpec, compiledQuery?: string): Promise<TraversalResult>;
+    /**
+     * Execute a native graph query (Gremlin, Cypher, etc.).
+     * The library passes the query string through without modification.
+     * The provider is responsible for execution and result mapping.
+     *
+     * Implementers decide whether to expose this to agents.
+     * The library does not add safety guards — that is the implementer's
+     * responsibility.
+     */
+    executeNativeQuery(repositoryId: string, query: string, params?: Record<string, unknown>): Promise<TraversalResult>;
+    /**
+     * Report provider capabilities so the library can adapt
+     * DSL compilation and validate traversal specs accordingly.
+     */
+    getCapabilities(): GraphTraversalCapabilities;
+    /** Optional lifecycle hooks, matching StorageProvider pattern. */
+    initialise?(): Promise<void>;
+    dispose?(): Promise<void>;
+}
+interface GraphTraversalCapabilities {
+    /** Whether executeNativeQuery() is implemented. */
+    supportsNativeQuery: boolean;
+    /** The native query language, for DSL compilation targeting. */
+    nativeQueryLanguage: 'gremlin' | 'cypher' | 'sql' | 'other';
+    /** Maximum traversal depth the provider supports. */
+    maxTraversalDepth: number;
+    /** Whether the provider supports property filters on relationships during traversal. */
+    supportsRelationshipPropertyFilters: boolean;
+    /** Whether the provider supports property filters on entities during traversal. */
+    supportsEntityPropertyFilters: boolean;
+    /** Whether the provider supports aggregation (count, sum, avg) on terminal results. */
+    supportsAggregation: boolean;
+    /** Whether the provider supports repeat/loop traversal steps. */
+    supportsRepeat: boolean;
+    /** Whether the provider supports dedup across traversal results. */
+    supportsDedup: boolean;
+}
+
+export type { EmbeddingProvider, GraphTraversalCapabilities, GraphTraversalProvider, LockHandle, LockOptions, LockProvider, SearchProvider, SearchableEntity };

package/dist/testing/conformance.d.cts

@@ -1,5 +1,5 @@
-import { S as StorageProvider } from '../StorageProvider-CkFjdboX.cjs';
-import '../portability-DdlNYXGX.cjs';
+import { S as StorageProvider } from '../StorageProvider-C3tKhfuw.cjs';
+import '../portability-DdjsCB07.cjs';
 
 /**
  * Run the full StorageProvider conformance test suite.

package/dist/testing/conformance.d.ts

@@ -1,5 +1,5 @@
-import { S as StorageProvider } from '../StorageProvider-CJjz8uBY.js';
-import '../portability-DdlNYXGX.js';
+import { S as StorageProvider } from '../StorageProvider-DR9HLYHJ.js';
+import '../portability-DdjsCB07.js';
 
 /**
  * Run the full StorageProvider conformance test suite.

package/dist/traversal-9JdiqjZ9.d.ts

@@ -0,0 +1,177 @@
+import { P as PropertyFilter, D as DetailLevel, E as Entity, a as EntitySummary, b as EntityBrief } from './portability-DdjsCB07.js';
+
+/**
+ * A structured traversal specification that can be compiled to
+ * Gremlin, Cypher, or executed via application-level BFS.
+ *
+ * Designed to be expressible by AI agents without raw query
+ * language knowledge, while covering the common multi-hop
+ * traversal patterns needed for knowledge graph exploration.
+ */
+interface TraversalSpec {
+    /** Starting point for the traversal. */
+    start: TraversalStart;
+    /** Ordered sequence of traversal steps. */
+    steps: TraversalStep[];
+    /** What to return from the traversal. */
+    returnMode: TraversalReturnMode;
+    /**
+     * Maximum number of results to return.
+     * Default: 50. Max: 200.
+     * Applied to the final result set after traversal.
+     */
+    limit?: number;
+    /**
+     * Pagination offset for the final result set.
+     * Default: 0.
+     */
+    offset?: number;
+    /** Detail level for returned entities. Default: 'summary'. */
+    detailLevel?: DetailLevel;
+    /** Whether to deduplicate entities in the result set. Default: true. */
+    dedup?: boolean;
+}
+/** Where the traversal begins. */
+interface TraversalStart {
+    /** Start from a specific entity by ID (GUID) or slug. */
+    entityId?: string;
+    /** Start from all entities of a given type. Requires limit on the spec. */
+    entityType?: string;
+    /** Filter starting entities by property values. */
+    filter?: PropertyFilter[];
+}
+/**
+ * A single step in the traversal — one hop along a relationship edge.
+ */
+interface TraversalStep {
+    /** Direction to traverse. */
+    direction: 'out' | 'in' | 'both';
+    /**
+     * Relationship types to follow in this step.
+     * Validated against the repository vocabulary.
+     * If omitted, follows all relationship types.
+     */
+    relationshipTypes?: string[];
+    /**
+     * Filter target entities by type.
+     * If omitted, accepts all entity types.
+     */
+    entityTypes?: string[];
+    /** Filter relationships by property values during traversal. */
+    relationshipFilter?: PropertyFilter[];
+    /** Filter target entities by property values during traversal. */
+    entityFilter?: PropertyFilter[];
+    /**
+     * Repeat this step up to maxDepth times.
+     * Useful for variable-depth traversals like "find all sub-components
+     * at any depth" via repeated CONTAINS hops.
+     *
+     * When present, this step becomes a loop. The step's direction,
+     * relationshipTypes, and filters apply to each iteration.
+     */
+    repeat?: {
+        /**
+         * Maximum number of times to repeat this step.
+         * Mandatory — no unbounded recursion.
+         * Capped by provider's maxTraversalDepth.
+         */
+        maxDepth: number;
+        /**
+         * Stop condition: stop expanding a path when the current entity
+         * matches these filters. The matching entity IS included in results.
+         */
+        until?: PropertyFilter[];
+        /** Whether to include intermediate entities or only terminal ones. Default: true. */
+        emitIntermediates?: boolean;
+    };
+}
+/** What the traversal returns. */
+type TraversalReturnMode = 
+/** Return only entities at the final step (most common). */
+'terminal'
+/** Return full paths (all entities and relationships from start to end). */
+ | 'path'
+/** Return all entities encountered during traversal (every step). */
+ | 'all';
+/**
+ * Result of a graph traversal, including query metadata for
+ * implementers to use in audit, billing, and circuit breaker logic.
+ */
+interface TraversalResult {
+    /** Entities in the result set, projected to the requested detail level. */
+    entities: Array<Entity | EntitySummary | EntityBrief>;
+    /**
+     * Relationships in the result set.
+     * Present when returnMode is 'path' or 'all'.
+     */
+    relationships?: TraversalRelationship[];
+    /**
+     * Full paths from start to terminal entities.
+     * Present only when returnMode is 'path'.
+     */
+    paths?: TraversalPath[];
+    /** Total number of results matching the traversal (before limit/offset). */
+    total: number;
+    /** Number of results returned in this response. */
+    returned: number;
+    /** Whether more results exist beyond offset + limit. */
+    hasMore: boolean;
+    /** Query execution metadata. */
+    queryMetadata: QueryMetadata;
+}
+interface TraversalRelationship {
+    id: string;
+    type: string;
+    sourceEntityId: string;
+    targetEntityId: string;
+    direction: 'outbound' | 'inbound';
+    properties: Record<string, unknown>;
+}
+interface TraversalPath {
+    /** Number of hops in this path. */
+    length: number;
+    /** Ordered sequence of entities from start to end. */
+    entities: Array<Entity | EntitySummary | EntityBrief>;
+    /** Ordered sequence of relationships connecting the entities. */
+    relationships: TraversalRelationship[];
+}
+/**
+ * Metadata about query execution.
+ * Providers populate this from database response headers/metrics.
+ * Implementers use this for audit, billing, and circuit breaker logic.
+ */
+interface QueryMetadata {
+    /** Wall-clock execution time in milliseconds. */
+    executionTimeMs: number;
+    /**
+     * Provider-specific resource cost.
+     * CosmosDB: { units: 'RU', value: 42.3 }
+     * Neo4j: { units: 'db_hits', value: 1250 }
+     * SQL Server: { units: 'logical_reads', value: 340 }
+     */
+    resourceCost?: {
+        units: string;
+        value: number;
+    };
+    /**
+     * The native query that was actually executed.
+     * Useful for debugging DSL compilation and for implementers
+     * building query audit logs.
+     * Only populated when the traversal was compiled from a spec.
+     */
+    compiledQuery?: string;
+    /** The native query language of the compiled query. */
+    compiledQueryLanguage?: 'gremlin' | 'cypher' | 'sql';
+    /** Limits that were applied during execution. */
+    appliedLimits: {
+        timeoutMs?: number;
+        maxResults: number;
+        maxDepth?: number;
+    };
+    /** Whether the result was truncated by any limit. */
+    truncated: boolean;
+    /** Reason for truncation, if truncated. */
+    truncationReason?: 'result_limit' | 'timeout' | 'cost_limit' | 'depth_limit';
+}
+
+export type { QueryMetadata as Q, TraversalSpec as T, TraversalResult as a, TraversalPath as b, TraversalRelationship as c, TraversalReturnMode as d, TraversalStart as e, TraversalStep as f };

package/dist/traversal-BB_yERbf.d.cts

@@ -0,0 +1,177 @@
+import { P as PropertyFilter, D as DetailLevel, E as Entity, a as EntitySummary, b as EntityBrief } from './portability-DdjsCB07.cjs';
+
+/**
+ * A structured traversal specification that can be compiled to
+ * Gremlin, Cypher, or executed via application-level BFS.
+ *
+ * Designed to be expressible by AI agents without raw query
+ * language knowledge, while covering the common multi-hop
+ * traversal patterns needed for knowledge graph exploration.
+ */
+interface TraversalSpec {
+    /** Starting point for the traversal. */
+    start: TraversalStart;
+    /** Ordered sequence of traversal steps. */
+    steps: TraversalStep[];
+    /** What to return from the traversal. */
+    returnMode: TraversalReturnMode;
+    /**
+     * Maximum number of results to return.
+     * Default: 50. Max: 200.
+     * Applied to the final result set after traversal.
+     */
+    limit?: number;
+    /**
+     * Pagination offset for the final result set.
+     * Default: 0.
+     */
+    offset?: number;
+    /** Detail level for returned entities. Default: 'summary'. */
+    detailLevel?: DetailLevel;
+    /** Whether to deduplicate entities in the result set. Default: true. */
+    dedup?: boolean;
+}
+/** Where the traversal begins. */
+interface TraversalStart {
+    /** Start from a specific entity by ID (GUID) or slug. */
+    entityId?: string;
+    /** Start from all entities of a given type. Requires limit on the spec. */
+    entityType?: string;
+    /** Filter starting entities by property values. */
+    filter?: PropertyFilter[];
+}
+/**
+ * A single step in the traversal — one hop along a relationship edge.
+ */
+interface TraversalStep {
+    /** Direction to traverse. */
+    direction: 'out' | 'in' | 'both';
+    /**
+     * Relationship types to follow in this step.
+     * Validated against the repository vocabulary.
+     * If omitted, follows all relationship types.
+     */
+    relationshipTypes?: string[];
+    /**
+     * Filter target entities by type.
+     * If omitted, accepts all entity types.
+     */
+    entityTypes?: string[];
+    /** Filter relationships by property values during traversal. */
+    relationshipFilter?: PropertyFilter[];
+    /** Filter target entities by property values during traversal. */
+    entityFilter?: PropertyFilter[];
+    /**
+     * Repeat this step up to maxDepth times.
+     * Useful for variable-depth traversals like "find all sub-components
+     * at any depth" via repeated CONTAINS hops.
+     *
+     * When present, this step becomes a loop. The step's direction,
+     * relationshipTypes, and filters apply to each iteration.
+     */
+    repeat?: {
+        /**
+         * Maximum number of times to repeat this step.
+         * Mandatory — no unbounded recursion.
+         * Capped by provider's maxTraversalDepth.
+         */
+        maxDepth: number;
+        /**
+         * Stop condition: stop expanding a path when the current entity
+         * matches these filters. The matching entity IS included in results.
+         */
+        until?: PropertyFilter[];
+        /** Whether to include intermediate entities or only terminal ones. Default: true. */
+        emitIntermediates?: boolean;
+    };
+}
+/** What the traversal returns. */
+type TraversalReturnMode = 
+/** Return only entities at the final step (most common). */
+'terminal'
+/** Return full paths (all entities and relationships from start to end). */
+ | 'path'
+/** Return all entities encountered during traversal (every step). */
+ | 'all';
+/**
+ * Result of a graph traversal, including query metadata for
+ * implementers to use in audit, billing, and circuit breaker logic.
+ */
+interface TraversalResult {
+    /** Entities in the result set, projected to the requested detail level. */
+    entities: Array<Entity | EntitySummary | EntityBrief>;
+    /**
+     * Relationships in the result set.
+     * Present when returnMode is 'path' or 'all'.
+     */
+    relationships?: TraversalRelationship[];
+    /**
+     * Full paths from start to terminal entities.
+     * Present only when returnMode is 'path'.
+     */
+    paths?: TraversalPath[];
+    /** Total number of results matching the traversal (before limit/offset). */
+    total: number;
+    /** Number of results returned in this response. */
+    returned: number;
+    /** Whether more results exist beyond offset + limit. */
+    hasMore: boolean;
+    /** Query execution metadata. */
+    queryMetadata: QueryMetadata;
+}
+interface TraversalRelationship {
+    id: string;
+    type: string;
+    sourceEntityId: string;
+    targetEntityId: string;
+    direction: 'outbound' | 'inbound';
+    properties: Record<string, unknown>;
+}
+interface TraversalPath {
+    /** Number of hops in this path. */
+    length: number;
+    /** Ordered sequence of entities from start to end. */
+    entities: Array<Entity | EntitySummary | EntityBrief>;
+    /** Ordered sequence of relationships connecting the entities. */
+    relationships: TraversalRelationship[];
+}
+/**
+ * Metadata about query execution.
+ * Providers populate this from database response headers/metrics.
+ * Implementers use this for audit, billing, and circuit breaker logic.
+ */
+interface QueryMetadata {
+    /** Wall-clock execution time in milliseconds. */
+    executionTimeMs: number;
+    /**
+     * Provider-specific resource cost.
+     * CosmosDB: { units: 'RU', value: 42.3 }
+     * Neo4j: { units: 'db_hits', value: 1250 }
+     * SQL Server: { units: 'logical_reads', value: 340 }
+     */
+    resourceCost?: {
+        units: string;
+        value: number;
+    };
+    /**
+     * The native query that was actually executed.
+     * Useful for debugging DSL compilation and for implementers
+     * building query audit logs.
+     * Only populated when the traversal was compiled from a spec.
+     */
+    compiledQuery?: string;
+    /** The native query language of the compiled query. */
+    compiledQueryLanguage?: 'gremlin' | 'cypher' | 'sql';
+    /** Limits that were applied during execution. */
+    appliedLimits: {
+        timeoutMs?: number;
+        maxResults: number;
+        maxDepth?: number;
+    };
+    /** Whether the result was truncated by any limit. */
+    truncated: boolean;
+    /** Reason for truncation, if truncated. */
+    truncationReason?: 'result_limit' | 'timeout' | 'cost_limit' | 'depth_limit';
+}
+
+export type { QueryMetadata as Q, TraversalSpec as T, TraversalResult as a, TraversalPath as b, TraversalRelationship as c, TraversalReturnMode as d, TraversalStart as e, TraversalStep as f };