@abloatai/humans 0.37.0

package/src/local/query/QueryProcessor.ts

@@ -0,0 +1,347 @@
+/**
+ * Runs in-memory queries over a set of models — filtering by predicate,
+ * sorting, paginating, and caching the results. A caller hands
+ * {@link QueryProcessor} the candidate models and the query options, and it
+ * returns a {@link QueryResult}. It keeps two caches: a string-keyed cache for
+ * plain queries, and a structural-identity cache for predicate queries, whose
+ * closures cannot be turned into a stable string key.
+ */
+
+import type { Model } from '../Model.js';
+import type { ModelScope } from '../InstanceCache.js';
+
+export interface QueryOptions<T extends Model> {
+  predicate?: (model: T) => boolean;
+  /** Stable key to distinguish different predicates for the same model type.
+   *  Required when multiple predicate queries exist for the same model — without this,
+   *  they share a cache key and thrash each other's cached result every render. */
+  predicateKey?: string;
+  scope?: ModelScope;
+  orderBy?: keyof T;
+  order?: 'asc' | 'desc';
+  limit?: number;
+  offset?: number;
+  skipCache?: boolean;
+}
+
+export interface QueryResult<T extends Model> {
+  data: T[];
+  total: number;
+  hasMore: boolean;
+  fromCache?: boolean;
+}
+
+/**
+ * Simple cache interface for query results
+ */
+interface QueryCache {
+  get<T>(key: string): T | undefined;
+  set(key: string, data: unknown): void;
+  invalidate(pattern?: string): void;
+  clear(): void;
+  /** Number of entries currently cached. */
+  readonly size: number;
+}
+
+/**
+ * The default in-memory cache. It keeps a reverse index from model type to the
+ * cache keys for that type, so invalidating one model type costs work
+ * proportional to that type's keys rather than a scan of the whole cache. A
+ * regex fallback still covers the rare pattern that is not a plain model-type
+ * match.
+ */
+class BasicQueryCache implements QueryCache {
+  private cache = new Map<string, unknown>();
+  // Reverse index: model type -> set of cache keys for that type
+  private modelTypeIndex = new Map<string, Set<string>>();
+
+  get<T>(key: string): T | undefined {
+    return this.cache.get(key) as T | undefined;
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+
+  set(key: string, data: unknown): void {
+    this.cache.set(key, data);
+
+    // Extract model type from cache key (format: "operation:ModelType:options")
+    const modelType = this.extractModelType(key);
+    if (modelType) {
+      if (!this.modelTypeIndex.has(modelType)) {
+        this.modelTypeIndex.set(modelType, new Set());
+      }
+      this.modelTypeIndex.get(modelType)!.add(key);
+    }
+  }
+
+  /**
+   * Optimized invalidation - O(k) where k = keys for model type
+   * Supports both exact model type names and regex patterns (fallback)
+   */
+  invalidate(pattern?: string): void {
+    if (!pattern) {
+      this.cache.clear();
+      this.modelTypeIndex.clear();
+      return;
+    }
+
+    // Fast path: Check if pattern is a simple model type match like ".*ModelType.*"
+    const modelType = /^\.\*(\w+)\.\*$/.exec(pattern)?.[1];
+    if (modelType !== undefined) {
+      const keysToDelete = this.modelTypeIndex.get(modelType);
+      if (keysToDelete) {
+        for (const key of keysToDelete) {
+          this.cache.delete(key);
+        }
+        this.modelTypeIndex.delete(modelType);
+      }
+      return;
+    }
+
+    // Slow path fallback: regex matching for complex patterns
+    // This should rarely be needed with proper model type patterns
+    const regex = new RegExp(pattern);
+    const keysToDelete: string[] = [];
+
+    for (const key of this.cache.keys()) {
+      if (regex.test(key)) {
+        keysToDelete.push(key);
+      }
+    }
+
+    // Batch delete to avoid iterator invalidation
+    for (const key of keysToDelete) {
+      this.cache.delete(key);
+      // Clean up index
+      const modelType = this.extractModelType(key);
+      if (modelType) {
+        this.modelTypeIndex.get(modelType)?.delete(key);
+      }
+    }
+  }
+
+  clear(): void {
+    this.cache.clear();
+    this.modelTypeIndex.clear();
+  }
+
+  /**
+   * Extract model type from cache key
+   * Cache key format: "operation:ModelType:options"
+   */
+  private extractModelType(key: string): string | null {
+    // A missing second segment reads as undefined, so `?? null` yields null.
+    return key.split(':')[1] ?? null;
+  }
+}
+
+export class QueryProcessor {
+  private cache: QueryCache;
+  private enableCache: boolean;
+
+  // Stable-reference cache for predicate queries. A string cache key cannot
+  // capture a closure, so predicate queries use a separate identity-based
+  // cache keyed on the deterministic part of the query (model name plus
+  // serializable options). Each entry stores the previous result and a
+  // fingerprint of its model ids; when the ids are unchanged, the processor
+  // returns the previous array reference so observers do not re-render.
+  private predicateResultCache = new Map<string, { ids: string; result: QueryResult<Model> }>();
+
+  constructor(config: { enableCache?: boolean } = {}) {
+    this.enableCache = config.enableCache ?? true;
+    this.cache = new BasicQueryCache();
+  }
+
+  /**
+   * Process query with filtering, sorting, and pagination
+   */
+  processQuery<T extends Model>(
+    models: T[],
+    modelName: string,
+    options: QueryOptions<T> = {}
+  ): QueryResult<T> {
+    // Generate cache key
+    const cacheKey = this.generateCacheKey('query', modelName, options);
+
+    // Check string-based cache (non-predicate queries only)
+    if (!options.predicate && !options.skipCache && this.enableCache) {
+      const cached = this.cache.get<QueryResult<T>>(cacheKey);
+      if (cached) {
+        return { ...cached, fromCache: true };
+      }
+    }
+
+    // Apply predicate filter
+    let filtered = options.predicate ? models.filter(options.predicate) : models;
+
+    // Sort models
+    if (options.orderBy) {
+      filtered = this.sortModels(filtered, options.orderBy, options.order);
+    }
+
+    const total = filtered.length;
+
+    // Apply pagination
+    const offset = options.offset || 0;
+    const limit = options.limit || filtered.length;
+    const data = filtered.slice(offset, offset + limit);
+
+    const result: QueryResult<T> = {
+      data,
+      total,
+      hasMore: offset + limit < total,
+      fromCache: false,
+    };
+
+    // For predicate queries: compare by structural identity. Return the
+    // previous array reference when the model ids are unchanged, so observers
+    // don't re-render on a structurally identical result.
+    if (options.predicate && this.enableCache) {
+      const ids = data.map((m) => m.id).join(',');
+      const cached = this.predicateResultCache.get(cacheKey);
+
+      if (cached && cached.ids === ids) {
+        // Structural match — return previous reference for stability
+        return { ...(cached.result as QueryResult<T>), fromCache: true };
+      }
+
+      // New result — store for future comparison
+      this.predicateResultCache.set(cacheKey, { ids, result });
+    }
+
+    // For non-predicate queries: use the string-based cache.
+    if (!options.predicate && this.enableCache) {
+      this.cache.set(cacheKey, result);
+    }
+
+    return result;
+  }
+
+  /**
+   * Sort models by field
+   */
+  private sortModels<T extends Model>(
+    models: T[],
+    field: keyof T,
+    order: 'asc' | 'desc' = 'asc'
+  ): T[] {
+    return [...models].sort((a, b) => {
+      const aVal = a[field];
+      const bVal = b[field];
+
+      if (aVal === bVal) return 0;
+      if (aVal === null || aVal === undefined) return 1;
+      if (bVal === null || bVal === undefined) return -1;
+
+      const comparison = aVal < bVal ? -1 : 1;
+      return order === 'asc' ? comparison : -comparison;
+    });
+  }
+
+  /**
+   * Find first matching model with predicate
+   */
+  findFirst<T extends Model>(
+    models: Generator<T, void, unknown>,
+    predicate: (model: T) => boolean
+  ): T | undefined {
+    for (const model of models) {
+      if (predicate(model)) {
+        return model;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Count models with optional predicate
+   */
+  countModels<T extends Model>(
+    models: Generator<T, void, unknown>,
+    predicate?: (model: T) => boolean
+  ): number {
+    let count = 0;
+
+    for (const model of models) {
+      if (!predicate || predicate(model)) {
+        count++;
+      }
+    }
+
+    return count;
+  }
+
+  /**
+   * Generate a deterministic cache key from query parameters.
+   * Functions (predicates) are excluded from the key — predicate queries use
+   * the structural identity cache (predicateResultCache) instead of the
+   * string-based cache.
+   */
+  private generateCacheKey<T extends Model>(
+    operation: string,
+    modelName: string,
+    options: QueryOptions<T>
+  ): string {
+    const serializableOptions: Record<string, unknown> = {};
+    let hasPredicate = false;
+
+    for (const [key, value] of Object.entries(options)) {
+      if (typeof value === 'function') {
+        hasPredicate = true;
+        // Mark that this query has a predicate, but use a stable marker
+        // (not Math.random). The actual caching for predicate queries
+        // is handled by predicateResultCache using ID comparison.
+        serializableOptions[key] = `__predicate__`;
+      } else {
+        serializableOptions[key] = value;
+      }
+    }
+
+    const sortedOptions = JSON.stringify(
+      serializableOptions,
+      Object.keys(serializableOptions).sort()
+    );
+    const key = `${operation}:${modelName}:${sortedOptions}`;
+    return hasPredicate ? `pred:${key}` : key;
+  }
+
+  /**
+   * Invalidate cache by pattern
+   */
+  invalidateCache(pattern?: string): void {
+    this.cache.invalidate(pattern);
+    // Also invalidate predicate result cache for this model type
+    if (pattern) {
+      const modelType = /^\.\*(\w+)\.\*$/.exec(pattern)?.[1];
+      if (modelType !== undefined) {
+        for (const key of this.predicateResultCache.keys()) {
+          if (key.includes(modelType)) {
+            this.predicateResultCache.delete(key);
+          }
+        }
+      }
+    } else {
+      this.predicateResultCache.clear();
+    }
+  }
+
+  /**
+   * Clear all cache
+   */
+  clearCache(): void {
+    this.cache.clear();
+    this.predicateResultCache.clear();
+  }
+
+  /**
+   * Get cache stats for debugging
+   */
+  getCacheStats(): { size: number; enabled: boolean } {
+    return {
+      size: this.cache.size,
+      enabled: this.enableCache,
+    };
+  }
+}

package/src/local/query/client.ts

@@ -0,0 +1,197 @@
+/**
+ * The HTTP client for the sync query endpoint.
+ *
+ * {@link postQuery} is a small wrapper over `fetch` that POSTs a
+ * {@link QueryBatch} as JSON to `/sync/query`, attaches the bearer credential
+ * as an `Authorization` header, and parses the response into a typed
+ * {@link QueryBatchResult}. An HTTP failure is not thrown: it is logged, and
+ * every query in the batch comes back with an empty result, so a
+ * fire-and-forget caller cannot crash on an unhandled rejection.
+ *
+ * Higher-level query helpers build on this to issue structured queries without
+ * repeating the fetch and error-handling boilerplate.
+ */
+
+import { z } from 'zod';
+import type { QueryBatch, QueryBatchResult } from './types.js';
+import { translateHttpError } from '@abloatai/transaction/errors';
+import { classifyRecovery, type RecoveryClass } from '@abloatai/transaction/errorCodes';
+import { withAuthHeaders, type AuthTokenGetter } from '@abloatai/transaction/auth/credentialSource';
+import { globalRuntime } from '../context.js';
+import type { RuntimeContext } from '../RuntimeContext.js';
+
+// ── Response validation ─────────────────────────────────────────────────
+//
+// Each result slot is an array of rows, or an object for a bundled response.
+// A per-query failure on the server surfaces here as an empty array rather
+// than an error, so emptiness alone does not distinguish "no rows" from
+// "the query failed." Parsing through Zod normalizes a `null` slot into an
+// empty array, so callers never receive a raw null.
+const QueryResultSchema = z
+  .union([z.array(z.unknown()), z.record(z.string(), z.unknown()), z.null()])
+  .transform((val): unknown[] | Record<string, unknown> => {
+    if (val === null) return [];
+    return val;
+  });
+
+const QueryBatchResultSchema = z
+  .object({
+    results: z.array(QueryResultSchema),
+  })
+  .loose();
+
+export interface PostQueryOptions {
+  /**
+   * Full base URL of the sync server including the `/api` prefix.
+   * The query endpoint is appended as `/sync/query`, so the final
+   * request hits `${baseUrl}/sync/query`.
+   */
+  baseUrl: string;
+
+  /** Timeout in ms for the fetch request. Default: 30000. */
+  fetchTimeout?: number;
+
+  /** The owning client's runtime. Defaults to the module-global bridge. */
+  runtime?: RuntimeContext;
+
+  /**
+   * Live bearer credential getter. Preferred over `capabilityToken` because it
+   * is read per request, so token refreshes propagate without reconstructing
+   * query helpers.
+   */
+  getAuthToken?: AuthTokenGetter;
+
+  /**
+   * A fixed credential string, for callers that hold only a copied token.
+   * Prefer `getAuthToken`, which is re-read on each request so a refresh takes
+   * effect without rebuilding the client.
+   */
+  capabilityToken?: string;
+
+  /**
+   * An optional hook that tries to recover from a rejected credential. When a
+   * query comes back with a 401, its {@link RecoveryClass} is passed here: a
+   * return of `'retry'` means a fresh credential has been obtained and the
+   * request is replayed exactly once, while `'stop'` ends the attempt. Because
+   * the replay happens at most once, a wedged credential cannot cause a retry
+   * loop. When this hook is absent, a 401 is logged and returns empty results
+   * like any other failure.
+   */
+  recoverCredential?: (recovery: RecoveryClass) => Promise<'retry' | 'stop'>;
+}
+
+/**
+ * Sends a batch of queries to `/sync/query` and returns the parsed
+ * {@link QueryBatchResult}. An HTTP failure is not thrown: it is logged, and
+ * every query in the batch comes back with an empty result, which keeps a
+ * fire-and-forget caller from crashing on an unhandled rejection. A 401 may
+ * first be handed to {@link PostQueryOptions.recoverCredential} for a single
+ * retry.
+ *
+ * The response preserves order: `results[i]` corresponds to the query at
+ * `queries[i]`, so callers can rely on index alignment to pull typed results
+ * out of a multi-query batch.
+ */
+export async function postQuery(
+  options: PostQueryOptions,
+  batch: QueryBatch,
+): Promise<QueryBatchResult> {
+  const url = `${options.baseUrl}/sync/query`;
+  const timeout = options.fetchTimeout ?? 30_000;
+  const runtime = options.runtime ?? globalRuntime;
+
+  // At most two attempts: the original request, plus one replay after a
+  // successful credential recovery (see `recoverCredential`). A second auth
+  // rejection falls through to the log-and-empty path, so a wedged credential
+  // can never retry-loop.
+  for (let attempt = 0; ; attempt++) {
+    // Race the fetch against a timeout so hung requests don't block
+    // the calling helper indefinitely. Fresh controller per attempt.
+    const controller = new AbortController();
+    const timer = setTimeout(() => { controller.abort(); }, timeout);
+
+    try {
+      // Recomputed per attempt: `withAuthHeaders` reads the live credential
+      // source, so a replay after recovery carries the freshly-minted key.
+      const headers = withAuthHeaders(
+        options.getAuthToken,
+        { 'Content-Type': 'application/json' },
+        options.capabilityToken,
+      );
+      const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(batch),
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        // Build the typed AbloError for this HTTP failure (the same
+        // code-to-class map the throwing paths use) so the log carries a
+        // registry `code` — for example an authentication error with
+        // `session_expired` on a 401 — rather than a bare status. This path
+        // deliberately does not throw, since a fire-and-forget caller could
+        // crash on an unhandled rejection. It returns empty slots while still
+        // logging a legible Ablo error.
+        let body: unknown = null;
+        try {
+          body = await response.clone().json();
+        } catch {
+          // non-JSON error page — translateHttpError falls back to status text
+        }
+        const err = translateHttpError(response.status, body);
+
+        // On a 401, hand the failure to the recovery hook once. The recovery
+        // class routes the outcome: an expired access credential is re-minted
+        // and the request replays; a lost session is terminal and stops here;
+        // anything else stops. A bare 401 with no readable code is treated as
+        // an expired access credential, so the only terminal path is the
+        // re-mint itself coming back empty, never an ambiguous status.
+        if (attempt === 0 && response.status === 401 && options.recoverCredential) {
+          const recovery: RecoveryClass =
+            typeof err.code === 'string'
+              ? classifyRecovery(err.code)
+              : 'access_credential_expiry';
+          const outcome = await options.recoverCredential(recovery);
+          if (outcome === 'retry') {
+            runtime.logger.debug('[postQuery] credential recovered — replaying query once', {
+              code: err.code ?? response.status,
+            });
+            continue;
+          }
+        }
+
+        // Logged through the level-gated logger, so it honors ABLO_LOG_LEVEL:
+        // a `warn` line the app developer can read (the models, the typed
+        // message, and a wire `code`), with the forensic detail on a companion
+        // `debug` line. The read stays empty until the underlying cause, such
+        // as auth or network, is resolved.
+        const models = batch.queries.map((q) => q.model).join(', ');
+        runtime.logger.warn(
+          `Could not load ${models} — ${err.message} (code: ${err.code ?? response.status}). No results were returned.`,
+        );
+        runtime.logger.debug('[postQuery.error] query http failure', {
+          type: err.type,
+          code: err.code ?? response.status,
+          models,
+          message: err.message,
+        });
+        return { results: batch.queries.map(() => []) };
+      }
+
+      const raw: unknown = await response.json();
+      const parsed = QueryBatchResultSchema.safeParse(raw);
+      if (!parsed.success) {
+        // A malformed server response isn't something the consumer can act on
+        // (server/protocol issue) → debug, gated like everything else.
+        runtime.logger.debug('[postQuery.error] malformed response', {
+          issues: parsed.error.issues,
+        });
+        return { results: batch.queries.map(() => []) };
+      }
+      return parsed.data;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}

package/src/local/query/types.ts

@@ -0,0 +1,102 @@
+/**
+ * Structured query types for the `/sync/query` endpoint.
+ *
+ * A query describes a filtered read in a compact wire format. `where` is a flat
+ * list of `[column, operator, value]` conditions combined with AND, and
+ * `related` names the schema relations to fetch alongside each row. The server
+ * compiles a query against your schema: it reads the model's relation metadata
+ * to turn `related: ['blocks']` into the right join, and turns each condition
+ * into a WHERE fragment. The protocol carries no model-specific logic, so
+ * adding a model or relation is a schema change rather than a server change.
+ *
+ * The `IN` operator lets you batch a read by any column, including a foreign
+ * key — for example, fetching every block whose `sectionId` falls in a set of
+ * ids.
+ */
+
+// The where grammar describes the *request*, not any local copy of the rows it
+// returns, so it lives in the settlement core (ADR 0016). Re-exported here so
+// the existing `query/types` import path keeps resolving.
+export type {
+  WherePrimitive,
+  WhereOp,
+  WhereClause,
+  LoadWhere,
+} from '@abloatai/transaction/resources/where';
+import type { WhereClause } from '@abloatai/transaction/resources/where';
+
+/** A single structured fetch request. */
+export interface Query {
+  /**
+   * Client-facing model name (e.g. "File", "Block", "Message").
+   * The server's adapter maps this to the actual database table.
+   */
+  model: string;
+
+  /**
+   * The conditions to filter by, combined with AND. Empty or omitted returns
+   * every row the caller may see; reads are still scoped to the caller's
+   * organization on the server. Use `['col', 'IN', values]` to batch a read by
+   * any column.
+   */
+  where?: readonly WhereClause[];
+
+  /**
+   * The relations to fetch with each row, named as they are declared on this
+   * model in the schema. The server resolves each name from the schema's
+   * relation metadata and joins the related rows in. They come back nested
+   * under the relation key:
+   *
+   *   { __typename: 'Section', id: '…', blocks: [{ __typename: 'Block', … }] }
+   */
+  related?: readonly string[];
+
+  /**
+   * Row limit. Applied after where + JOIN, before related nesting.
+   * Omit for no limit.
+   */
+  limit?: number;
+
+  /**
+   * Column to order by. For stable pagination. Omit for unordered.
+   */
+  orderBy?: string;
+
+  /** Order direction. Defaults to `'asc'`. */
+  order?: 'asc' | 'desc';
+}
+
+/** Request body for POST /sync/query. */
+export interface QueryBatch {
+  /**
+   * Batch of queries to execute in one round trip. Results are
+   * returned in request order at the same indices. Keep batches
+   * small — the server caps at 16 queries per batch by default.
+   */
+  queries: Query[];
+}
+
+/** Response body from POST /sync/query. */
+export interface QueryBatchResult {
+  /**
+   * The result of each query, in request order: `results[i]` corresponds to
+   * `queries[i]`. Each element is an array of rows, or an object bundling
+   * several named row collections when the source returns more than one. Every
+   * row carries a `__typename` field naming its model, so callers can dispatch
+   * on it, along with any requested `related` rows nested under their relation
+   * key.
+   *
+   * A query that fails on the server comes back as an empty array, which is
+   * indistinguishable from a query that simply matched nothing — treat an empty
+   * result as "no rows", not as proof the query succeeded. The element type is
+   * `unknown` because one batch can mix row shapes, so narrow each result
+   * before use.
+   */
+  results: unknown[];
+  /**
+   * The server watermark observed after the batch ran. Model reads expose this
+   * as `stamp`, and callers thread it into `commits.create({ readAt })` so the
+   * server can reject a write built on stale data.
+   */
+  lastSyncId?: number;
+}

package/src/local/schema/serialize.ts

@@ -0,0 +1 @@
+export * from '@abloatai/transaction/schema/serialize';