@utaba/deep-memory-storage-neo4j 0.19.0

package/dist/index.d.ts

@@ -0,0 +1,430 @@
+import { EnsureSchemaResult, EntityReadOptions, GraphTraversalCapabilities } from '@utaba/deep-memory/providers';
+import { UsageSink, StorageRepositoryConfig, StoredRepository, RepositoryFilter, PaginatedResult, StoredRepositorySummary, RepositoryUpdate, DeleteProgressCallback, MemoryVocabulary, PaginationOptions, VocabularyChangeRecord, StoredEntity, StoredEntityUpdate, StorageFindQuery, StoredRelationship, RelationshipQueryOptions, TraversalSpec, TraversalResult, StorageExploreOptions, StorageNeighborhood, StoragePathOptions, StoragePathResult, StorageTimelineOptions, StorageTimelineResult, ExportChunk, ImportChunk, BulkImportOptions, BulkImportResult, RepositoryStats } from '@utaba/deep-memory/types';
+
+/** Connection configuration. */
+interface Neo4jConnectionConfig {
+    /** Bolt URI, e.g. `bolt://localhost:7687` or `neo4j+s://aura-host`. */
+    uri: string;
+    /** Username for basic auth. */
+    username: string;
+    /** Password for basic auth. */
+    password: string;
+    /**
+     * Database name. Per the driver manual, this should be specified explicitly
+     * even on single-database Community instances. Defaults to `'neo4j'`.
+     */
+    database?: string;
+    /** User-agent string sent on the Bolt handshake. */
+    userAgent?: string;
+    /** Maximum time (ms) the driver will retry a managed transaction. */
+    maxTransactionRetryTime?: number;
+}
+
+/** Configuration for `Neo4jStorageProvider`. */
+interface Neo4jStorageProviderConfig extends Neo4jConnectionConfig {
+    /**
+     * Optional usage sink. When provided, the provider emits one
+     * `OperationUsage` record per public method call. The record's `value` is
+     * the aggregated `summary.resultConsumedAfter` (server-side ms) across
+     * every Bolt round-trip the operation produced; `unit` is `'server_ms'`.
+     *
+     * The sink is **never** plumbed through to AI-agent-facing surfaces — MCP
+     * tools must not expose RU / server-time figures to model responses.
+     */
+    reportUsage?: UsageSink;
+    /**
+     * When `true`, prepend `PROFILE` to every compiled traversal query and
+     * surface the resulting plan summary under `details.profile` on the sink
+     * record. Defaults to `false` — `PROFILE` more than doubles wall-clock on
+     * short traversals (see plan §D14 and the Phase 9 probe results), so the
+     * cost is worth paying only when an operator is actively investigating
+     * planner behaviour.
+     */
+    profileTraversals?: boolean;
+}
+declare class Neo4jStorageProvider {
+    private readonly connection;
+    private readonly traversalExecutor;
+    private initialized;
+    /**
+     * In-process vocabulary cache. Reads hit this map first; writes inside this
+     * process invalidate the entry so cache hits stay coherent with the local
+     * write. Cross-process staleness is bounded by `VOCABULARY_CACHE_TTL_MS`.
+     */
+    private readonly vocabularyCache;
+    /**
+     * Captured at construction so `exportAll`'s `trackIterable` can emit
+     * outside the Proxy's promise-resolution path. The Proxy itself relies on
+     * the same `safeSink` captured by closure; this field exists for the
+     * streaming-iterator case only.
+     */
+    private readonly reportUsage;
+    constructor(config: Neo4jStorageProviderConfig);
+    initialize(): Promise<void>;
+    dispose(): Promise<void>;
+    /**
+     * Idempotent constraint / index DDL plus a single `_Meta` schema-version
+     * handshake. Safe to call repeatedly — `CREATE ... IF NOT EXISTS` makes
+     * each statement a no-op on subsequent runs.
+     *
+     * Neo4j Community has no per-tenant database concept — `databaseCreated`
+     * is always `false`. Operators are responsible for the target database
+     * existing before the provider connects.
+     */
+    ensureSchema(): Promise<EnsureSchemaResult>;
+    private readSchemaVersion;
+    private writeSchemaVersion;
+    /**
+     * Create a new repository. Fixed-shape `CREATE` template — every optional
+     * field is bound on every call so the server plan-caches one entry across
+     * all repository creates. Optional fields bound as `null` are not persisted
+     * (Cypher drops null property values on write — symmetric with read).
+     *
+     * The `(:_Repository) REQUIRE n.repositoryId IS UNIQUE` constraint surfaces
+     * duplicates as `Neo.ClientError.Schema.ConstraintValidationFailed`, which
+     * `mapDriverError({ kind: 'repository', ... })` routes to
+     * `DuplicateRepositoryError`.
+     */
+    createRepository(config: StorageRepositoryConfig): Promise<StoredRepository>;
+    getRepository(repositoryId: string): Promise<StoredRepository | null>;
+    listRepositories(filter?: RepositoryFilter): Promise<PaginatedResult<StoredRepositorySummary>>;
+    /**
+     * Variable-shape Cypher (per D23 trade-off — repository writes are rare so
+     * the plan-cache cost is negligible). Projection-on-write returns the
+     * updated row in one round-trip; empty-rowset → `RepositoryNotFoundError`.
+     */
+    updateRepository(repositoryId: string, updates: RepositoryUpdate): Promise<StoredRepository>;
+    /**
+     * Drop every node and relationship scoped to `repositoryId`, including the
+     * `_Repository` node itself. Two-stage chunked wipe driven by app-side loops
+     * so the progress callback fires at a useful cadence:
+     *
+     *   1. Drain relationships in batches via `CALL ( ) { ... } IN TRANSACTIONS`.
+     *   2. Drain nodes (entities + system) in batches via the same form with
+     *      `DETACH DELETE` (catches any straggler edges).
+     *
+     * `IN TRANSACTIONS` can only run on auto-commit sessions — `executeWrite`
+     * fails with `Neo.DatabaseError.Transaction.TransactionStartFailed` per
+     * probe P13. The chokepoint's `executeImplicitInTransactions` is the only
+     * legitimate entry point for this pattern.
+     */
+    deleteRepository(repositoryId: string, onProgress?: DeleteProgressCallback): Promise<void>;
+    /**
+     * Drop every entity and relationship scoped to `repositoryId` but preserve
+     * the `_Repository` and `_Vocabulary` / `_VocabularyChangeLog` system nodes.
+     * Same chunked-wipe contract as `deleteRepository`, restricted to the
+     * `:_Entity` umbrella label for nodes.
+     */
+    deleteAllContents(repositoryId: string, onProgress?: DeleteProgressCallback): Promise<{
+        deletedEntities: number;
+        deletedRelationships: number;
+    }>;
+    /**
+     * One-shot pre-count used by `deleteRepository` / `deleteAllContents`. The
+     * entity count uses the umbrella `:_Entity` label so system nodes
+     * (`_Repository` / `_Vocabulary`) are excluded — that matches the
+     * user-facing semantics of the progress callback.
+     *
+     * The relationship count uses the **directed** pattern `()-[r]->()`: every
+     * edge is written in its stored direction (D5), so the directed pattern
+     * binds each edge to exactly one row. An undirected `-` pattern would
+     * double-count every edge whose endpoints are distinct vertices, because
+     * Cypher enumerates the pattern from both directions.
+     */
+    private countRepositoryContents;
+    /**
+     * Read the vocabulary for a repository. Cache-aware: cache hits return
+     * synchronously with zero Bolt round-trips. The TRACKED_METHODS proxy still
+     * fires for every call — the sink record on a cache hit carries
+     * `details.calls === 0` and `value === 0`, which is the contract the sink
+     * expects to express "this operation ran but did no server work".
+     */
+    getVocabulary(repositoryId: string): Promise<MemoryVocabulary>;
+    /**
+     * Cached vocabulary read used by `getVocabulary` and (in later phases) by
+     * traversal compilation. The vocabulary is compile-time context for the
+     * Cypher compiler — it changes on the order of once per session, but the
+     * traversal hot path would otherwise pay one round-trip per call. The cache
+     * flips that to one round-trip per TTL window.
+     *
+     * Reads inside an active usage scope still record a round-trip when a fetch
+     * actually happens (cache miss); cache hits emit no round-trip and therefore
+     * contribute nothing to the scope.
+     */
+    private getVocabularyCached;
+    /** Drop the cache entry for a repository — call after every vocabulary write. */
+    private invalidateVocabularyCache;
+    /**
+     * Upsert the vocabulary for a repository. Invalidates the in-process cache
+     * on success so subsequent reads observe the new state immediately within
+     * this process (cross-process staleness is bounded by the 60 s TTL).
+     */
+    saveVocabulary(repositoryId: string, vocabulary: MemoryVocabulary): Promise<void>;
+    /**
+     * Page the vocabulary change-log newest first. Writes land in
+     * `proposeVocabularyExtension` (out of scope here) — this method only reads
+     * the `_VocabularyChangeLog` nodes back, ordered by `proposedAt` to match
+     * the audit semantic on `VocabularyChangeRecord`.
+     */
+    getVocabularyChangeLog(repositoryId: string, options?: PaginationOptions): Promise<PaginatedResult<VocabularyChangeRecord>>;
+    /**
+     * Create a new entity via fixed-shape `CREATE` + catch on the uniqueness
+     * constraint. A `MERGE`-with-discriminator alternative is marginally faster
+     * on the happy path but mutates the existing node on collisions, writing
+     * a discriminator property onto durable graph state the caller never
+     * requested — correctness wins over the marginal perf delta.
+     */
+    createEntity(repositoryId: string, entity: StoredEntity): Promise<StoredEntity>;
+    /** Read a single entity by id; `null` when not found. */
+    getEntity(repositoryId: string, entityId: string, options?: EntityReadOptions): Promise<StoredEntity | null>;
+    /** Read a single entity by slug; `null` when not found. */
+    getEntityBySlug(repositoryId: string, slug: string, options?: EntityReadOptions): Promise<StoredEntity | null>;
+    /**
+     * Batch read by ids. Absent ids do not appear in the returned `Map`; empty
+     * input returns an empty map without a round-trip.
+     */
+    getEntities(repositoryId: string, entityIds: string[], options?: EntityReadOptions): Promise<Map<string, StoredEntity>>;
+    /**
+     * Variable-shape projection-on-write update (D23) — single round-trip
+     * MATCH+SET+RETURN. Empty record array → `EntityNotFoundError`.
+     */
+    updateEntity(repositoryId: string, entityId: string, updates: StoredEntityUpdate): Promise<StoredEntity>;
+    /**
+     * Delete a single entity (and its incident relationships via `DETACH
+     * DELETE`). Throws `EntityNotFoundError` when the match returns zero rows.
+     */
+    deleteEntity(repositoryId: string, entityId: string): Promise<void>;
+    /**
+     * Bulk delete by ids — single round-trip. Returns the ids actually
+     * deleted; missing ids land in `notFound`.
+     */
+    deleteEntities(repositoryId: string, ids: string[]): Promise<{
+        deleted: string[];
+        notFound: string[];
+    }>;
+    /**
+     * Delete every entity of a type plus their incident relationships, with
+     * exact counts (entity + relationship) returned in one round-trip — a
+     * strict improvement over Cosmos's `deletedRelationships: undefined` path
+     * (Gremlin would fan out across every partition the type touches).
+     */
+    deleteEntitiesByType(repositoryId: string, entityType: string): Promise<{
+        deletedEntities: number;
+        deletedRelationships: number | undefined;
+    }>;
+    /**
+     * Page entities matching a `StorageFindQuery`. Parallel data + count Cypher
+     * pair; `total` is always exact because every filter (entity-type, property
+     * equality, search term, provenance) is server-side via either a typed
+     * predicate or the `dm_entity_text` fulltext index. Search-term queries
+     * order by Lucene score descending; non-search queries order by `n.id` to
+     * pin pagination determinism across slices.
+     */
+    findEntities(repositoryId: string, query: StorageFindQuery, options?: EntityReadOptions): Promise<PaginatedResult<StoredEntity>>;
+    /**
+     * Create a relationship. Both endpoint entities are matched under the
+     * repository scope before the edge is created, so cross-repository edges
+     * are structurally impossible to write (D3b layer 3). A missing endpoint
+     * surfaces as `EntityNotFoundError` carrying the absent id.
+     */
+    createRelationship(repositoryId: string, relationship: StoredRelationship): Promise<StoredRelationship>;
+    /** Read a single relationship by id; `null` when not found. */
+    getRelationship(repositoryId: string, relationshipId: string): Promise<StoredRelationship | null>;
+    /**
+     * Page an entity's incident relationships. `direction: 'out' | 'in'`
+     * additionally surfaces edges flagged `bidirectional: true` from the
+     * opposite endpoint, mirroring the Cosmos read-time duplication of bidir
+     * edges. `propertyFilters` is applied client-side and reports
+     * `total: undefined` in that branch — same trade-off as the Cosmos
+     * provider, because relationship `properties` is a JSON blob with no
+     * per-key index.
+     */
+    getEntityRelationships(repositoryId: string, entityId: string, options?: RelationshipQueryOptions): Promise<PaginatedResult<StoredRelationship>>;
+    /** Drop a single relationship by id. No-op when the id does not match. */
+    deleteRelationship(repositoryId: string, relationshipId: string): Promise<void>;
+    /**
+     * Bulk drop by ids — single round-trip. Returns the ids actually deleted;
+     * missing ids land in `notFound`.
+     */
+    deleteRelationships(repositoryId: string, ids: string[]): Promise<{
+        deleted: string[];
+        notFound: string[];
+    }>;
+    /**
+     * Drop every relationship of a type in the repository. Returns an exact
+     * delete count in a single round-trip.
+     */
+    deleteRelationshipsByType(repositoryId: string, relationshipType: string): Promise<{
+        deletedRelationships: number;
+    }>;
+    /**
+     * Capabilities surface used by the dispatcher to decide whether a given
+     * `TraversalSpec` shape is supported natively. Strict improvement over the
+     * Cosmos provider in two cells: `supportsAggregation` is `true` (Cypher's
+     * native aggregation makes `count` / per-key projection a one-statement
+     * shape) and the runtime supports every other traversal lever.
+     */
+    getCapabilities(): GraphTraversalCapabilities;
+    /**
+     * Execute a `TraversalSpec` against this repository's subgraph. The
+     * provider owns Cypher compilation; the spec stays language-agnostic.
+     * `track('traverse')` opens the per-operation usage scope so every
+     * `executeQuery` round-trip the executor performs aggregates into a single
+     * `OperationUsage` record.
+     */
+    traverse(repositoryId: string, spec: TraversalSpec): Promise<TraversalResult>;
+    /**
+     * Internal compile → submit → project pipeline. Shared by the public
+     * `traverse` method and by the compiler-model rewrites of
+     * `exploreNeighborhood` / `findPaths`, which both consume the raw stored
+     * shape to rebuild their storage-level outputs.
+     */
+    private traverseInternal;
+    /**
+     * Lower-level compile + submit + parse helper. Fetches the cached
+     * vocabulary once (D16) and hands it to the executor; the executor handles
+     * the repositoryId-scope rewrite, optional PROFILE prefix, and Path-object
+     * parsing.
+     */
+    private executeRawTraversal;
+    /**
+     * BFS-like neighbourhood exploration. For each depth `d` from 1 to
+     * `options.depth`, compile a cumulative `'all'`-mode spec with `d` discrete
+     * `'both'`-direction steps, run it through the executor, and walk one BFS
+     * layer client-side from the previous frontier using the returned edges.
+     *
+     * Round-trips per call: `options.depth`. Server-side step direction is
+     * fixed to `'both'` (catches every edge in either direction); the
+     * directional + bidirectional filter and entity-type filter run client-side
+     * during layer reconstruction — both to preserve the observable contract
+     * shared with the Cosmos provider and because the compiler's prefix walk at
+     * each depth is intentionally unfiltered so deeper layers stay reachable
+     * through any intermediate.
+     */
+    exploreNeighborhood(repositoryId: string, entityId: string, options: StorageExploreOptions): Promise<StorageNeighborhood>;
+    /**
+     * Path finding between two entities. Single round-trip via a variable-length
+     * `MATCH p = (s)-[*1..N]-(t)` pattern; the compiler's path-binding emission
+     * lets the executor recover ordered nodes and relationships via `nodes(p)`
+     * / `relationships(p)`. The default `DIFFERENT RELATIONSHIPS` match mode in
+     * Cypher 25 prevents edge reuse within a single path — no explicit dedup
+     * filter is needed.
+     *
+     * The traversal walks the graph topologically regardless of relationship
+     * directionality (a path is defined by reachability, not semantic
+     * direction); entity-type and relationship-property filters apply during
+     * compilation, target filtering happens post-fetch.
+     */
+    findPaths(repositoryId: string, sourceId: string, targetId: string, options: StoragePathOptions): Promise<StoragePathResult>;
+    /**
+     * Reconstruct the timeline event stream for an entity. One server
+     * round-trip: the centre entity's provenance scalars plus every incident
+     * edge's id + createdAt arrive in a single tuple via `OPTIONAL MATCH +
+     * collect()`. The provider walks the row client-side to emit
+     * `entity:created` / `entity:updated` / `relationship:created` events.
+     *
+     * Cosmos pays two round-trips for the same information because Gremlin
+     * cannot bind an aggregated edge list to a vertex projection in one shot —
+     * a platform divergence, not an inherent trade-off.
+     */
+    getTimeline(repositoryId: string, entityId: string, options: StorageTimelineOptions): Promise<StorageTimelineResult>;
+    /**
+     * Stream every entity and every relationship in the repository as
+     * cursor-paginated chunks. Entities come first, then relationships; each
+     * chunk carries a monotonic `sequence` and an `isLast` flag.
+     *
+     * The Proxy-based tracking flow does not apply here. Tracked methods emit
+     * one sink record at promise resolution; an `AsyncIterable` returns
+     * synchronously, before any chunk has streamed. Instead, `trackIterable`
+     * wraps the underlying generator in its own `UsageScope` that opens at
+     * iterator creation, records each round-trip as the consumer pulls the
+     * next chunk, and emits one sink record when the iterator drains — so the
+     * resulting record aggregates server time across every chunk fetch.
+     */
+    exportAll(repositoryId: string): AsyncIterable<ExportChunk>;
+    /**
+     * Run a bulk import: every entity then every relationship from the input
+     * chunks lands in the repository. `skipExistenceCheck: true` uses CREATE
+     * for the absolute peak throughput; `false` (default) uses MERGE for
+     * idempotent re-imports.
+     *
+     * Returns a single aggregate `BulkImportResult` spanning every chunk.
+     * Per-row failures land in `result.errors`; surviving rows still count
+     * toward `entitiesImported` / `relationshipsImported`.
+     */
+    importBulk(repositoryId: string, data: ImportChunk[], options?: BulkImportOptions): Promise<BulkImportResult>;
+    /**
+     * Wrap an `AsyncIterable` so every chunk it produces is generated inside a
+     * single shared `UsageScope`. The scope aggregates `summary.resultConsumedAfter`
+     * across every round-trip the iterator performs; one sink record fires when
+     * the iterator drains (or is closed / thrown into).
+     *
+     * Implementation mirrors the Cosmos `trackIterable` precedent: each
+     * `iter.next()` call re-enters the scope via `runInUsageScope`. The
+     * `AsyncLocalStorage` chain links async work performed inside the
+     * generator body to the scope for the duration of that step. Between
+     * `next()` calls the scope is dormant — the consumer's awaits do not
+     * accumulate into it, which is exactly the desired semantics.
+     *
+     * When the sink is absent the wrap degenerates to a pass-through; the
+     * Proxy's `createSafeSink` short-circuit covers the no-sink case at
+     * construction time, so this method is only reached when `reportUsage` is
+     * present.
+     */
+    private trackIterable;
+    /**
+     * Aggregate repository statistics — entity / relationship totals, per-type
+     * breakdowns, vocabulary version. Two parallel native-aggregation round-
+     * trips (`count(n)` per `entityType`, `count(r)` per `type(r)`); the
+     * vocabulary version comes from the cached `_Vocabulary` node so a warm
+     * cache costs exactly two round-trips total.
+     *
+     * Strict improvement over Cosmos's Gremlin `.group().by().by(count())`
+     * shape — Cypher's native aggregation collapses each metric to a one-
+     * statement plan that hits the `(repositoryId, entityType)` and
+     * relationship-property indexes directly.
+     */
+    getRepositoryStats(repositoryId: string): Promise<RepositoryStats>;
+    /**
+     * Execute a raw Cypher statement with caller-supplied bindings.
+     *
+     * ⚠️  ELEVATED PRIVILEGE — SYSTEM-LEVEL OPERATION ⚠️
+     *
+     * This method is an unscoped pass-through: it does not filter by
+     * repository, does not inject the `$rid` binding, and performs no
+     * validation on the Cypher string. A single call can read or mutate any
+     * node or relationship in the database regardless of which repository it
+     * belongs to.
+     *
+     * DO NOT expose this method to AI agents, end users, or any untrusted
+     * caller. It is intended for:
+     *   - administrative tooling (migrations, diagnostics, repairs)
+     *   - internal library operations that need cross-repository reach
+     *
+     * `repositoryId` is accepted for interface symmetry but is intentionally
+     * ignored here — the caller is trusted to scope the query themselves.
+     * Because the call is cross-repository by design, the emitted usage
+     * record carries no `repositoryId` (see `TRACKED_METHODS`).
+     *
+     * For agent-facing graph queries use {@link traverse}, which enforces the
+     * repositoryId scope predicate.
+     */
+    executeNativeQuery(_repositoryId: string, query: string, params?: Record<string, unknown>): Promise<unknown[]>;
+}
+
+declare const SCHEMA_VERSION = 1;
+/**
+ * Returns the constraint / index DDL for the deep-memory Neo4j schema as an
+ * array of single statements. Each statement is idempotent via
+ * `IF NOT EXISTS`. Callers (the provider's `ensureSchema`, or operators
+ * running out-of-band against a managed Neo4j) execute the statements one by
+ * one.
+ *
+ * Composite uniqueness and lookup indexes all lead with `repositoryId` so the
+ * planner uses it as the cheap discriminator — see D3b layer 1 in the plan.
+ * The fulltext index is unfiltered; callers that query it must add an
+ * explicit `WHERE node.repositoryId = $rid` post-filter.
+ */
+declare function getSchemaCypher(): readonly string[];
+
+export { Neo4jStorageProvider, type Neo4jStorageProviderConfig, SCHEMA_VERSION, getSchemaCypher };