@utaba/deep-memory-storage-cosmosdb 0.8.1 → 0.9.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { StorageProvider, GraphTraversalProvider, EnsureSchemaResult, GraphTraversalCapabilities } from '@utaba/deep-memory/providers';
-import { StorageRepositoryConfig, StoredRepository, RepositoryFilter, PaginatedResult, StoredRepositorySummary, RepositoryUpdate, DeleteProgressCallback, RepositoryStats, MemoryVocabulary, PaginationOptions, VocabularyChangeRecord, StoredEntity, StoredEntityUpdate, StorageFindQuery, StoredRelationship, RelationshipQueryOptions, StorageExploreOptions, StorageNeighborhood, StoragePathOptions, StoragePathResult, StorageTimelineOptions, StorageTimelineResult, ExportChunk, ImportChunk, BulkImportOptions, BulkImportResult, TraversalSpec, TraversalResult } from '@utaba/deep-memory/types';
+import { UsageSink, StorageRepositoryConfig, StoredRepository, RepositoryFilter, PaginatedResult, StoredRepositorySummary, RepositoryUpdate, DeleteProgressCallback, RepositoryStats, MemoryVocabulary, PaginationOptions, VocabularyChangeRecord, StoredEntity, StoredEntityUpdate, StorageFindQuery, StoredRelationship, RelationshipQueryOptions, StorageExploreOptions, StorageNeighborhood, StoragePathOptions, StoragePathResult, StorageTimelineOptions, StorageTimelineResult, ExportChunk, ImportChunk, BulkImportOptions, BulkImportResult, TraversalSpec, TraversalResult } from '@utaba/deep-memory/types';
 import gremlin from 'gremlin';
 
 /** Configuration for CosmosDbProvider. */
@@ -22,6 +22,13 @@ interface CosmosDbProviderConfig {
     defaultTimeoutMs?: number;
     /** Whether to reject unauthorized TLS certs — set false for emulator (default: true) */
     rejectUnauthorized?: boolean;
+    /**
+     * Optional usage sink. When provided, the provider emits one
+     * {@link OperationUsage} record per public method call with the aggregated
+     * CosmosDB request charge (RU). Never exposed to AI agents — the MCP server
+     * deliberately does not plumb this sink through.
+     */
+    reportUsage?: UsageSink;
 }
 /**
  * CosmosDB Gremlin storage provider for deep-memory.
@@ -31,7 +38,22 @@ declare class CosmosDbProvider implements StorageProvider, GraphTraversalProvide
     private readonly conn;
     private readonly config;
     private readonly compiler;
+    private readonly reportUsage;
     constructor(config: CosmosDbProviderConfig);
+    /**
+     * Run the given operation inside an async-local usage scope. While the
+     * operation runs, every `conn.submit()` call accumulates its request charge
+     * into a shared accumulator. When the operation completes (success or
+     * failure), a single {@link OperationUsage} record is emitted to the sink.
+     *
+     * Nested public-method calls (e.g. `traverse` internally calls
+     * `getVocabulary`) are detected: the inner call joins the outer scope
+     * instead of starting a new one, so one user-visible operation produces
+     * exactly one usage record covering all its internal round-trips.
+     *
+     * If no sink is configured, this is a zero-overhead pass-through.
+     */
+    private track;
     /**
      * Reject any repositoryId that is not a valid v4 UUID.
      *
@@ -45,6 +67,7 @@ declare class CosmosDbProvider implements StorageProvider, GraphTraversalProvide
     initialize(): Promise<void>;
     dispose(): Promise<void>;
     ensureSchema(): Promise<EnsureSchemaResult>;
+    private ensureSchemaImpl;
     /** Derive the REST endpoint from config — either explicit or from the Gremlin endpoint host. */
     private getRestEndpoint;
     createRepository(config: StorageRepositoryConfig): Promise<StoredRepository>;
@@ -70,6 +93,7 @@ declare class CosmosDbProvider implements StorageProvider, GraphTraversalProvide
         deleted: string[];
         notFound: string[];
     }>;
+    private deleteEntitiesImpl;
     deleteEntitiesByType(repositoryId: string, entityType: string): Promise<{
         deletedEntities: number;
         deletedRelationships: number;
@@ -83,6 +107,7 @@ declare class CosmosDbProvider implements StorageProvider, GraphTraversalProvide
         deleted: string[];
         notFound: string[];
     }>;
+    private deleteRelationshipsImpl;
     deleteRelationshipsByType(repositoryId: string, relationshipType: string): Promise<{
         deletedRelationships: number;
     }>;
@@ -91,8 +116,16 @@ declare class CosmosDbProvider implements StorageProvider, GraphTraversalProvide
     getTimeline(repositoryId: string, entityId: string, options: StorageTimelineOptions): Promise<StorageTimelineResult>;
     exportAll(repositoryId: string): AsyncIterable<ExportChunk>;
     importBulk(repositoryId: string, data: ImportChunk[], options?: BulkImportOptions): Promise<BulkImportResult>;
+    /**
+     * Wrap an AsyncIterable so every emitted chunk is generated inside the
+     * usage scope. On each iteration step, the scope aggregates charges from
+     * the next chunk's submits; when the iterator completes (or is closed), a
+     * single usage record is emitted for the whole stream.
+     */
+    private trackIterable;
     getCapabilities(): GraphTraversalCapabilities;
     traverse(repositoryId: string, spec: TraversalSpec): Promise<TraversalResult>;
+    private traverseImpl;
     /**
      * Execute a raw Gremlin query with caller-supplied bindings.
      *
@@ -115,6 +148,7 @@ declare class CosmosDbProvider implements StorageProvider, GraphTraversalProvide
      * repositoryId partition predicate.
      */
     executeNativeQuery(_repositoryId: string, query: string, params?: Record<string, unknown>): Promise<TraversalResult>;
+    private executeNativeQueryImpl;
 }
 
 interface CosmosDbConnectionConfig {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { StorageProvider, GraphTraversalProvider, EnsureSchemaResult, GraphTraversalCapabilities } from '@utaba/deep-memory/providers';
-import { StorageRepositoryConfig, StoredRepository, RepositoryFilter, PaginatedResult, StoredRepositorySummary, RepositoryUpdate, DeleteProgressCallback, RepositoryStats, MemoryVocabulary, PaginationOptions, VocabularyChangeRecord, StoredEntity, StoredEntityUpdate, StorageFindQuery, StoredRelationship, RelationshipQueryOptions, StorageExploreOptions, StorageNeighborhood, StoragePathOptions, StoragePathResult, StorageTimelineOptions, StorageTimelineResult, ExportChunk, ImportChunk, BulkImportOptions, BulkImportResult, TraversalSpec, TraversalResult } from '@utaba/deep-memory/types';
+import { UsageSink, StorageRepositoryConfig, StoredRepository, RepositoryFilter, PaginatedResult, StoredRepositorySummary, RepositoryUpdate, DeleteProgressCallback, RepositoryStats, MemoryVocabulary, PaginationOptions, VocabularyChangeRecord, StoredEntity, StoredEntityUpdate, StorageFindQuery, StoredRelationship, RelationshipQueryOptions, StorageExploreOptions, StorageNeighborhood, StoragePathOptions, StoragePathResult, StorageTimelineOptions, StorageTimelineResult, ExportChunk, ImportChunk, BulkImportOptions, BulkImportResult, TraversalSpec, TraversalResult } from '@utaba/deep-memory/types';
 import gremlin from 'gremlin';
 
 /** Configuration for CosmosDbProvider. */
@@ -22,6 +22,13 @@ interface CosmosDbProviderConfig {
     defaultTimeoutMs?: number;
     /** Whether to reject unauthorized TLS certs — set false for emulator (default: true) */
     rejectUnauthorized?: boolean;
+    /**
+     * Optional usage sink. When provided, the provider emits one
+     * {@link OperationUsage} record per public method call with the aggregated
+     * CosmosDB request charge (RU). Never exposed to AI agents — the MCP server
+     * deliberately does not plumb this sink through.
+     */
+    reportUsage?: UsageSink;
 }
 /**
  * CosmosDB Gremlin storage provider for deep-memory.
@@ -31,7 +38,22 @@ declare class CosmosDbProvider implements StorageProvider, GraphTraversalProvide
     private readonly conn;
     private readonly config;
     private readonly compiler;
+    private readonly reportUsage;
     constructor(config: CosmosDbProviderConfig);
+    /**
+     * Run the given operation inside an async-local usage scope. While the
+     * operation runs, every `conn.submit()` call accumulates its request charge
+     * into a shared accumulator. When the operation completes (success or
+     * failure), a single {@link OperationUsage} record is emitted to the sink.
+     *
+     * Nested public-method calls (e.g. `traverse` internally calls
+     * `getVocabulary`) are detected: the inner call joins the outer scope
+     * instead of starting a new one, so one user-visible operation produces
+     * exactly one usage record covering all its internal round-trips.
+     *
+     * If no sink is configured, this is a zero-overhead pass-through.
+     */
+    private track;
     /**
      * Reject any repositoryId that is not a valid v4 UUID.
      *
@@ -45,6 +67,7 @@ declare class CosmosDbProvider implements StorageProvider, GraphTraversalProvide
     initialize(): Promise<void>;
     dispose(): Promise<void>;
     ensureSchema(): Promise<EnsureSchemaResult>;
+    private ensureSchemaImpl;
     /** Derive the REST endpoint from config — either explicit or from the Gremlin endpoint host. */
     private getRestEndpoint;
     createRepository(config: StorageRepositoryConfig): Promise<StoredRepository>;
@@ -70,6 +93,7 @@ declare class CosmosDbProvider implements StorageProvider, GraphTraversalProvide
         deleted: string[];
         notFound: string[];
     }>;
+    private deleteEntitiesImpl;
     deleteEntitiesByType(repositoryId: string, entityType: string): Promise<{
         deletedEntities: number;
         deletedRelationships: number;
@@ -83,6 +107,7 @@ declare class CosmosDbProvider implements StorageProvider, GraphTraversalProvide
         deleted: string[];
         notFound: string[];
     }>;
+    private deleteRelationshipsImpl;
     deleteRelationshipsByType(repositoryId: string, relationshipType: string): Promise<{
         deletedRelationships: number;
     }>;
@@ -91,8 +116,16 @@ declare class CosmosDbProvider implements StorageProvider, GraphTraversalProvide
     getTimeline(repositoryId: string, entityId: string, options: StorageTimelineOptions): Promise<StorageTimelineResult>;
     exportAll(repositoryId: string): AsyncIterable<ExportChunk>;
     importBulk(repositoryId: string, data: ImportChunk[], options?: BulkImportOptions): Promise<BulkImportResult>;
+    /**
+     * Wrap an AsyncIterable so every emitted chunk is generated inside the
+     * usage scope. On each iteration step, the scope aggregates charges from
+     * the next chunk's submits; when the iterator completes (or is closed), a
+     * single usage record is emitted for the whole stream.
+     */
+    private trackIterable;
     getCapabilities(): GraphTraversalCapabilities;
     traverse(repositoryId: string, spec: TraversalSpec): Promise<TraversalResult>;
+    private traverseImpl;
     /**
      * Execute a raw Gremlin query with caller-supplied bindings.
      *
@@ -115,6 +148,7 @@ declare class CosmosDbProvider implements StorageProvider, GraphTraversalProvide
      * repositoryId partition predicate.
      */
     executeNativeQuery(_repositoryId: string, query: string, params?: Record<string, unknown>): Promise<TraversalResult>;
+    private executeNativeQueryImpl;
 }
 
 interface CosmosDbConnectionConfig {

package/dist/index.js

@@ -1,9 +1,11 @@
 // src/CosmosDbProvider.ts
 import crypto from "crypto";
-import { GremlinCompiler, ProviderError, InvalidInputError, isValidUuid, projectEntity } from "@utaba/deep-memory";
+import { GremlinCompiler, ProviderError, InvalidInputError, isValidUuid, projectEntity, createSafeSink } from "@utaba/deep-memory";
 
 // src/CosmosDbConnection.ts
 import gremlin from "gremlin";
+import { AsyncLocalStorage } from "async_hooks";
+var usageScope = new AsyncLocalStorage();
 var CosmosDbConnection = class {
   client = null;
   config;
@@ -51,11 +53,18 @@ var CosmosDbConnection = class {
         const resultSet = await this.client.submit(query, bindings);
         const items = resultSet.toArray();
         const requestCharge = extractRequestCharge(resultSet);
+        const acc = usageScope.getStore();
+        if (acc) {
+          acc.calls++;
+          if (typeof requestCharge === "number") acc.ru += requestCharge;
+        }
         return { items, requestCharge };
       } catch (err) {
         lastError = err;
         if (isTransientError(err) && attempt < this.config.maxRetries) {
           const retryAfterMs = getRetryAfterMs(err, attempt);
+          const acc = usageScope.getStore();
+          if (acc) acc.retries++;
           await sleep(retryAfterMs);
           continue;
         }
@@ -1291,14 +1300,17 @@ async function upsertRelationship(conn, repositoryId, rel) {
 }
 
 // src/CosmosDbProvider.ts
+var PROVIDER_NAME = "cosmosdb";
 var SCHEMA_VERSION = 1;
 var META_VERTEX_ID = "_meta:schema";
 var CosmosDbProvider = class {
   conn;
   config;
   compiler = new GremlinCompiler();
+  reportUsage;
   constructor(config) {
     this.config = config;
+    this.reportUsage = createSafeSink(config.reportUsage);
     this.conn = new CosmosDbConnection({
       endpoint: config.endpoint,
       key: config.key,
@@ -1309,6 +1321,39 @@ var CosmosDbProvider = class {
       rejectUnauthorized: config.rejectUnauthorized
     });
   }
+  /**
+   * Run the given operation inside an async-local usage scope. While the
+   * operation runs, every `conn.submit()` call accumulates its request charge
+   * into a shared accumulator. When the operation completes (success or
+   * failure), a single {@link OperationUsage} record is emitted to the sink.
+   *
+   * Nested public-method calls (e.g. `traverse` internally calls
+   * `getVocabulary`) are detected: the inner call joins the outer scope
+   * instead of starting a new one, so one user-visible operation produces
+   * exactly one usage record covering all its internal round-trips.
+   *
+   * If no sink is configured, this is a zero-overhead pass-through.
+   */
+  async track(operation, repositoryId, fn) {
+    if (!this.reportUsage) return fn();
+    if (usageScope.getStore()) return fn();
+    const acc = { ru: 0, calls: 0, retries: 0 };
+    try {
+      return await usageScope.run(acc, fn);
+    } finally {
+      if (acc.calls > 0) {
+        this.reportUsage({
+          provider: PROVIDER_NAME,
+          operation,
+          unit: "RU",
+          value: acc.ru,
+          ...repositoryId ? { repositoryId } : {},
+          timestamp: /* @__PURE__ */ new Date(),
+          details: { calls: acc.calls, retries: acc.retries }
+        });
+      }
+    }
+  }
   /**
    * Reject any repositoryId that is not a valid v4 UUID.
    *
@@ -1334,6 +1379,9 @@ var CosmosDbProvider = class {
     await this.conn.close();
   }
   async ensureSchema() {
+    return this.track("ensureSchema", void 0, () => this.ensureSchemaImpl());
+  }
+  async ensureSchemaImpl() {
     const restBase = this.getRestEndpoint();
     const partitionKey = this.config.partitionKey ?? "/repositoryId";
     let databaseCreated = false;
@@ -1412,72 +1460,139 @@ var CosmosDbProvider = class {
   // ─── Repository ────────────────────────────────────────────────────
   async createRepository(config) {
     this.assertValidRepositoryId(config.repositoryId);
-    return createRepository(this.conn, config);
+    return this.track(
+      "createRepository",
+      config.repositoryId,
+      () => createRepository(this.conn, config)
+    );
   }
   async getRepository(repositoryId) {
     this.assertValidRepositoryId(repositoryId);
-    return getRepository(this.conn, repositoryId);
+    return this.track(
+      "getRepository",
+      repositoryId,
+      () => getRepository(this.conn, repositoryId)
+    );
   }
   async listRepositories(filter) {
-    return listRepositories(this.conn, filter);
+    return this.track(
+      "listRepositories",
+      void 0,
+      () => listRepositories(this.conn, filter)
+    );
   }
   async updateRepository(repositoryId, updates) {
     this.assertValidRepositoryId(repositoryId);
-    return updateRepository(this.conn, repositoryId, updates);
+    return this.track(
+      "updateRepository",
+      repositoryId,
+      () => updateRepository(this.conn, repositoryId, updates)
+    );
   }
   async deleteRepository(repositoryId, onProgress) {
     this.assertValidRepositoryId(repositoryId);
-    return deleteRepository(this.conn, repositoryId, onProgress);
+    return this.track(
+      "deleteRepository",
+      repositoryId,
+      () => deleteRepository(this.conn, repositoryId, onProgress)
+    );
   }
   async deleteAllContents(repositoryId, onProgress) {
     this.assertValidRepositoryId(repositoryId);
-    return deleteAllContents(this.conn, repositoryId, onProgress);
+    return this.track(
+      "deleteAllContents",
+      repositoryId,
+      () => deleteAllContents(this.conn, repositoryId, onProgress)
+    );
   }
   async getRepositoryStats(repositoryId) {
     this.assertValidRepositoryId(repositoryId);
-    return getRepositoryStats(this.conn, repositoryId);
+    return this.track(
+      "getRepositoryStats",
+      repositoryId,
+      () => getRepositoryStats(this.conn, repositoryId)
+    );
   }
   // ─── Vocabulary ────────────────────────────────────────────────────
   async getVocabulary(repositoryId) {
     this.assertValidRepositoryId(repositoryId);
-    return getVocabulary(this.conn, repositoryId);
+    return this.track(
+      "getVocabulary",
+      repositoryId,
+      () => getVocabulary(this.conn, repositoryId)
+    );
   }
   async saveVocabulary(repositoryId, vocabulary) {
     this.assertValidRepositoryId(repositoryId);
-    return saveVocabulary(this.conn, repositoryId, vocabulary);
+    return this.track(
+      "saveVocabulary",
+      repositoryId,
+      () => saveVocabulary(this.conn, repositoryId, vocabulary)
+    );
   }
   async getVocabularyChangeLog(repositoryId, options) {
     this.assertValidRepositoryId(repositoryId);
-    return getVocabularyChangeLog(this.conn, repositoryId, options);
+    return this.track(
+      "getVocabularyChangeLog",
+      repositoryId,
+      () => getVocabularyChangeLog(this.conn, repositoryId, options)
+    );
   }
   // ─── Entities ──────────────────────────────────────────────────────
   async createEntity(repositoryId, entity) {
     this.assertValidRepositoryId(repositoryId);
-    return createEntity(this.conn, repositoryId, entity);
+    return this.track(
+      "createEntity",
+      repositoryId,
+      () => createEntity(this.conn, repositoryId, entity)
+    );
   }
   async getEntity(repositoryId, entityId) {
     this.assertValidRepositoryId(repositoryId);
-    return getEntity(this.conn, repositoryId, entityId);
+    return this.track(
+      "getEntity",
+      repositoryId,
+      () => getEntity(this.conn, repositoryId, entityId)
+    );
   }
   async getEntityBySlug(repositoryId, slug) {
     this.assertValidRepositoryId(repositoryId);
-    return getEntityBySlug(this.conn, repositoryId, slug);
+    return this.track(
+      "getEntityBySlug",
+      repositoryId,
+      () => getEntityBySlug(this.conn, repositoryId, slug)
+    );
   }
   async getEntities(repositoryId, entityIds) {
     this.assertValidRepositoryId(repositoryId);
-    return getEntities(this.conn, repositoryId, entityIds);
+    return this.track(
+      "getEntities",
+      repositoryId,
+      () => getEntities(this.conn, repositoryId, entityIds)
+    );
   }
   async updateEntity(repositoryId, entityId, updates) {
     this.assertValidRepositoryId(repositoryId);
-    return updateEntity(this.conn, repositoryId, entityId, updates);
+    return this.track(
+      "updateEntity",
+      repositoryId,
+      () => updateEntity(this.conn, repositoryId, entityId, updates)
+    );
   }
   async deleteEntity(repositoryId, entityId) {
     this.assertValidRepositoryId(repositoryId);
-    return deleteEntity(this.conn, repositoryId, entityId);
+    return this.track(
+      "deleteEntity",
+      repositoryId,
+      () => deleteEntity(this.conn, repositoryId, entityId)
+    );
   }
   async deleteEntities(repositoryId, ids) {
     if (ids.length === 0) return { deleted: [], notFound: [] };
     this.assertValidRepositoryId(repositoryId);
+    return this.track("deleteEntities", repositoryId, () => this.deleteEntitiesImpl(repositoryId, ids));
+  }
+  async deleteEntitiesImpl(repositoryId, ids) {
     const deleted = [];
     const CHUNK = 100;
     for (let i = 0; i < ids.length; i += CHUNK) {
@@ -1516,32 +1631,59 @@ var CosmosDbProvider = class {
   }
   async deleteEntitiesByType(repositoryId, entityType) {
     this.assertValidRepositoryId(repositoryId);
-    return deleteEntitiesByType(this.conn, repositoryId, entityType);
+    return this.track(
+      "deleteEntitiesByType",
+      repositoryId,
+      () => deleteEntitiesByType(this.conn, repositoryId, entityType)
+    );
   }
   async findEntities(repositoryId, query) {
     this.assertValidRepositoryId(repositoryId);
-    return findEntities(this.conn, repositoryId, query);
+    return this.track(
+      "findEntities",
+      repositoryId,
+      () => findEntities(this.conn, repositoryId, query)
+    );
   }
   // ─── Relationships ─────────────────────────────────────────────────
   async createRelationship(repositoryId, relationship) {
     this.assertValidRepositoryId(repositoryId);
-    return createRelationship(this.conn, repositoryId, relationship);
+    return this.track(
+      "createRelationship",
+      repositoryId,
+      () => createRelationship(this.conn, repositoryId, relationship)
+    );
   }
   async getRelationship(repositoryId, relationshipId) {
     this.assertValidRepositoryId(repositoryId);
-    return getRelationship(this.conn, repositoryId, relationshipId);
+    return this.track(
+      "getRelationship",
+      repositoryId,
+      () => getRelationship(this.conn, repositoryId, relationshipId)
+    );
   }
   async getEntityRelationships(repositoryId, entityId, options) {
     this.assertValidRepositoryId(repositoryId);
-    return getEntityRelationships(this.conn, repositoryId, entityId, options);
+    return this.track(
+      "getEntityRelationships",
+      repositoryId,
+      () => getEntityRelationships(this.conn, repositoryId, entityId, options)
+    );
   }
   async deleteRelationship(repositoryId, relationshipId) {
     this.assertValidRepositoryId(repositoryId);
-    return deleteRelationship(this.conn, repositoryId, relationshipId);
+    return this.track(
+      "deleteRelationship",
+      repositoryId,
+      () => deleteRelationship(this.conn, repositoryId, relationshipId)
+    );
   }
   async deleteRelationships(repositoryId, ids) {
     if (ids.length === 0) return { deleted: [], notFound: [] };
     this.assertValidRepositoryId(repositoryId);
+    return this.track("deleteRelationships", repositoryId, () => this.deleteRelationshipsImpl(repositoryId, ids));
+  }
+  async deleteRelationshipsImpl(repositoryId, ids) {
     const deleted = [];
     const CHUNK = 100;
     for (let i = 0; i < ids.length; i += CHUNK) {
@@ -1577,30 +1719,99 @@ var CosmosDbProvider = class {
   }
   async deleteRelationshipsByType(repositoryId, relationshipType) {
     this.assertValidRepositoryId(repositoryId);
-    return deleteRelationshipsByType(this.conn, repositoryId, relationshipType);
+    return this.track(
+      "deleteRelationshipsByType",
+      repositoryId,
+      () => deleteRelationshipsByType(this.conn, repositoryId, relationshipType)
+    );
   }
   // ─── Graph Traversal (StorageProvider) ─────────────────────────────
   async exploreNeighborhood(repositoryId, entityId, options) {
     this.assertValidRepositoryId(repositoryId);
-    return exploreNeighborhood(this.conn, repositoryId, entityId, options);
+    return this.track(
+      "exploreNeighborhood",
+      repositoryId,
+      () => exploreNeighborhood(this.conn, repositoryId, entityId, options)
+    );
   }
   async findPaths(repositoryId, sourceId, targetId, options) {
     this.assertValidRepositoryId(repositoryId);
-    return findPaths(this.conn, repositoryId, sourceId, targetId, options);
+    return this.track(
+      "findPaths",
+      repositoryId,
+      () => findPaths(this.conn, repositoryId, sourceId, targetId, options)
+    );
   }
   // ─── Timeline ──────────────────────────────────────────────────────
   async getTimeline(repositoryId, entityId, options) {
     this.assertValidRepositoryId(repositoryId);
-    return getTimeline(this.conn, repositoryId, entityId, options);
+    return this.track(
+      "getTimeline",
+      repositoryId,
+      () => getTimeline(this.conn, repositoryId, entityId, options)
+    );
   }
   // ─── Bulk Operations ───────────────────────────────────────────────
   exportAll(repositoryId) {
     this.assertValidRepositoryId(repositoryId);
-    return exportAll(this.conn, repositoryId);
+    return this.trackIterable("exportAll", repositoryId, exportAll(this.conn, repositoryId));
   }
   async importBulk(repositoryId, data, options) {
     this.assertValidRepositoryId(repositoryId);
-    return importBulk(this.conn, repositoryId, data, options);
+    return this.track(
+      "importBulk",
+      repositoryId,
+      () => importBulk(this.conn, repositoryId, data, options)
+    );
+  }
+  /**
+   * Wrap an AsyncIterable so every emitted chunk is generated inside the
+   * usage scope. On each iteration step, the scope aggregates charges from
+   * the next chunk's submits; when the iterator completes (or is closed), a
+   * single usage record is emitted for the whole stream.
+   */
+  trackIterable(operation, repositoryId, source) {
+    if (!this.reportUsage) return source;
+    const sink = this.reportUsage;
+    return {
+      [Symbol.asyncIterator]: () => {
+        const iter = source[Symbol.asyncIterator]();
+        const acc = { ru: 0, calls: 0, retries: 0 };
+        let emitted = false;
+        const emit = () => {
+          if (emitted) return;
+          emitted = true;
+          if (acc.calls > 0) {
+            sink({
+              provider: PROVIDER_NAME,
+              operation,
+              unit: "RU",
+              value: acc.ru,
+              repositoryId,
+              timestamp: /* @__PURE__ */ new Date(),
+              details: { calls: acc.calls, retries: acc.retries }
+            });
+          }
+        };
+        return {
+          async next() {
+            const step = await usageScope.run(acc, () => iter.next());
+            if (step.done) emit();
+            return step;
+          },
+          async return(value) {
+            emit();
+            if (iter.return) return iter.return(value);
+            return { done: true, value };
+          },
+          async throw(err) {
+            emit();
+            if (iter.throw) return iter.throw(err);
+            throw err;
+          }
+        };
+      }
+    };
   }
   // ─── GraphTraversalProvider ────────────────────────────────────────
   getCapabilities() {
@@ -1618,6 +1829,9 @@ var CosmosDbProvider = class {
   }
   async traverse(repositoryId, spec) {
     this.assertValidRepositoryId(repositoryId);
+    return this.track("traverse", repositoryId, () => this.traverseImpl(repositoryId, spec));
+  }
+  async traverseImpl(repositoryId, spec) {
     const startTime = Date.now();
     const vocabulary = await this.getVocabulary(repositoryId);
     const compiled = this.compiler.compile(spec, vocabulary);
@@ -1711,6 +1925,9 @@ var CosmosDbProvider = class {
    * repositoryId partition predicate.
    */
   async executeNativeQuery(_repositoryId, query, params) {
+    return this.track("executeNativeQuery", void 0, () => this.executeNativeQueryImpl(query, params));
+  }
+  async executeNativeQueryImpl(query, params) {
     const startTime = Date.now();
     try {
       const result = await this.conn.submit(query, params);