@aouda/client 0.1.13 → 0.1.15

package/dist/index.cjs

@@ -60,6 +60,7 @@ __export(index_exports, {
   MaterializedQueriesApi: () => MaterializedQueriesApi,
   MaterializedQueryState: () => MaterializedQueryState,
   MaterializedQueryType: () => MaterializedQueryType,
+  MemoryConsistencyTokenStore: () => MemoryConsistencyTokenStore,
   MetricsAdminApi: () => MetricsAdminApi,
   NamedMutationsApi: () => NamedMutationsApi,
   NamedQueriesApi: () => NamedQueriesApi,
@@ -75,10 +76,12 @@ __export(index_exports, {
   applyLocalNetworkAccess: () => applyLocalNetworkAccess,
   coerceColumnarValue: () => coerceColumnarValue,
   columnarToRows: () => columnarToRows,
+  compareOrdinal: () => compareOrdinal,
   createAoudaClient: () => createAoudaClient,
   createAoudaClusterMcpToolSet: () => createAoudaClusterMcpToolSet,
   installLocalNetworkFetch: () => installLocalNetworkFetch,
   localNetworkFetch: () => localNetworkFetch,
+  maxToken: () => maxToken,
   resolveTargetAddressSpace: () => resolveTargetAddressSpace,
   version: () => version
 });
@@ -87,7 +90,7 @@ module.exports = __toCommonJS(index_exports);
 // package.json
 var package_default = {
   name: "@aouda/client",
-  version: "0.1.13",
+  version: "0.1.15",
   description: "Official TypeScript/JavaScript client library for Aouda",
   type: "module",
   main: "./dist/index.cjs",
@@ -219,43 +222,44 @@ var AoudaResponseError = class extends AoudaError {
   }
 };
 var AoudaApiError = class extends AoudaError {
-  constructor(message, code, statusCode, details, requestId, retryAfterSeconds) {
+  constructor(message, code, statusCode, details, requestId, retryAfterSeconds, token) {
     super(message);
     this.code = code;
     this.statusCode = statusCode;
     this.details = details;
     this.requestId = requestId;
     this.retryAfterSeconds = retryAfterSeconds;
+    this.token = token;
     this.name = "AoudaApiError";
   }
 };
 var AoudaNotFoundError = class extends AoudaApiError {
-  constructor(message, code, statusCode, details, requestId) {
-    super(message, code, statusCode, details, requestId);
+  constructor(message, code, statusCode, details, requestId, retryAfterSeconds, token) {
+    super(message, code, statusCode, details, requestId, retryAfterSeconds, token);
     this.name = "AoudaNotFoundError";
   }
 };
 var AoudaConflictError = class extends AoudaApiError {
-  constructor(message, code, statusCode, details, requestId) {
-    super(message, code, statusCode, details, requestId);
+  constructor(message, code, statusCode, details, requestId, retryAfterSeconds, token) {
+    super(message, code, statusCode, details, requestId, retryAfterSeconds, token);
     this.name = "AoudaConflictError";
   }
 };
 var AoudaValidationError = class extends AoudaApiError {
-  constructor(message, code, statusCode, details, requestId) {
-    super(message, code, statusCode, details, requestId);
+  constructor(message, code, statusCode, details, requestId, retryAfterSeconds, token) {
+    super(message, code, statusCode, details, requestId, retryAfterSeconds, token);
     this.name = "AoudaValidationError";
   }
 };
 var AoudaServerError = class extends AoudaApiError {
-  constructor(message, code, statusCode, details, requestId, retryAfterSeconds) {
-    super(message, code, statusCode, details, requestId, retryAfterSeconds);
+  constructor(message, code, statusCode, details, requestId, retryAfterSeconds, token) {
+    super(message, code, statusCode, details, requestId, retryAfterSeconds, token);
     this.name = "AoudaServerError";
   }
 };
 var AoudaAuthenticationError = class extends AoudaApiError {
-  constructor(message, code, statusCode, details, requestId) {
-    super(message, code, statusCode, details, requestId);
+  constructor(message, code, statusCode, details, requestId, retryAfterSeconds, token) {
+    super(message, code, statusCode, details, requestId, retryAfterSeconds, token);
     this.name = "AoudaAuthenticationError";
   }
 };
@@ -1067,7 +1071,7 @@ function buildHandle(jobId, commitResp, wasResumed, transport, database, signal)
     rowsDurablyCommitted: commitResp.rowsLoaded,
     segmentsCreated: commitResp.segmentsCreated,
     committedAtUtc: commitResp.committedAtUtc,
-    walPosition: commitResp.walPosition,
+    token: commitResp.token,
     writeConcernSatisfied: commitResp.writeConcernAchieved ?? "acknowledged",
     writeConcernTimedOut: commitResp.writeConcernTimedOut,
     wasResumed,
@@ -1193,6 +1197,7 @@ var PROTOCOL_VERSION_HEADER = "X-Aouda-Protocol-Version";
 var PROTOCOL_VERSION = "1";
 var CONTENT_TYPE_JSON2 = "application/json";
 var REQUEST_ID_HEADER2 = "X-Request-Id";
+var TOKEN_HEADER = "X-Aouda-Token";
 var ERROR_CODE_MAP = {
   TABLE_NOT_FOUND: AoudaNotFoundError,
   COLUMN_NOT_FOUND: AoudaNotFoundError,
@@ -1232,7 +1237,12 @@ var ERROR_CODE_MAP = {
   AUTH_IDENTITY_INVALID: AoudaValidationError,
   AUTH_IDENTITY_NOT_FOUND: AoudaValidationError,
   BULK_LOAD_TRANSFORM_INTENT_REQUIRED: AoudaValidationError,
-  BULK_LOAD_TRANSFORM_INTENT_CONFLICT: AoudaValidationError
+  BULK_LOAD_TRANSFORM_INTENT_CONFLICT: AoudaValidationError,
+  TOKEN_MALFORMED: AoudaValidationError,
+  TOKEN_FOREIGN_DATABASE: AoudaValidationError,
+  TOKEN_EPOCH_SUPERSEDED: AoudaConflictError,
+  TOKEN_UNSATISFIED: AoudaConflictError,
+  TOKEN_FETCH_PRIMARY: AoudaApiError
 };
 function createComposedAbortController(...signals) {
   const controller = new AbortController();
@@ -1269,7 +1279,7 @@ function createApiError(statusCode, statusText, body, retryAfterHeader) {
   const requestId = body.requestId;
   const retryAfterSeconds = parseRetryAfterSeconds(retryAfterHeader ?? null);
   const Ctor = ERROR_CODE_MAP[code] ?? AoudaApiError;
-  return new Ctor(message, code, statusCode, details, requestId, retryAfterSeconds);
+  return new Ctor(message, code, statusCode, details, requestId, retryAfterSeconds, body.token);
 }
 var HttpTransport = class {
   constructor(options) {
@@ -1281,6 +1291,29 @@ var HttpTransport = class {
       ...options.defaultHeaders
     };
     this.abortController = new AbortController();
+    this.database = options.database;
+    this.store = options.consistencyTokenStore;
+  }
+  presentTokenHeaders(path, headers) {
+    if (this.store == null || this.database == null || isAuthPath(path)) {
+      return;
+    }
+    const token = this.store.get(this.database);
+    if (token != null && token.length > 0) {
+      headers[TOKEN_HEADER] = token;
+    }
+  }
+  observeResponse(_path, response, bodyText, errorCode) {
+    if (this.store == null || this.database == null) {
+      return;
+    }
+    if (errorCode === "TOKEN_MALFORMED" || errorCode === "TOKEN_FOREIGN_DATABASE") {
+      return;
+    }
+    const header = response.headers.get(TOKEN_HEADER);
+    const bodyToken = readBodyToken(bodyText);
+    const token = header != null && header.trim().length > 0 ? header : bodyToken;
+    this.store.observe(this.database, token);
   }
   /**
    * Abort all in-flight and future requests (e.g. on client disconnect).
@@ -1318,6 +1351,7 @@ var HttpTransport = class {
       ...this.defaultHeaders,
       ...config.headers
     };
+    this.presentTokenHeaders(config.path, headers);
     if (config.body !== void 0 && config.body !== null) {
       headers["Content-Type"] = CONTENT_TYPE_JSON2;
     }
@@ -1337,6 +1371,7 @@ var HttpTransport = class {
         const text = await response.text();
         if (config.allowStatuses?.includes(response.status) && text) {
           try {
+            this.observeResponse(config.path, response, text);
             return JSON.parse(text);
           } catch {
           }
@@ -1350,15 +1385,19 @@ var HttpTransport = class {
         }
         if (response.status === 401) {
           const code = errorBody?.code ?? "AUTH_TOKEN_MISSING";
+          this.observeResponse(config.path, response, text, code);
           throw new AoudaAuthenticationError(
             errorBody?.error ?? "Unauthorized",
             code,
             401,
             errorBody?.details,
-            errorBody?.requestId
+            errorBody?.requestId,
+            void 0,
+            errorBody?.token
           );
         }
         if (errorBody?.code != null) {
+          this.observeResponse(config.path, response, text, errorBody.code);
           throw createApiError(
             response.status,
             response.statusText,
@@ -1366,6 +1405,7 @@ var HttpTransport = class {
             response.headers.get("Retry-After")
           );
         }
+        this.observeResponse(config.path, response, text);
         throw new AoudaResponseError(
           errorBody?.error ?? `${response.status} ${response.statusText}`,
           response.status,
@@ -1373,6 +1413,7 @@ var HttpTransport = class {
         );
       }
       const responseText = await response.text();
+      this.observeResponse(config.path, response, responseText);
       if (config.rawText) {
         return responseText;
       }
@@ -1433,6 +1474,7 @@ var HttpTransport = class {
       ...this.defaultHeaders,
       ...config.headers
     };
+    this.presentTokenHeaders(config.path, headers);
     if (config.rawBodyStr === void 0 && config.body !== void 0 && config.body !== null) {
       headers["Content-Type"] = CONTENT_TYPE_JSON2;
     }
@@ -1449,6 +1491,7 @@ var HttpTransport = class {
     try {
       const response = await localNetworkFetch(url, init);
       if (response.ok || config.allowStatuses?.includes(response.status)) {
+        this.observeResponse(config.path, response, void 0);
         return response;
       }
       const text = await response.text();
@@ -1461,15 +1504,19 @@ var HttpTransport = class {
       }
       if (response.status === 401) {
         const code = errorBody?.code ?? "AUTH_TOKEN_MISSING";
+        this.observeResponse(config.path, response, text, code);
         throw new AoudaAuthenticationError(
           errorBody?.error ?? "Unauthorized",
           code,
           401,
           errorBody?.details,
-          errorBody?.requestId
+          errorBody?.requestId,
+          void 0,
+          errorBody?.token
         );
       }
       if (errorBody?.code != null) {
+        this.observeResponse(config.path, response, text, errorBody.code);
         throw createApiError(
           response.status,
           response.statusText,
@@ -1477,6 +1524,7 @@ var HttpTransport = class {
           response.headers.get("Retry-After")
         );
       }
+      this.observeResponse(config.path, response, text);
       throw new AoudaResponseError(
         errorBody?.error ?? `${response.status} ${response.statusText}`,
         response.status,
@@ -1631,6 +1679,47 @@ var HttpTransport = class {
     });
   }
 };
+function isAuthPath(path) {
+  let p = path;
+  const q = p.indexOf("?");
+  if (q >= 0) {
+    p = p.slice(0, q);
+  }
+  if (/^https?:\/\//i.test(p)) {
+    try {
+      p = new URL(p).pathname;
+    } catch {
+    }
+  }
+  const lower = p.toLowerCase();
+  if (lower === "/api/auth" || lower.startsWith("/api/auth/")) {
+    return true;
+  }
+  const prefix = "/api/databases/";
+  if (!lower.startsWith(prefix)) {
+    return false;
+  }
+  const rest = lower.slice(prefix.length);
+  const slash = rest.indexOf("/");
+  if (slash < 0) {
+    return false;
+  }
+  const afterDb = rest.slice(slash + 1);
+  return afterDb === "auth" || afterDb.startsWith("auth/");
+}
+function readBodyToken(bodyText) {
+  if (bodyText == null || bodyText.trim().length === 0) {
+    return void 0;
+  }
+  try {
+    const parsed = JSON.parse(bodyText);
+    if (parsed !== null && typeof parsed === "object" && "token" in parsed && typeof parsed.token === "string") {
+      return parsed.token;
+    }
+  } catch {
+  }
+  return void 0;
+}
 
 // src/resilience/retry.ts
 var DEFAULT_MAX_RETRIES = 3;
@@ -2063,6 +2152,48 @@ function databasePath2(db) {
   return `/api/databases/${encodeURIComponent(db)}`;
 }
 
+// src/consistency-token-store.ts
+var MemoryConsistencyTokenStore = class {
+  constructor() {
+    this.tokens = /* @__PURE__ */ new Map();
+  }
+  get(database) {
+    if (typeof database !== "string" || database.trim().length === 0) {
+      throw new Error("database must be a non-empty string");
+    }
+    return this.tokens.get(normalizeKey(database));
+  }
+  observe(database, token) {
+    if (typeof database !== "string" || database.trim().length === 0) {
+      throw new Error("database must be a non-empty string");
+    }
+    if (token == null || token.trim().length === 0) {
+      return;
+    }
+    const key = normalizeKey(database);
+    const stored = this.tokens.get(key);
+    if (stored === void 0 || compareOrdinal(token, stored) > 0) {
+      this.tokens.set(key, token);
+    }
+  }
+};
+function compareOrdinal(left, right) {
+  if (left === right) return 0;
+  return left < right ? -1 : 1;
+}
+function maxToken(left, right) {
+  if (left == null || left.length === 0) {
+    return right == null || right.length === 0 ? void 0 : right;
+  }
+  if (right == null || right.length === 0) {
+    return left;
+  }
+  return compareOrdinal(left, right) >= 0 ? left : right;
+}
+function normalizeKey(database) {
+  return database.toLowerCase();
+}
+
 // src/streaming/subscription.ts
 var AsyncEventQueue = class {
   constructor() {
@@ -2119,7 +2250,7 @@ var AsyncEventQueue = class {
   }
 };
 var TableSubscription = class {
-  constructor(transport, identity, options = {}, onWarnings) {
+  constructor(transport, identity, options = {}, onWarnings, store, database) {
     this._queue = new AsyncEventQueue();
     this._active = true;
     this._started = false;
@@ -2135,6 +2266,11 @@ var TableSubscription = class {
     this._onError = options.onError;
     this._onWarnings = onWarnings;
     this._conflate = options.conflate;
+    this._atLeast = options.atLeast;
+    this._waitMs = options.waitMs;
+    this._onExceeded = options.onExceeded;
+    this._store = store;
+    this._database = database;
     this._reconnectHandlerKey = `${this.id}::reconnect`;
   }
   get lastVersion() {
@@ -2199,10 +2335,13 @@ var TableSubscription = class {
       id: this.id
     };
     if (this._identity.kind === "named") {
-      message.hash = this._identity.hash;
+      message.name = this._identity.name;
       if (this._identity.args !== void 0) {
         message.args = this._identity.args;
       }
+      if (this._identity.orderByIndex !== void 0) {
+        message.orderByIndex = this._identity.orderByIndex;
+      }
     } else {
       message.target = this._identity.target;
       if (this._identity.filter !== void 0) {
@@ -2215,8 +2354,30 @@ var TableSubscription = class {
     if (this._conflate !== void 0) {
       message.conflate = this._conflate;
     }
+    const pin = this._resolvePin();
+    if (pin !== void 0) {
+      message.at_least = pin;
+    }
+    if (this._waitMs !== void 0) {
+      message.wait_ms = this._waitMs;
+    }
+    if (this._onExceeded !== void 0) {
+      message.on_exceeded = this._onExceeded;
+    }
     await this._transport.send(message);
   }
+  _resolvePin() {
+    if (this._atLeast !== void 0 && this._store != null && this._database != null) {
+      this._store.observe(this._database, this._atLeast);
+    }
+    const stored = this._store != null && this._database != null ? this._store.get(this._database) : void 0;
+    return maxToken(this._atLeast, stored);
+  }
+  _observeToken(token) {
+    if (token !== void 0 && this._store != null && this._database != null) {
+      this._store.observe(this._database, token);
+    }
+  }
   _handleMessage(message) {
     if (!this._active) {
       return;
@@ -2243,6 +2404,7 @@ var TableSubscription = class {
   }
   _handleSnapshotPage(message) {
     this._pendingSnapshotRows.push(...message.rows);
+    this._observeToken(message.token);
   }
   _handleSnapshotComplete(message) {
     this._lastVersion = message.version;
@@ -2251,12 +2413,20 @@ var TableSubscription = class {
     }
     const rows = this._pendingSnapshotRows;
     this._pendingSnapshotRows = [];
-    this._onSnapshot?.(rows, message.version);
-    this._queue.push({
+    this._onSnapshot?.(rows, message.version, message.total_matches);
+    const snapshot = {
       type: "snapshot",
       rows,
       version: message.version
-    });
+    };
+    if (message.total_matches !== void 0) {
+      snapshot.totalMatches = message.total_matches;
+    }
+    if (message.token !== void 0) {
+      snapshot.token = message.token;
+      this._observeToken(message.token);
+    }
+    this._queue.push(snapshot);
   }
   async _handleGap(message) {
     this._pendingSnapshotRows = [];
@@ -2281,6 +2451,10 @@ var TableSubscription = class {
     if (message.values_skipped !== void 0) {
       event.values_skipped = message.values_skipped;
     }
+    if (message.token !== void 0) {
+      event.token = message.token;
+      this._observeToken(message.token);
+    }
     this._onChange?.(event);
     this._queue.push(event);
   }
@@ -2625,11 +2799,12 @@ var TableQuery = class _TableQuery {
    * @param state - Optional initial state (used for immutable chaining).
    * @internal Use `client.table()` to create queries.
    */
-  constructor(transport, tableName, database, state, getWebSocketTransport) {
+  constructor(transport, tableName, database, state, getWebSocketTransport, store) {
     this.transport = transport;
     this.tableName = tableName;
     this.database = database;
     this.getWebSocketTransport = getWebSocketTransport;
+    this.store = store;
     this.state = state ?? {
       predicates: [],
       groupClauses: [],
@@ -2645,6 +2820,16 @@ var TableQuery = class _TableQuery {
       isDistinct: false
     };
   }
+  withState(state) {
+    return new _TableQuery(
+      this.transport,
+      this.tableName,
+      this.database,
+      state,
+      this.getWebSocketTransport,
+      this.store
+    );
+  }
   where(column, operator, value) {
     const newPredicates = buildWherePredicates(column, operator, value);
     return new _TableQuery(
@@ -2655,7 +2840,8 @@ var TableQuery = class _TableQuery {
         ...this.state,
         predicates: [...this.state.predicates, ...newPredicates]
       },
-      this.getWebSocketTransport
+      this.getWebSocketTransport,
+      this.store
     );
   }
   /**
@@ -2674,7 +2860,7 @@ var TableQuery = class _TableQuery {
     return new _TableQuery(this.transport, this.tableName, this.database, {
       ...this.state,
       groupClauses: [...this.state.groupClauses, sub]
-    }, this.getWebSocketTransport);
+    }, this.getWebSocketTransport, this.store);
   }
   /**
    * Sets the primary sort column for the query.
@@ -2699,7 +2885,7 @@ var TableQuery = class _TableQuery {
     return new _TableQuery(this.transport, this.tableName, this.database, {
       ...this.state,
       orderByClauses: [orderByClause]
-    }, this.getWebSocketTransport);
+    }, this.getWebSocketTransport, this.store);
   }
   /**
    * Sets the primary sort column to descending order.
@@ -2745,7 +2931,7 @@ var TableQuery = class _TableQuery {
     return new _TableQuery(this.transport, this.tableName, this.database, {
       ...this.state,
       orderByClauses: [...this.state.orderByClauses, orderByClause]
-    }, this.getWebSocketTransport);
+    }, this.getWebSocketTransport, this.store);
   }
   /**
    * Sets the maximum number of rows to return.
@@ -2762,7 +2948,7 @@ var TableQuery = class _TableQuery {
     return new _TableQuery(this.transport, this.tableName, this.database, {
       ...this.state,
       limitValue: count
-    }, this.getWebSocketTransport);
+    }, this.getWebSocketTransport, this.store);
   }
   /**
    * Sets the number of rows to skip.
@@ -2779,7 +2965,7 @@ var TableQuery = class _TableQuery {
     return new _TableQuery(this.transport, this.tableName, this.database, {
       ...this.state,
       offsetValue: count
-    }, this.getWebSocketTransport);
+    }, this.getWebSocketTransport, this.store);
   }
   /**
    * Requests cross-partition access for this query.
@@ -2794,10 +2980,21 @@ var TableQuery = class _TableQuery {
     return new _TableQuery(this.transport, this.tableName, this.database, {
       ...this.state,
       crossPartitionAccess: true
-    }, this.getWebSocketTransport);
+    }, this.getWebSocketTransport, this.store);
+  }
+  /**
+   * Pin this query at at least this C-1 token. Observes the token into the
+   * client store (I3, sticky) and presents it on execute via `X-Aouda-Token`.
+   */
+  atLeast(token) {
+    if (typeof token !== "string" || token.trim().length === 0) {
+      throw new Error("atLeast() requires a non-empty token");
+    }
+    this.store?.observe(this.database, token);
+    return this.withState({ ...this.state, atLeast: token });
   }
   /**
-   * Restricts the columns returned in the result.
+   * Selects specific columns to return.
    * If not called, all columns are returned.
    *
    * When T is a specific row type, only keys of T are accepted as column names.
@@ -2819,7 +3016,7 @@ var TableQuery = class _TableQuery {
     return new _TableQuery(this.transport, this.tableName, this.database, {
       ...this.state,
       selectColumns: columns.length > 0 ? columns : null
-    }, this.getWebSocketTransport);
+    }, this.getWebSocketTransport, this.store);
   }
   /**
    * Return only distinct (de-duplicated) rows for the given columns — SQL `SELECT DISTINCT`.
@@ -2849,7 +3046,7 @@ var TableQuery = class _TableQuery {
       ...this.state,
       selectColumns: columns,
       isDistinct: true
-    }, this.getWebSocketTransport);
+    }, this.getWebSocketTransport, this.store);
   }
   /**
    * Adds server-side computed columns to the query result.
@@ -2878,7 +3075,7 @@ var TableQuery = class _TableQuery {
     return new _TableQuery(this.transport, this.tableName, this.database, {
       ...this.state,
       selectExprs: projections
-    }, this.getWebSocketTransport);
+    }, this.getWebSocketTransport, this.store);
   }
   join(rightTable, leftColumnOrColumns, rightColumnOrColumns) {
     return this.addJoinClause(
@@ -2936,7 +3133,8 @@ var TableQuery = class _TableQuery {
           }
         ]
       },
-      this.getWebSocketTransport
+      this.getWebSocketTransport,
+      this.store
     );
   }
   /**
@@ -2972,7 +3170,8 @@ var TableQuery = class _TableQuery {
         ...this.state,
         groupByColumns: [...columns]
       },
-      this.getWebSocketTransport
+      this.getWebSocketTransport,
+      this.store
     );
   }
   /**
@@ -3006,8 +3205,11 @@ var TableQuery = class _TableQuery {
       onSnapshot: options.onSnapshot,
       onChange: options.onChange,
       onError: options.onError,
-      conflate: options.conflate
-    });
+      conflate: options.conflate,
+      atLeast: options.atLeast ?? this.state.atLeast,
+      waitMs: options.waitMs,
+      onExceeded: options.onExceeded
+    }, void 0, this.store, this.database);
     subscription.start();
     return subscription;
   }
@@ -3122,7 +3324,8 @@ var TableQuery = class _TableQuery {
         ...this.state,
         joinClauses: [...this.state.joinClauses, joinClause]
       },
-      this.getWebSocketTransport
+      this.getWebSocketTransport,
+      this.store
     );
   }
   addAggregate(op, column) {
@@ -3143,7 +3346,8 @@ var TableQuery = class _TableQuery {
           }
         ]
       },
-      this.getWebSocketTransport
+      this.getWebSocketTransport,
+      this.store
     );
   }
   requireWebSocketTransport() {
@@ -3173,17 +3377,23 @@ var TableQuery = class _TableQuery {
    * ```
    */
   async execute() {
+    if (this.state.atLeast) {
+      this.store?.observe(this.database, this.state.atLeast);
+    }
     const request = this.buildRequest();
     const path = `${databasePath2(this.database)}/query`;
     const response = await this.transport.post(path, request);
     const rows = columnarToRows(response);
     const stats = response.stats;
-    return { rows, stats };
+    return { rows, stats, token: response.token };
   }
   /**
    * Executes the query and returns the raw columnar JSON payload (no row-object conversion).
    */
   async toColumnar() {
+    if (this.state.atLeast) {
+      this.store?.observe(this.database, this.state.atLeast);
+    }
     const request = this.buildRequest();
     const path = `${databasePath2(this.database)}/query`;
     return this.transport.post(path, request);
@@ -3213,8 +3423,12 @@ var TableQuery = class _TableQuery {
         limitValue: 0,
         selectColumns: []
       },
-      this.getWebSocketTransport
+      this.getWebSocketTransport,
+      this.store
     );
+    if (this.state.atLeast) {
+      this.store?.observe(this.database, this.state.atLeast);
+    }
     const request = countQuery.buildRequest();
     const path = `${databasePath2(this.database)}/query`;
     const response = await this.transport.post(path, request);
@@ -3261,7 +3475,8 @@ var TableQuery = class _TableQuery {
     const response = await this.transport.post(path, body);
     const result = {
       rowsInserted: response.rowsInserted,
-      executionMs: response.executionMs
+      executionMs: response.executionMs,
+      token: response.token
     };
     if (response.generatedValues !== void 0) {
       result.generatedValues = response.generatedValues;
@@ -3311,7 +3526,8 @@ var TableQuery = class _TableQuery {
     const response = await this.transport.post(path, body);
     const result = {
       rowsInserted: response.rowsInserted,
-      executionMs: response.executionMs
+      executionMs: response.executionMs,
+      token: response.token
     };
     if (response.generatedValues !== void 0) {
       result.generatedValues = response.generatedValues;
@@ -3363,6 +3579,7 @@ var TableQuery = class _TableQuery {
     return {
       rowsAffected: response.rowsUpdated,
       executionMs: response.executionMs,
+      token: response.token,
       ...response.rows ? { rows: columnarToRows(response.rows) } : {},
       ...response.rowsTruncated ? { rowsTruncated: true } : {}
     };
@@ -3413,6 +3630,7 @@ var TableQuery = class _TableQuery {
       rowsAffected: response.rowsDeleted,
       executionMs: response.executionMs,
       hasMore: response.hasMore,
+      token: response.token,
       ...response.rows ? { rows: columnarToRows(response.rows) } : {},
       ...response.rowsTruncated ? { rowsTruncated: true } : {}
     };
@@ -3432,7 +3650,8 @@ var TableQuery = class _TableQuery {
     return {
       rowsAffected: response.rowsDeleted,
       executionMs: response.executionMs,
-      hasMore: false
+      hasMore: false,
+      token: response.token
     };
   }
   /**
@@ -3445,7 +3664,14 @@ var TableQuery = class _TableQuery {
       throw new Error("batch() requires a non-empty operations array");
     }
     const wireOperations = operations.map((op, index) => {
-      const base = new _TableQuery(this.transport, this.tableName, this.database);
+      const base = new _TableQuery(
+        this.transport,
+        this.tableName,
+        this.database,
+        void 0,
+        this.getWebSocketTransport,
+        this.store
+      );
       const scoped = op.where(base);
       const where = scoped.buildWhereClause();
       if (!where) {
@@ -4813,12 +5039,12 @@ function raiseDeprecationWarnings(sink, warnings) {
       continue;
     }
     const sunset = warning.sunsetAt != null ? ` sunsetAt=${warning.sunsetAt}` : "";
-    const hash = warning.hash != null && warning.hash.length > 0 ? ` hash=${warning.hash}` : "";
+    const name = warning.name != null && warning.name.length > 0 ? ` name=${warning.name}` : "";
     sink({
       code: warning.code,
-      hash: warning.hash,
+      name: warning.name,
       sunsetAt: warning.sunsetAt,
-      message: `${warning.code}:${hash}${sunset}`.trim()
+      message: `${warning.code}:${name}${sunset}`.trim()
     });
   }
 }
@@ -4831,21 +5057,31 @@ function emptyStats() {
   };
 }
 var NamedQueriesApi = class {
-  constructor(transport, database, onWarning, getStreamingTransport) {
+  constructor(transport, database, onWarning, getStreamingTransport, store) {
     this.transport = transport;
     this.database = database;
     this.onWarning = onWarning;
     this.getStreamingTransport = getStreamingTransport;
+    this.store = store;
   }
-  async execute(hash, args, options) {
-    if (typeof hash !== "string" || hash.trim().length === 0) {
-      throw new Error("Named query hash must be a non-empty string");
+  async execute(name, args, options) {
+    if (typeof name !== "string" || name.trim().length === 0) {
+      throw new Error("Named query name must be a non-empty string");
     }
     const prefix = databasePath2(this.database);
-    const path = `${prefix}/named-queries/${encodeURIComponent(hash)}/query?format=columnar`;
+    const path = `${prefix}/named-queries/${encodeURIComponent(name)}/query?format=columnar`;
+    const body = {
+      args: args ?? {}
+    };
+    if (options?.orderByIndex !== void 0) {
+      body.orderByIndex = options.orderByIndex;
+    }
+    if (options?.atLeast !== void 0) {
+      this.store?.observe(this.database, options.atLeast);
+    }
     const response = await this.transport.post(
       path,
-      { args: args ?? {} },
+      body,
       { signal: options?.signal }
     );
     const rows = columnarToRows(response);
@@ -4853,7 +5089,9 @@ var NamedQueriesApi = class {
     return {
       rows,
       stats: response.stats,
-      warnings: response.warnings
+      warnings: response.warnings,
+      totalMatches: response.totalMatches,
+      token: response.token
     };
   }
   async batch(items, options) {
@@ -4871,6 +5109,9 @@ var NamedQueriesApi = class {
         400
       );
     }
+    if (options?.atLeast !== void 0) {
+      this.store?.observe(this.database, options.atLeast);
+    }
     const prefix = databasePath2(this.database);
     const path = `${prefix}/named-queries/batch?format=columnar`;
     const envelope = await this.transport.post(
@@ -4892,33 +5133,42 @@ var NamedQueriesApi = class {
         data: slot.data ?? [],
         rowCount: slot.rowCount ?? 0,
         stats: slot.stats ?? emptyStats(),
-        warnings: slot.warnings
+        warnings: slot.warnings,
+        totalMatches: slot.totalMatches,
+        token: slot.token
       };
       const result = {
         rows: columnarToRows(columnar),
         stats: columnar.stats,
-        warnings: slot.warnings
+        warnings: slot.warnings,
+        totalMatches: slot.totalMatches,
+        token: slot.token
       };
       raiseDeprecationWarnings(this.onWarning, slot.warnings);
       return { isError: false, result };
     });
   }
-  subscribe(hash, args, options = {}) {
-    if (typeof hash !== "string" || hash.trim().length === 0) {
-      throw new Error("Named query hash must be a non-empty string");
+  subscribe(name, args, options = {}) {
+    if (typeof name !== "string" || name.trim().length === 0) {
+      throw new Error("Named query name must be a non-empty string");
     }
     const subscription = new TableSubscription(
       this.getStreamingTransport(),
-      { kind: "named", hash, args },
+      { kind: "named", name, args, orderByIndex: options.orderByIndex },
       {
         onSnapshot: options.onSnapshot,
         onChange: options.onChange,
         onError: options.onError,
-        conflate: options.conflate
+        conflate: options.conflate,
+        atLeast: options.atLeast,
+        waitMs: options.waitMs,
+        onExceeded: options.onExceeded
       },
       (warnings) => {
         raiseDeprecationWarnings(this.onWarning, warnings);
-      }
+      },
+      this.store,
+      this.database
     );
     subscription.start();
     return subscription;
@@ -4930,12 +5180,12 @@ var NamedMutationsApi = class {
     this.database = database;
     this.onWarning = onWarning;
   }
-  async execute(hash, args) {
-    if (typeof hash !== "string" || hash.trim().length === 0) {
-      throw new Error("Named mutation hash must be a non-empty string");
+  async execute(name, args) {
+    if (typeof name !== "string" || name.trim().length === 0) {
+      throw new Error("Named mutation name must be a non-empty string");
     }
     const prefix = databasePath2(this.database);
-    const path = `${prefix}/named-mutations/${encodeURIComponent(hash)}/execute`;
+    const path = `${prefix}/named-mutations/${encodeURIComponent(name)}/execute`;
     const wire = await this.transport.post(path, {
       args: args ?? {}
     });
@@ -4996,6 +5246,7 @@ var WebSocketTransport = class {
     // Serialized-send queue: each send appends to this tail.
     this._sendTail = Promise.resolve();
     this._lastVersion = 0;
+    this._lastToken = null;
     this._reconnectAttempt = 0;
     this._disposed = false;
     this._missedPings = 0;
@@ -5013,6 +5264,7 @@ var WebSocketTransport = class {
     this._pingIntervalMs = options.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS;
     this._maxMissedHeartbeats = options.maxMissedHeartbeats ?? DEFAULT_MAX_MISSED_HEARTBEATS;
     this._enableCompression = options.enableCompression ?? true;
+    this._store = options.consistencyTokenStore;
     this._wireMode = options.wireMode ?? "json";
     this._authHandler?.setOnAccessTokenRefreshed((token) => {
       if (this._handshakeComplete && this._ws?.readyState === WS_READY_STATE_OPEN) {
@@ -5021,10 +5273,14 @@ var WebSocketTransport = class {
     });
   }
   // ─── Public API ────────────────────────────────────────────────────────────
-  /** Latest version number from the most recent server `heartbeat` message. */
+  /** Latest change-event sequence from the most recent server `heartbeat` message. */
   get lastVersion() {
     return this._lastVersion;
   }
+  /** Consistency token from the most recent server `heartbeat` (ADR 0042 D-13). */
+  get lastToken() {
+    return this._lastToken;
+  }
   /**
    * Registers a handler for incoming server messages with the given channel id.
    * Use `"__global__"` to receive broadcast messages that carry no `id`.
@@ -5212,6 +5468,10 @@ var WebSocketTransport = class {
       }
       case "heartbeat":
         this._lastVersion = msg.version;
+        this._lastToken = msg.token ?? null;
+        if (this._lastToken != null && this._lastToken.length > 0) {
+          this._store?.observe(this._database, this._lastToken);
+        }
         break;
       case "pong":
         this._missedPings = 0;
@@ -5377,16 +5637,21 @@ var LongPollTransport = class {
     this._connected = false;
     this._pollTask = null;
     this._lastVersion = 0;
+    this._lastToken = null;
     this._serverUrl = serverUrl;
     this._database = database;
     this._authHandler = options.authHandler;
     this._onReconnected = options.onReconnected;
     this._waitMs = Math.max(1, options.waitMs ?? DEFAULT_WAIT_MS);
     this._fetch = options.fetchImpl ?? localNetworkFetch;
+    this._store = options.consistencyTokenStore;
   }
   get lastVersion() {
     return this._lastVersion;
   }
+  get lastToken() {
+    return this._lastToken;
+  }
   registerHandler(id, handler) {
     this._handlers.set(id, handler);
   }
@@ -5509,6 +5774,10 @@ var LongPollTransport = class {
     for (const msg of payload.messages) {
       if (msg.type === "heartbeat") {
         this._lastVersion = msg.version;
+        this._lastToken = msg.token ?? null;
+        if (this._lastToken != null && this._lastToken.length > 0) {
+          this._store?.observe(this._database, this._lastToken);
+        }
       }
       const id = "id" in msg ? msg.id : void 0;
       if (id !== void 0 && id !== null) {
@@ -5588,6 +5857,9 @@ var FallbackStreamingTransport = class {
   get lastVersion() {
     return this._active.lastVersion;
   }
+  get lastToken() {
+    return this._active.lastToken;
+  }
   registerHandler(id, handler) {
     this._handlers.set(id, handler);
     this._active.registerHandler(id, handler);
@@ -5667,6 +5939,7 @@ var AoudaClient = class {
     this.baseUrl = normalizeBaseUrl(options.serverUrl);
     this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
     this.database = options.database.trim();
+    this._store = options.consistencyTokenStore ?? new MemoryConsistencyTokenStore();
     if (!Number.isFinite(this.timeout) || this.timeout <= 0) {
       throw new Error("timeout must be a finite positive number");
     }
@@ -5701,7 +5974,9 @@ var AoudaClient = class {
     }
     const httpTransport = new HttpTransport({
       baseUrl: this.baseUrl,
-      timeout: this.timeout
+      timeout: this.timeout,
+      database: this.database,
+      consistencyTokenStore: this._store
     });
     const activeAuth = options.serverAuth ?? options.appAuth;
     if (activeAuth) {
@@ -5761,7 +6036,8 @@ var AoudaClient = class {
       this.transport,
       this.database,
       onNamedArtifactWarning,
-      () => this._getOrCreateWebSocketTransport()
+      () => this._getOrCreateWebSocketTransport(),
+      this._store
     );
     this._namedMutations = new NamedMutationsApi(
       this.transport,
@@ -5860,7 +6136,8 @@ var AoudaClient = class {
       name,
       this.database,
       void 0,
-      () => this._getOrCreateWebSocketTransport()
+      () => this._getOrCreateWebSocketTransport(),
+      this._store
     );
   }
   /**
@@ -5912,13 +6189,26 @@ var AoudaClient = class {
     return this._materializedQueries;
   }
   /**
-   * Hash-only named-query execute and batch. Names are codegen aliases (D-5).
+   * Named-query execute, read-only batch, and subscribe by unique schema name.
    */
   get namedQueries() {
     return this._namedQueries;
   }
+  observeConsistencyToken(token) {
+    this._store.observe(this.database, token);
+  }
+  getObservedConsistencyToken() {
+    return this._store.get(this.database);
+  }
+  async getConsistencyToken() {
+    const body = await this.transport.get(
+      `/api/databases/${encodeURIComponent(this.database)}/token`
+    );
+    this._store.observe(this.database, body.token);
+    return this._store.get(this.database) ?? body.token;
+  }
   /**
-   * Hash-only named-mutation execute. No batch.
+   * Named-mutation execute by unique schema name. No batch.
    */
   get namedMutations() {
     return this._namedMutations;
@@ -6045,13 +6335,15 @@ var AoudaClient = class {
       const primary = new WebSocketTransport(this.baseUrl, this.database, {
         authHandler: this._authHandler,
         enableCompression: this._streamingEnableCompression,
-        wireMode: this._streamingWireMode
+        wireMode: this._streamingWireMode,
+        consistencyTokenStore: this._store
       });
       if (this._streamingEnableLongPollFallback) {
         this._wsTransport = new FallbackStreamingTransport(primary, () => {
           return new LongPollTransport(this.baseUrl, this.database, {
             authHandler: this._authHandler,
-            waitMs: this._streamingLongPollWaitMs
+            waitMs: this._streamingLongPollWaitMs,
+            consistencyTokenStore: this._store
           });
         });
       } else {
@@ -6349,6 +6641,7 @@ var version = package_default.version;
   MaterializedQueriesApi,
   MaterializedQueryState,
   MaterializedQueryType,
+  MemoryConsistencyTokenStore,
   MetricsAdminApi,
   NamedMutationsApi,
   NamedQueriesApi,
@@ -6364,10 +6657,12 @@ var version = package_default.version;
   applyLocalNetworkAccess,
   coerceColumnarValue,
   columnarToRows,
+  compareOrdinal,
   createAoudaClient,
   createAoudaClusterMcpToolSet,
   installLocalNetworkFetch,
   localNetworkFetch,
+  maxToken,
   resolveTargetAddressSpace,
   version
 });