feat(entities): log console.error when realtime broadcast is oversize (#167)

* feat(entities): auto-refetch when realtime broadcast is truncated

Server-side BASE-40236 slims oversize entity broadcasts to fit under the
Redis pubsub cap, signaling the slim with `_truncated: true` on the event
data. Customer apps that render the truncated fields would otherwise
display placeholder text until refresh.

The SDK now detects `_truncated` in `entities.X.subscribe` and transparently
refetches the full record over HTTP before invoking the user callback, so
deployed customer code keeps working without changes. Concurrent subscribers
in the same browser fan out to a single HTTP call via an in-flight
debounce keyed by `${entityName}:${id}:${timestamp}`. On refetch failure
the SDK falls through with the partial payload and logs a warning, so the
failure mode is no worse than today's drop-and-stale.

Delete events skip refetch — the record no longer exists.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* refactor(entities): rename _truncated → _oversize for stub flag

The wire flag is set only when the server falls back to a stub payload
because the original record was too big for realtime transport. Calling
it "truncated" was misleading — we don't truncate fields in that path,
we replace the whole payload with `{id, _oversize: true}`. `_oversize`
names the actual cause and tells the SDK why a refetch is needed.

Coordinated with the matching backend rename.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* refactor(entities): replace auto-refetch with console.error on _oversize

Per PM pushback, drop the HTTP auto-refetch path on oversize broadcasts —
even with debouncing, an entity that tens of subscribers all refetch on
every broadcast (e.g. a popular Truck record updated every 30 s in a
fleet app) shifts realtime load to HTTP at potentially uncapped fan-out.

New behavior: when `_oversize: true` is seen, log a single console.error
naming the entity, id, and the recommended `entities.X.get(id)` call so
the developer is notified at debug time. The user callback still fires
with the slimmed payload (big string fields are empty, rest of the
record may be the stub) — caller decides what to do.

Removed the inflightRefetches debounce map and refetchTruncated helper
since they're no longer needed.

Tests collapse from 5 refetch scenarios to 3 logging scenarios:
- logs and passes the stub through when _oversize is true
- does NOT log on delete events even if _oversize is set
- does NOT log when _oversize is absent

156/156 pass; lint + build clean.

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: theunreal

src/modules/entities.ts

@@ -197,6 +197,22 @@ function createEntityHandler<T = any>(
             return;
           }
 
+          // Server signals oversize broadcasts with `_oversize: true` on
+          // `data`. The wire payload was slimmed to fit under the realtime
+          // transport cap, so big string fields arrive as empty strings (or
+          // the whole record collapses to a stub). Surface this to the
+          // developer console so they know to fetch the full record on
+          // demand (e.g. a follow-up entities.X.get(id) call) instead of
+          // rendering the slimmed payload directly. Skip on delete events
+          // — the record no longer exists.
+          if (event.type !== "delete" && (event.data as any)?._oversize) {
+            console.error(
+              `[Base44 SDK] Realtime broadcast for ${entityName}#${event.id} was oversize and got slimmed for transport. ` +
+                `Fields >10 KB are empty and the rest of the record may be a stub. ` +
+                `Call \`entities.${entityName}.get("${event.id}")\` to fetch the full record.`
+            );
+          }
+
           try {
             callback(event);
           } catch (error) {

tests/unit/entities-subscribe.test.ts

@@ -207,6 +207,116 @@ describe("Entities Module - subscribe()", () => {
     warnSpy.mockRestore();
   });
 
+  describe("oversize broadcast handling", () => {
+    test("logs a console.error and passes the stub through when data._oversize is true", () => {
+      const mockSocket = createMockSocket();
+      const mockAxios = createMockAxios();
+      const entities = createEntitiesModule({
+        axios: mockAxios as any,
+        appId,
+        getSocket: () => mockSocket as any,
+      });
+
+      const callback = vi.fn();
+      const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+      entities.Todo.subscribe(callback);
+
+      mockSocket._simulateMessage(`entities:${appId}:Todo`, {
+        room: `entities:${appId}:Todo`,
+        data: JSON.stringify({
+          type: "update",
+          data: { id: "123", _oversize: true },
+          id: "123",
+          timestamp: "2024-01-01T00:00:00.000Z",
+        }),
+      });
+
+      // No HTTP call — the SDK never auto-refetches.
+      expect(mockAxios.get).not.toHaveBeenCalled();
+      // Developer is notified via console.error.
+      expect(errorSpy).toHaveBeenCalledWith(
+        expect.stringContaining("[Base44 SDK] Realtime broadcast for Todo#123 was oversize")
+      );
+      // Callback still fires with the slimmed payload — caller decides what to do.
+      expect(callback).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: "update",
+          id: "123",
+          data: { id: "123", _oversize: true },
+        })
+      );
+
+      errorSpy.mockRestore();
+    });
+
+    test("does NOT log on delete events even if _oversize is set", () => {
+      const mockSocket = createMockSocket();
+      const mockAxios = createMockAxios();
+      const entities = createEntitiesModule({
+        axios: mockAxios as any,
+        appId,
+        getSocket: () => mockSocket as any,
+      });
+
+      const callback = vi.fn();
+      const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+      entities.Todo.subscribe(callback);
+
+      mockSocket._simulateMessage(`entities:${appId}:Todo`, {
+        room: `entities:${appId}:Todo`,
+        data: JSON.stringify({
+          type: "delete",
+          data: { id: "123", _oversize: true },
+          id: "123",
+          timestamp: "2024-01-01T00:00:00.000Z",
+        }),
+      });
+
+      expect(errorSpy).not.toHaveBeenCalled();
+      expect(callback).toHaveBeenCalledWith(
+        expect.objectContaining({ type: "delete", id: "123" })
+      );
+
+      errorSpy.mockRestore();
+    });
+
+    test("does NOT log when data has no _oversize flag", () => {
+      const mockSocket = createMockSocket();
+      const mockAxios = createMockAxios();
+      const entities = createEntitiesModule({
+        axios: mockAxios as any,
+        appId,
+        getSocket: () => mockSocket as any,
+      });
+
+      const callback = vi.fn();
+      const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+      entities.Todo.subscribe(callback);
+
+      mockSocket._simulateMessage(`entities:${appId}:Todo`, {
+        room: `entities:${appId}:Todo`,
+        data: JSON.stringify({
+          type: "update",
+          data: { id: "123", title: "Normal Todo" },
+          id: "123",
+          timestamp: "2024-01-01T00:00:00.000Z",
+        }),
+      });
+
+      expect(errorSpy).not.toHaveBeenCalled();
+      expect(callback).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: { id: "123", title: "Normal Todo" },
+        })
+      );
+
+      errorSpy.mockRestore();
+    });
+  });
+
   test("subscribe() should catch and log errors thrown by callback", () => {
     const mockSocket = createMockSocket();
     const mockAxios = createMockAxios();