@abloatai/humans 0.37.0

package/dist/local/mutators/undoApply.js

@@ -0,0 +1,117 @@
+/**
+ * Conflict-aware replay of undo and redo operations, so undo reverts only your
+ * own changes.
+ *
+ * The undo stack is already per-client: only your local mutator calls record
+ * onto it through `UndoScope.record`, and a collaborator's edits arrive as
+ * inbound sync deltas that never enter it. This module adds the other half of
+ * per-user undo. When replaying a recorded operation, it touches a field only
+ * if that field's current value still equals the value this operation
+ * established. Undo therefore reverts your change where it still stands and
+ * leaves alone any field a collaborator has since overwritten — selective undo
+ * applied to a field-level, last-writer-wins model.
+ *
+ * {@link resolveOps} does the filtering. It takes the operations about to be
+ * replayed (`apply` — the inverses on undo, the forwards on redo) and their
+ * counterparts (`paired`), which carry the value each operation established: on
+ * undo the forwards say what you set, and on redo the inverses say what undo
+ * restored. For `update` and `updateMany` operations it drops any field whose
+ * live value no longer matches that established value. The `create` and
+ * `delete` families are structural and always applied — undoing a create
+ * removes the row you added, and undoing a delete restores it.
+ *
+ * When no collaborator is involved, the live value always equals what you set,
+ * so nothing is dropped and single-user undo behaves exactly as before.
+ */
+import { deepEqual } from '@abloatai/transaction/utils/json';
+export const DEFAULT_UNDO_CONFLICT_POLICY = 'skip-stale';
+/**
+ * Structural equality for JSON-shaped values — scalars, arrays, and plain
+ * objects — ignoring object key order. Re-exported from the package's shared
+ * JSON helper so the undo path and your own code can share one implementation.
+ */
+export { deepEqual };
+/**
+ * Map `id → { field: establishedValue }` from the paired ops. Only update-family
+ * ops carry per-field values worth comparing.
+ */
+function buildEstablished(paired) {
+    const map = new Map();
+    for (const op of paired) {
+        if (op.kind === 'update') {
+            map.set(op.patch.id, op.patch);
+        }
+        else if (op.kind === 'updateMany') {
+            for (const p of op.patches)
+                map.set(p.id, p);
+        }
+    }
+    return map;
+}
+/** Read the live value of a field from the store's pool, or `undefined`. */
+function readCurrentField(store, id, field) {
+    const model = store.pool.get(id);
+    if (!model)
+        return undefined;
+    const json = model.toJSON?.();
+    return json ? json[field] : undefined;
+}
+/**
+ * Keep only the fields whose live value still equals what this op established
+ * (`established[field]`). Returns `null` if nothing survives (the whole op is a
+ * no-op — every field was superseded by a collaborator).
+ */
+function filterStalePatch(store, patch, established) {
+    const out = { id: patch.id };
+    let kept = 0;
+    for (const field of Object.keys(patch)) {
+        if (field === 'id')
+            continue;
+        if (established && field in established) {
+            // Apply only if the field still holds the value we established, meaning no
+            // collaborator has overwritten it since. Otherwise skip it, so the
+            // collaborator's change is left intact.
+            if (deepEqual(readCurrentField(store, patch.id, field), established[field])) {
+                out[field] = patch[field];
+                kept++;
+            }
+        }
+        else {
+            // No paired value to compare against. The recorder always pairs fields,
+            // so this is theoretical; apply to preserve undo functionality.
+            out[field] = patch[field];
+            kept++;
+        }
+    }
+    return kept > 0 ? out : null;
+}
+/**
+ * Filter the ops to apply so they don't clobber concurrent collaborator edits.
+ * See the module docblock. `last-writer-wins` returns the ops unchanged.
+ */
+export function resolveOps(apply, paired, store, policy) {
+    if (policy === 'last-writer-wins')
+        return apply;
+    const established = buildEstablished(paired);
+    const out = [];
+    for (const op of apply) {
+        if (op.kind === 'update') {
+            const filtered = filterStalePatch(store, op.patch, established.get(op.patch.id));
+            if (filtered)
+                out.push({ kind: 'update', modelKey: op.modelKey, patch: filtered });
+        }
+        else if (op.kind === 'updateMany') {
+            const patches = op.patches
+                .map((p) => filterStalePatch(store, p, established.get(p.id)))
+                .filter((p) => p !== null);
+            if (patches.length > 0) {
+                out.push({ kind: 'updateMany', modelKey: op.modelKey, patches });
+            }
+        }
+        else {
+            // create / createMany / delete / deleteMany — structural, applied as-is.
+            out.push(op);
+        }
+    }
+    return out;
+}

package/dist/local/persistence.d.ts

@@ -0,0 +1,7 @@
+export type AbloPersistence = 'memory' | 'indexeddb';
+export interface PersistenceOptions {
+    readonly persistence?: AbloPersistence;
+    readonly inMemory?: boolean;
+    readonly offline?: boolean;
+}
+export declare function shouldUseInMemoryPersistence(options: PersistenceOptions): boolean;

package/dist/local/persistence.js

@@ -0,0 +1,9 @@
+export function shouldUseInMemoryPersistence(options) {
+    if (typeof window === 'undefined')
+        return true;
+    if (options.persistence)
+        return options.persistence === 'memory';
+    if (typeof options.inMemory === 'boolean')
+        return options.inMemory;
+    return options.offline !== true;
+}

package/dist/local/query/QueryProcessor.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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;
+}
+export declare class QueryProcessor {
+    private cache;
+    private enableCache;
+    private predicateResultCache;
+    constructor(config?: {
+        enableCache?: boolean;
+    });
+    /**
+     * Process query with filtering, sorting, and pagination
+     */
+    processQuery<T extends Model>(models: T[], modelName: string, options?: QueryOptions<T>): QueryResult<T>;
+    /**
+     * Sort models by field
+     */
+    private sortModels;
+    /**
+     * Find first matching model with predicate
+     */
+    findFirst<T extends Model>(models: Generator<T, void, unknown>, predicate: (model: T) => boolean): T | undefined;
+    /**
+     * Count models with optional predicate
+     */
+    countModels<T extends Model>(models: Generator<T, void, unknown>, predicate?: (model: T) => boolean): number;
+    /**
+     * 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;
+    /**
+     * Invalidate cache by pattern
+     */
+    invalidateCache(pattern?: string): void;
+    /**
+     * Clear all cache
+     */
+    clearCache(): void;
+    /**
+     * Get cache stats for debugging
+     */
+    getCacheStats(): {
+        size: number;
+        enabled: boolean;
+    };
+}

package/dist/local/query/QueryProcessor.js

@@ -0,0 +1,255 @@
+/**
+ * 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.
+ */
+/**
+ * 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 {
+    cache = new Map();
+    // Reverse index: model type -> set of cache keys for that type
+    modelTypeIndex = new Map();
+    get(key) {
+        return this.cache.get(key);
+    }
+    get size() {
+        return this.cache.size;
+    }
+    set(key, data) {
+        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) {
+        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 = [];
+        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() {
+        this.cache.clear();
+        this.modelTypeIndex.clear();
+    }
+    /**
+     * Extract model type from cache key
+     * Cache key format: "operation:ModelType:options"
+     */
+    extractModelType(key) {
+        // A missing second segment reads as undefined, so `?? null` yields null.
+        return key.split(':')[1] ?? null;
+    }
+}
+export class QueryProcessor {
+    cache;
+    enableCache;
+    // 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.
+    predicateResultCache = new Map();
+    constructor(config = {}) {
+        this.enableCache = config.enableCache ?? true;
+        this.cache = new BasicQueryCache();
+    }
+    /**
+     * Process query with filtering, sorting, and pagination
+     */
+    processQuery(models, modelName, options = {}) {
+        // 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(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 = {
+            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, 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
+     */
+    sortModels(models, field, order = 'asc') {
+        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(models, predicate) {
+        for (const model of models) {
+            if (predicate(model)) {
+                return model;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Count models with optional predicate
+     */
+    countModels(models, predicate) {
+        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.
+     */
+    generateCacheKey(operation, modelName, options) {
+        const serializableOptions = {};
+        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) {
+        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() {
+        this.cache.clear();
+        this.predicateResultCache.clear();
+    }
+    /**
+     * Get cache stats for debugging
+     */
+    getCacheStats() {
+        return {
+            size: this.cache.size,
+            enabled: this.enableCache,
+        };
+    }
+}

package/dist/local/query/client.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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 type { QueryBatch, QueryBatchResult } from './types.js';
+import { type RecoveryClass } from '@abloatai/transaction/errorCodes';
+import { type AuthTokenGetter } from '@abloatai/transaction/auth/credentialSource';
+import type { RuntimeContext } from '../RuntimeContext.js';
+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 declare function postQuery(options: PostQueryOptions, batch: QueryBatch): Promise<QueryBatchResult>;

package/dist/local/query/client.js

@@ -0,0 +1,138 @@
+/**
+ * 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 { translateHttpError } from '@abloatai/transaction/errors';
+import { classifyRecovery } from '@abloatai/transaction/errorCodes';
+import { withAuthHeaders } from '@abloatai/transaction/auth/credentialSource';
+import { globalRuntime } from '../context.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) => {
+    if (val === null)
+        return [];
+    return val;
+});
+const QueryBatchResultSchema = z
+    .object({
+    results: z.array(QueryResultSchema),
+})
+    .loose();
+/**
+ * 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, batch) {
+    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 = 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 = 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 = 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);
+        }
+    }
+}