@abloatai/ablo 0.34.1 → 0.36.0

package/dist/sync/OnDemandLoader.d.ts

@@ -24,9 +24,10 @@ import type { InstanceCache } from '../InstanceCache.js';
 import type { Database } from '../Database.js';
 import type { Model } from '../Model.js';
 import type { ModelRegistry } from '../ModelRegistry.js';
-import type { RecoveryClass } from '../errorCodes.js';
+import type { RuntimeContext } from '../RuntimeContext.js';
+import type { RecoveryClass } from '../transaction/errorCodes.js';
 import type { LoadWhere, WhereClause } from '../query/types.js';
-import type { Schema } from '../schema/schema.js';
+import type { Schema } from '../transaction/schema/schema.js';
 export interface OnDemandLoaderOptions {
     readonly objectPool: InstanceCache;
     readonly database: Database;
@@ -41,6 +42,8 @@ export interface OnDemandLoaderOptions {
     readonly getAuthToken?: () => string | null;
     /** @deprecated Use `getAuthToken`. */
     readonly getCapabilityToken?: () => string | null;
+    /** The owning client's runtime. Defaults to the module-global bridge. */
+    readonly runtime?: RuntimeContext;
 }
 export interface FetchOptions<T> {
     /**

package/dist/sync/OnDemandLoader.js

@@ -21,8 +21,32 @@
  * is ready.
  */
 import { ModelScope } from '../InstanceCache.js';
-import { AbloValidationError } from '../errors.js';
+import { AbloValidationError } from '../transaction/errors.js';
 import { postQuery } from '../query/client.js';
+function timestampMs(value) {
+    if (value instanceof Date) {
+        const timestamp = value.getTime();
+        return Number.isFinite(timestamp) ? timestamp : undefined;
+    }
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value !== 'string')
+        return undefined;
+    const parsed = Date.parse(value);
+    return Number.isNaN(parsed) ? undefined : parsed;
+}
+/**
+ * A query response is a snapshot, not an ordered delta. It may have started
+ * before a local optimistic write and completed after it. Only treat the row
+ * as authoritative over an existing model when its server timestamp is newer;
+ * missing timestamps retain the legacy merge behavior for custom sources that
+ * do not expose `updatedAt`.
+ */
+function snapshotDoesNotAdvanceModel(data, model) {
+    const incoming = timestampMs(data.updatedAt);
+    const resident = timestampMs(model.updatedAt);
+    return incoming !== undefined && resident !== undefined && incoming <= resident;
+}
 export class OnDemandLoader {
     opts;
     inFlight = new Map();
@@ -323,19 +347,27 @@ export class OnDemandLoader {
         if (typeof obj.id !== 'string')
             return null;
         if (this.opts.objectPool.has(obj.id)) {
-            // Pool already has this entity, but the row coming from the
-            // network is the freshest server-confirmed state. Apply the new
-            // fields onto the existing instance instead of returning the
-            // stale model verbatim — otherwise a `load()` that re-fetches
-            // after a missed delta (WS dropped, tab slept, redeploy) silently
-            // discards the fresh state and the consumer keeps seeing the
-            // birth-time snapshot forever. `updateFromData` is the same
-            // primitive `InstanceCache.upsert()` uses for delta application,
-            // so the behaviour matches "delta-applied" semantics exactly.
+            // Keep the existing instance alive when a query refreshes it. A query
+            // can carry fresher server state after a missed delta, but unlike the
+            // ordered delta stream it can also finish late with an older snapshot;
+            // the reconciliation below distinguishes those cases before applying.
             const existing = this.opts.objectPool.get(obj.id);
             if (existing) {
                 const stamped = this.stampTypename(obj, typename);
-                existing.updateFromData(stamped);
+                // Network queries are unordered snapshots. A request that began before
+                // an optimistic resize can return afterward with the old row; applying
+                // it here would visibly snap the live model back, and the matching
+                // authoritative delta cannot repair it because own echoes are
+                // intentionally suppressed. Keep a newer resident row intact.
+                if (snapshotDoesNotAdvanceModel(stamped, existing))
+                    return existing;
+                // If the source has no comparable timestamp, retain pending local
+                // fields while accepting unrelated server fields. This is the same
+                // local-first merge contract used by SyncClient's delta resolver.
+                const localChanges = existing.getChanges();
+                existing.updateFromData(Object.keys(localChanges).length > 0
+                    ? { ...stamped, ...localChanges, updatedAt: existing.updatedAt }
+                    : stamped);
                 return existing;
             }
             return null;
@@ -347,7 +379,7 @@ export class OnDemandLoader {
         // "InstanceCache.createFromData: No model identifier found" warning,
         // failing to hydrate the entity from cache (network path then has to
         // re-populate it). The typename comes from the schema relation
-        // (`'SlideLayer'`, `'SlideLayoutLayer'`, etc.) so no guessing involved.
+        // (`'Block'`, `'Section'`, etc.) so no guessing involved.
         const stamped = this.stampTypename(obj, typename);
         return this.opts.objectPool.createFromData(stamped, undefined, opts);
     }
@@ -367,8 +399,15 @@ export class OnDemandLoader {
         const obj = item;
         if (obj.__typename === typename)
             return obj;
-        const { _Typename: _drop, ...rest } = obj;
-        void _drop;
+        // Drop the driver-mangled `_Typename` AND any row-carried `__typename`
+        // that disagrees with the schema's: these rows were returned FOR this
+        // model's query, so the schema typename is correct by construction — and
+        // without stripping it, the spread would put the row's variant (a server
+        // echoing the schema KEY `tasks` instead of the typename `Task`) back on
+        // top of the stamp, sending hydration to the strict unknown-model error.
+        const { _Typename: _dropMangled, __typename: _dropRowVariant, ...rest } = obj;
+        void _dropMangled;
+        void _dropRowVariant;
         return { __typename: typename, ...rest };
     }
     async queryNetwork(modelName, clauses, options) {
@@ -393,6 +432,7 @@ export class OnDemandLoader {
             baseUrl: this.opts.baseUrl,
             getAuthToken: this.authTokenProvider ?? undefined,
             recoverCredential: this.credentialRecovery ?? undefined,
+            runtime: this.opts.runtime,
         }, { queries: [query] });
         const rows = Array.isArray(result.results[0]) ? result.results[0] : [];
         // Normalize: wire rows lack `__typename` when the server elides it.
@@ -403,7 +443,7 @@ export class OnDemandLoader {
             return row;
         });
         // Expand: server returns related entities nested under each row
-        // (`row.layers = [{...}, ...]`). Walk the nested shape, stamp the
+        // (`row.blocks = [{...}, ...]`). Walk the nested shape, stamp the
         // typename from the schema's relation metadata (the server bakes
         // `__typename` into the JSONB but the postgres.camel driver
         // mangles it to `_Typename` mid-flight, so client-side stamping
@@ -475,8 +515,8 @@ export class OnDemandLoader {
     }
     resolveTypename(modelName) {
         // Schema is the source of truth for wire typenames. The model proxy
-        // is keyed by camelCase plural (`slideLayers`) but the wire query +
-        // InstanceCache typeIndex use the typename (`SlideLayer`).
+        // is keyed by camelCase plural (`blocks`) but the wire query +
+        // InstanceCache typeIndex use the typename (`Block`).
         const def = this.opts.schema
             .models?.[modelName];
         return def?.typename ?? modelName;
@@ -512,8 +552,8 @@ function stableKey(modelName, clauses, orderBy, limit, expand) {
         const kb = JSON.stringify(b);
         return ka < kb ? -1 : ka > kb ? 1 : 0;
     });
-    // Expand is part of the query identity: `slides where deck=d1` and the same
-    // with `expand:['layers']` hydrate different data, so they must not share a
+    // Expand is part of the query identity: `sections where report=r1` and the same
+    // with `expand:['blocks']` hydrate different data, so they must not share a
     // ledger/dedup key. Sorted so relation order doesn't fork the key.
     const expandKey = expand && expand.length > 0 ? [...expand].sort() : undefined;
     return JSON.stringify({ modelName, where: sorted, orderBy, limit, expand: expandKey });
@@ -693,10 +733,10 @@ function likeRegex(pattern, insensitive) {
     return new RegExp(`^${body}$`, insensitive ? 'i' : '');
 }
 /**
- * Schema fields are camelCase (`slideId`); the wire query expects
+ * Schema fields are camelCase (`sectionId`); the wire query expects
  * the server-side column name. The query server's input resolver
  * casing-folds, but we send snake_case to match the convention used
- * by the existing loaders' postQuery calls (`'slide_id'` etc.).
+ * by the existing loaders' postQuery calls (`'section_id'` etc.).
  */
 function columnize(field) {
     return field.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);

package/dist/sync/SubscriptionManager.d.ts

@@ -73,7 +73,7 @@ export interface SubscriptionManagerOptions {
 }
 export declare class SubscriptionManager {
     private readonly transport;
-    private readonly baseGroups;
+    private baseGroups;
     private readonly warmTtlMs;
     private readonly maxWarm;
     private readonly now;
@@ -88,8 +88,19 @@ export declare class SubscriptionManager {
     /** Coalescing state so concurrent mutations collapse into one in-flight call. */
     private inFlight;
     private dirty;
-    private readonly cancelSweep;
+    /** Arms the sweep timer; `null` when sweeping is disabled. The timer is
+     *  armed lazily, on the first warm entry — sweeping exists only to expire
+     *  warm groups, so a manager that never warms one holds no timer (and a
+     *  client that is constructed but never navigates holds none either). */
+    private readonly armSweep;
+    private cancelSweep;
     constructor(options: SubscriptionManagerOptions);
+    /**
+     * Seeds the permanent scopes once the host resolves identity. The manager
+     * can exist from client construction — before the connection's read scope
+     * is known — so the base set is seeded rather than fixed at construction.
+     */
+    setBaseGroups(groups: readonly string[]): void;
     /**
      * Move a group into the warm set with a fresh TTL, maintaining LRU order
      * and the `maxWarm` cap. JS `Map` preserves insertion order, so deleting

package/dist/sync/SubscriptionManager.js

@@ -49,7 +49,12 @@ export class SubscriptionManager {
     /** Coalescing state so concurrent mutations collapse into one in-flight call. */
     inFlight = null;
     dirty = false;
-    cancelSweep;
+    /** Arms the sweep timer; `null` when sweeping is disabled. The timer is
+     *  armed lazily, on the first warm entry — sweeping exists only to expire
+     *  warm groups, so a manager that never warms one holds no timer (and a
+     *  client that is constructed but never navigates holds none either). */
+    armSweep;
+    cancelSweep = null;
     constructor(options) {
         this.transport = options.transport;
         this.baseGroups = new Set(options.baseGroups ?? []);
@@ -63,14 +68,24 @@ export class SubscriptionManager {
                     const handle = setInterval(fn, ms);
                     return () => { clearInterval(handle); };
                 });
-            this.cancelSweep = schedule(() => {
-                void this.sweep();
-            }, sweepInterval);
+            this.armSweep = () => {
+                this.cancelSweep = schedule(() => {
+                    void this.sweep();
+                }, sweepInterval);
+            };
         }
         else {
-            this.cancelSweep = null;
+            this.armSweep = null;
         }
     }
+    /**
+     * Seeds the permanent scopes once the host resolves identity. The manager
+     * can exist from client construction — before the connection's read scope
+     * is known — so the base set is seeded rather than fixed at construction.
+     */
+    setBaseGroups(groups) {
+        this.baseGroups = new Set(groups);
+    }
     /**
      * Move a group into the warm set with a fresh TTL, maintaining LRU order
      * and the `maxWarm` cap. JS `Map` preserves insertion order, so deleting
@@ -79,6 +94,8 @@ export class SubscriptionManager {
      * warm — callers guard before calling this.
      */
     warmGroup(group) {
+        if (this.armSweep && !this.cancelSweep)
+            this.armSweep();
         this.warm.delete(group);
         this.warm.set(group, this.now() + this.warmTtlMs);
         while (this.warm.size > this.maxWarm) {
@@ -172,6 +189,7 @@ export class SubscriptionManager {
     /** Stop the sweep timer. The connection is unaffected. */
     dispose() {
         this.cancelSweep?.();
+        this.cancelSweep = null;
     }
     /**
      * Push the desired set to the transport iff it differs from the last