tina4-nodejs 3.13.130 → 3.13.132

package/packages/orm/dist/index.js

@@ -262,6 +262,99 @@ var init_databaseResult = __esm({
   }
 });
 
+// src/modelCollection.ts
+var ModelCollection;
+var init_modelCollection = __esm({
+  "src/modelCollection.ts"() {
+    "use strict";
+    ModelCollection = class extends Array {
+      /** Total rows matching the query's filter (ignores limit/offset). */
+      _total = 0;
+      /** The SQL limit that produced this page. */
+      _limit = 0;
+      /** The SQL offset that produced this page. */
+      _offset = 0;
+      /**
+       * Derived array operations (`map`, `filter`, `slice`, spread, …) build a plain
+       * `Array`, never another `ModelCollection`. This is what defuses the Array-
+       * subclass constructor/species trap: the engine never calls this constructor
+       * with a length during those operations.
+       */
+      static get [Symbol.species]() {
+        return Array;
+      }
+      /**
+       * @param items  the page of hydrated model instances (or the length, when the
+       *               engine constructs a derived array — defended against here).
+       * @param total  total rows matching the query's filter (ignores limit/offset).
+       * @param limit  the SQL limit that produced this page.
+       * @param offset the SQL offset that produced this page.
+       */
+      constructor(items, total = 0, limit = 0, offset = 0) {
+        super();
+        if (typeof items === "number") {
+          this.length = items;
+          return;
+        }
+        if (items) {
+          for (let i = 0; i < items.length; i++) {
+            this[i] = items[i];
+          }
+        }
+        this._total = Math.trunc(total) || 0;
+        this._limit = Math.trunc(limit) || 0;
+        this._offset = Math.trunc(offset) || 0;
+      }
+      /**
+       * Total rows matching the query's filter, ignoring limit/offset.
+       *
+       * This is the whole point of the collection: the page slice you are iterating
+       * is capped by `limit`, but this number is the full count of matching rows —
+       * what a pager needs to render "page 3 of 13".
+       */
+      getTotalRecords() {
+        return this._total;
+      }
+      /**
+       * The canonical pagination envelope — seven snake_case keys, identical to
+       * `DatabaseResult.toPaginate()` (ADR-0043) and to the other three frameworks'
+       * `toPaginate()` / `to_paginate()`.
+       *
+       *     records     the page's rows as plain objects (never re-sliced)
+       *     total       getTotalRecords() — the true total for the filter
+       *     page        floor(offset / per_page) + 1
+       *     per_page    the query's limit
+       *     total_pages ceil(total / per_page)
+       *     limit       the SQL limit actually applied
+       *     offset      the SQL offset actually applied
+       *
+       * `records` are model dicts (via `toDict()`, the same serialisation the
+       * framework applies to a model in a JSON response), so the JSON a client sees
+       * matches `DatabaseResult` exactly — the result is uniform whether the route
+       * returned a raw `db.fetch()` or an ORM query.
+       */
+      toPaginate() {
+        const perPage = this._limit > 0 ? this._limit : this.length;
+        const page = perPage > 0 ? Math.floor(this._offset / perPage) + 1 : 1;
+        const totalPages = perPage > 0 ? Math.max(1, Math.ceil(this._total / perPage)) : 1;
+        const records = this.map((model) => {
+          const m = model;
+          return m && typeof m.toDict === "function" ? m.toDict() : model;
+        });
+        return {
+          records,
+          total: this._total,
+          page,
+          per_page: perPage,
+          total_pages: totalPages,
+          limit: perPage,
+          offset: this._offset
+        };
+      }
+    };
+  }
+});
+
 // src/databaseUrl.ts
 import { inspect } from "node:util";
 function stripOneSlash(path8) {
@@ -5414,33 +5507,17 @@ var init_engine = __esm({
           i++;
         }
       }
-      handleCache(tokens, start2, context) {
-        const [content] = stripTag(tokens[start2][1]);
-        const m = content.match(/^cache\s+["'](.+?)["']\s*(\d+)?/);
-        const cacheKey = m ? m[1] : "default";
-        const ttl = m && m[2] ? parseInt(m[2], 10) : 60;
-        sweepExpiredCache(this.fragmentCache);
-        const cached = this.fragmentCache.get(cacheKey);
-        if (cached) {
-          const [htmlContent, expiresAt] = cached;
-          if (Date.now() < expiresAt) {
-            let i2 = start2 + 1;
-            let depth2 = 0;
-            while (i2 < tokens.length) {
-              if (tokens[i2][0] === "BLOCK") {
-                const [tagContent] = stripTag(tokens[i2][1]);
-                const tag = tagContent.split(/\s+/)[0] || "";
-                if (tag === "cache") depth2++;
-                else if (tag === "endcache") {
-                  if (depth2 === 0) return [htmlContent, i2 + 1];
-                  depth2--;
-                }
-              }
-              i2++;
-            }
-            return [htmlContent, i2];
-          }
-        }
+      /**
+       * Collect the body tokens of a {% <openTag> %}...{% end<openTag> %} block,
+       * starting from the token after the opening tag (start + 1). Nested same-tag
+       * blocks are kept in the body and balanced by depth; the matching closing tag is
+       * consumed but NOT included. Returns [bodyTokens, indexAfterClosingTag].
+       *
+       * canNest guards the open-tag count: handleSetBlock passes it so the inline
+       * {% set x = 1 %} form (which has no {% endset %}) never opens a nested block —
+       * only the block form {% set x %} nests. Omitted, every openTag occurrence nests.
+       */
+      collectBlockBody(tokens, start2, openTag, closeTag, canNest) {
         const bodyTokens = [];
         let i = start2 + 1;
         let depth = 0;
@@ -5448,10 +5525,10 @@ var init_engine = __esm({
           if (tokens[i][0] === "BLOCK") {
             const [tagContent] = stripTag(tokens[i][1]);
             const tag = tagContent.split(/\s+/)[0] || "";
-            if (tag === "cache") {
+            if (tag === openTag && (canNest ? canNest(tagContent) : true)) {
               depth++;
               bodyTokens.push(tokens[i]);
-            } else if (tag === "endcache") {
+            } else if (tag === closeTag) {
               if (depth === 0) {
                 i++;
                 break;
@@ -5466,6 +5543,36 @@ var init_engine = __esm({
           }
           i++;
         }
+        return [bodyTokens, i];
+      }
+      handleCache(tokens, start2, context) {
+        const [content] = stripTag(tokens[start2][1]);
+        const m = content.match(/^cache\s+["'](.+?)["']\s*(\d+)?/);
+        const cacheKey = m ? m[1] : "default";
+        const ttl = m && m[2] ? parseInt(m[2], 10) : 60;
+        sweepExpiredCache(this.fragmentCache);
+        const cached = this.fragmentCache.get(cacheKey);
+        if (cached) {
+          const [htmlContent, expiresAt] = cached;
+          if (Date.now() < expiresAt) {
+            let i2 = start2 + 1;
+            let depth = 0;
+            while (i2 < tokens.length) {
+              if (tokens[i2][0] === "BLOCK") {
+                const [tagContent] = stripTag(tokens[i2][1]);
+                const tag = tagContent.split(/\s+/)[0] || "";
+                if (tag === "cache") depth++;
+                else if (tag === "endcache") {
+                  if (depth === 0) return [htmlContent, i2 + 1];
+                  depth--;
+                }
+              }
+              i2++;
+            }
+            return [htmlContent, i2];
+          }
+        }
+        const [bodyTokens, i] = this.collectBlockBody(tokens, start2, "cache", "endcache");
         const rendered = this.renderTokens([...bodyTokens], context);
         capCache(this.fragmentCache, TEMPLATE_CACHE_MAX);
         this.fragmentCache.set(cacheKey, [rendered, Date.now() + ttl * 1e3]);
@@ -5630,62 +5737,20 @@ var init_engine = __esm({
       handleSetBlock(tokens, start2, context) {
         const [content] = stripTag(tokens[start2][1]);
         const name = (content.split(/\s+/)[1] || "").trim();
-        const bodyTokens = [];
-        let i = start2 + 1;
-        let depth = 0;
-        while (i < tokens.length) {
-          if (tokens[i][0] === "BLOCK") {
-            const [tagContent] = stripTag(tokens[i][1]);
-            const tag = tagContent.split(/\s+/)[0] || "";
-            if (tag === "set" && !tagContent.includes("=")) {
-              depth++;
-              bodyTokens.push(tokens[i]);
-            } else if (tag === "endset") {
-              if (depth === 0) {
-                i++;
-                break;
-              }
-              depth--;
-              bodyTokens.push(tokens[i]);
-            } else {
-              bodyTokens.push(tokens[i]);
-            }
-          } else {
-            bodyTokens.push(tokens[i]);
-          }
-          i++;
-        }
+        const [bodyTokens, i] = this.collectBlockBody(
+          tokens,
+          start2,
+          "set",
+          "endset",
+          (tagContent) => !tagContent.includes("=")
+        );
         if (name) {
           context[name] = new SafeString(this.renderTokens([...bodyTokens], context));
         }
         return i;
       }
       handleSpaceless(tokens, start2, context) {
-        const bodyTokens = [];
-        let i = start2 + 1;
-        let depth = 0;
-        while (i < tokens.length) {
-          if (tokens[i][0] === "BLOCK") {
-            const [tagContent] = stripTag(tokens[i][1]);
-            const tag = tagContent.split(/\s+/)[0] || "";
-            if (tag === "spaceless") {
-              depth++;
-              bodyTokens.push(tokens[i]);
-            } else if (tag === "endspaceless") {
-              if (depth === 0) {
-                i++;
-                break;
-              }
-              depth--;
-              bodyTokens.push(tokens[i]);
-            } else {
-              bodyTokens.push(tokens[i]);
-            }
-          } else {
-            bodyTokens.push(tokens[i]);
-          }
-          i++;
-        }
+        const [bodyTokens, i] = this.collectBlockBody(tokens, start2, "spaceless", "endspaceless");
         let rendered = this.renderTokens([...bodyTokens], context);
         rendered = rendered.replace(/>\s+</g, "><");
         return [rendered, i];
@@ -5694,31 +5759,7 @@ var init_engine = __esm({
         const [content] = stripTag(tokens[start2][1]);
         const modeMatch = content.match(/^autoescape\s+(false|true)/);
         const autoEscapeOn = !(modeMatch && modeMatch[1] === "false");
-        const bodyTokens = [];
-        let i = start2 + 1;
-        let depth = 0;
-        while (i < tokens.length) {
-          if (tokens[i][0] === "BLOCK") {
-            const [tagContent] = stripTag(tokens[i][1]);
-            const tag = tagContent.split(/\s+/)[0] || "";
-            if (tag === "autoescape") {
-              depth++;
-              bodyTokens.push(tokens[i]);
-            } else if (tag === "endautoescape") {
-              if (depth === 0) {
-                i++;
-                break;
-              }
-              depth--;
-              bodyTokens.push(tokens[i]);
-            } else {
-              bodyTokens.push(tokens[i]);
-            }
-          } else {
-            bodyTokens.push(tokens[i]);
-          }
-          i++;
-        }
+        const [bodyTokens, i] = this.collectBlockBody(tokens, start2, "autoescape", "endautoescape");
         if (!autoEscapeOn) {
           const oldAutoEscape = this._autoEscape;
           this._autoEscape = false;
@@ -23511,7 +23552,7 @@ function toolbarJs() {
     connect();
 })();`;
 }
-var cpuCount, DEV_SAFE_METHODS, DEV_MCP_PREFIXES, DEV_SECRET_BASENAMES, DEV_SECRET_SUFFIXES, MessageLog, RequestInspector, ErrorTracker, DevMailboxStore, DevQueue, WsTracker, DevAdmin, handleDashboard, _reloadMtime, _reloadFile, handleMtime, handleReload, handleMessages, handleMessagesClear, handleRequests, handleRequestsClear, handleSystem, handleMessagesSearch, handleQueue, handleQueueTopics, handleQueueDeadLetters, handleQueueRetry, handleQueuePurge, handleQueueReplay, handleMailbox, handleMailboxRead, handleMailboxSeed, handleMailboxClear, handleTable, handleTables, handleSeed, handleQuery, handleBroken, handleBrokenResolve, handleBrokenClear, handleWebsockets, handleWebsocketsDisconnect, handleTool, handleChat, DEFAULT_MCP_URL, handleGroundingStatus, handleGroundingToken, handleMigrate, handleSeedRun, handleTest, handleThreads, handleThreadsSub, handleConnections, handleConnectionsTest, handleConnectionsSave, __devAdminFilename, __devAdminDirname, handleGalleryList, handleVersionCheck, handleThoughts, handleSuperviseStub, handleExecute, DEV_FILES_IGNORED, handleFiles, DEV_ADMIN_LANG_MAP, handleFileRead, handleFileSave, handleFileRaw, handleFileRename, handleFileDelete, handleDepsSearch, handleDepsInstall, handleGitStatus, handleMcpTools, handleMcpCall, handleMcpStreamable, handleMcpDelete, handleMcpGet405, handleMcpLegacyMessage, handleMcpSse, handleScaffoldList, handleScaffoldRun, handlePlanCurrent, handlePlanList, handlePlanCreate, handlePlanSwitch, handlePlanCompleteStep, handlePlanAddStep, handlePlanNote, handlePlanArchive, handlePlanRead, handlePlanFlesh, handleIndexRebuild, handleIndexSearch, handleIndexFile, handleIndexOverview, handleDocsSearch, handleDocsClass, handleDocsMethod, handleDocsIndex, handleDocsWellKnown, handleDevAdminJs, handleToolbarCss, handleToolbarJs;
+var cpuCount, DEV_SAFE_METHODS, DEV_MCP_PREFIXES, DEV_SECRET_BASENAMES, DEV_SECRET_SUFFIXES, MessageLog, RequestInspector, ErrorTracker, DevMailboxStore, DevQueue, WsTracker, DevAdmin, handleDashboard, _reloadMtime, _reloadFile, handleMtime, handleReload, handleMessages, handleMessagesClear, handleRequests, handleRequestsClear, handleSystem, handleMessagesSearch, handleQueue, handleQueueTopics, handleQueueDeadLetters, handleQueueRetry, handleQueuePurge, handleQueueReplay, handleMailbox, handleMailboxRead, handleMailboxSeed, handleMailboxClear, handleTable, handleTables, handleSeed, handleQuery, handleBroken, handleBrokenResolve, handleBrokenClear, handleWebsockets, handleWebsocketsDisconnect, handleTool, DEFAULT_MCP_URL, handleGroundingStatus, handleGroundingToken, handleMigrate, handleSeedRun, handleTest, handleThreads, handleThreadsSub, handleConnections, handleConnectionsTest, handleConnectionsSave, __devAdminFilename, __devAdminDirname, handleGalleryList, handleVersionCheck, handleThoughts, handleSuperviseStub, DEV_FILES_IGNORED, handleFiles, DEV_ADMIN_LANG_MAP, handleFileRead, handleFileSave, handleFileRaw, handleFileRename, handleFileDelete, handleDepsSearch, handleDepsInstall, handleGitStatus, handleMcpTools, handleMcpCall, handleMcpStreamable, handleMcpDelete, handleMcpGet405, handleMcpLegacyMessage, handleMcpSse, handleScaffoldList, handleScaffoldRun, handlePlanCurrent, handlePlanList, handlePlanCreate, handlePlanSwitch, handlePlanCompleteStep, handlePlanAddStep, handlePlanNote, handlePlanArchive, handlePlanRead, handlePlanFlesh, handleIndexRebuild, handleIndexSearch, handleIndexFile, handleIndexOverview, handleDocsSearch, handleDocsClass, handleDocsMethod, handleDocsIndex, handleDocsWellKnown, handleDevAdminJs, handleToolbarCss, handleToolbarJs;
 var init_devAdmin = __esm({
   "../core/src/devAdmin.ts"() {
     "use strict";
@@ -23849,9 +23890,6 @@ var init_devAdmin = __esm({
           { method: "POST", pattern: "/__dev/api/websockets/disconnect", handler: handleWebsocketsDisconnect },
           // Tools
           { method: "POST", pattern: "/__dev/api/tool", handler: handleTool },
-          // Chat — proxies to Rust agent /chat (SSE passthrough). Forwards
-          // active_file and any other body keys verbatim. See proxyToSupervisor.
-          { method: "POST", pattern: "/__dev/api/chat", handler: handleChat },
           // Threads — proxies to Rust agent /threads. Mirrors Python's
           // _api_threads + _api_threads_sub.
           { method: "GET", pattern: "/__dev/api/threads", handler: handleThreads },
@@ -23930,8 +23968,6 @@ var init_devAdmin = __esm({
           { method: "GET", pattern: "/__dev/api/supervise/diff", handler: handleSuperviseStub },
           { method: "POST", pattern: "/__dev/api/supervise/commit", handler: handleSuperviseStub },
           { method: "POST", pattern: "/__dev/api/supervise/cancel", handler: handleSuperviseStub },
-          // Execute — proxies to the framework_port+2000 Rust agent (SSE passthrough)
-          { method: "POST", pattern: "/__dev/api/execute", handler: handleExecute },
           // Framework-grounding MCP token config — self-contained (.env upsert)
           { method: "GET", pattern: "/__dev/api/grounding/status", handler: handleGroundingStatus },
           { method: "POST", pattern: "/__dev/api/grounding/token", handler: handleGroundingToken },
@@ -24501,9 +24537,6 @@ var init_devAdmin = __esm({
       }
       res.json({ tool, status: "executed", message: `Tool '${tool}' executed (stub)`, timestamp: (/* @__PURE__ */ new Date()).toISOString() });
     };
-    handleChat = async (req2, res) => {
-      await proxyToSupervisor(req2, res, "/chat");
-    };
     DEFAULT_MCP_URL = "https://mcp.tina4.com";
     handleGroundingStatus = async (_req, res) => {
       const token = resolveDevEnvVar("TINA4_MCP_TOKEN");
@@ -24791,35 +24824,6 @@ var init_devAdmin = __esm({
         501
       );
     };
-    handleExecute = async (req2, res) => {
-      const port = parseInt(process.env.TINA4_PORT ?? process.env.PORT ?? "7148", 10);
-      const agentUrl = `http://127.0.0.1:${port + 2e3}/execute`;
-      try {
-        const upstream = await fetch(agentUrl, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify(req2.body ?? {})
-        });
-        if (!upstream.body) {
-          res.json({ error: "agent returned no body" }, 502);
-          return;
-        }
-        res.raw.writeHead(upstream.status || 200, {
-          "Content-Type": upstream.headers.get("content-type") || "text/event-stream",
-          "Cache-Control": "no-cache",
-          Connection: "keep-alive"
-        });
-        const reader = upstream.body.getReader();
-        while (true) {
-          const { done, value } = await reader.read();
-          if (done) break;
-          if (value) res.raw.write(Buffer.from(value));
-        }
-        res.raw.end();
-      } catch (e) {
-        res.json({ error: `agent unreachable at ${agentUrl}: ${e.message}` }, 502);
-      }
-    };
     DEV_FILES_IGNORED = /* @__PURE__ */ new Set([
       "__pycache__",
       "node_modules",
@@ -27297,7 +27301,9 @@ function injectIntoHtml(ctx, devToolbar, html) {
     // Suppress the live reloader on the AI/stable port (data-reload="0"); the
     // toolbar JS early-returns when data-reload !== "1". Mirrors PHP's
     // suppressReload flag.
-    reload: !ctx.isAiPortRequest
+    // Also suppress on the dev-admin dashboard (any /__dev page): its SPA reloads
+    // itself gently, so the toolbar's full-page reloader must not fire there.
+    reload: !ctx.isAiPortRequest && !ctx.pathname.startsWith("/__dev")
   };
   return injectFeedbackWidget(ctx.req, injectDevToolbar(html, toolbarCtx));
 }
@@ -27552,6 +27558,51 @@ async function runDispatch(ctx, rawReq, rawRes) {
   if (!rawRes.headersSent) rawRes.setHeader("x-request-id", requestId);
   return Log.runWithRequestId(requestId, () => dispatchInner(ctx, rawReq, rawRes, requestId));
 }
+function loopbackBindHosts(host) {
+  const normalized = host.trim().replace(/^\[|\]$/g, "").toLowerCase();
+  switch (normalized) {
+    case "localhost":
+      return ["127.0.0.1", "::1"];
+    case "127.0.0.1":
+    case "0.0.0.0":
+      return ["::1"];
+    case "::1":
+    case "::":
+      return ["127.0.0.1"];
+    default:
+      return [];
+  }
+}
+function startLoopbackSiblings(port, host, dispatch) {
+  const siblingHosts = loopbackBindHosts(host);
+  if (siblingHosts.length === 0) return Promise.resolve([]);
+  return Promise.all(
+    siblingHosts.map(
+      (siblingHost) => new Promise((resolveSibling) => {
+        const sibling = createServer2(dispatch);
+        let settled = false;
+        sibling.on("error", (err) => {
+          const expected = err.code === "EADDRINUSE" || err.code === "EADDRNOTAVAIL" || err.code === "EAFNOSUPPORT";
+          if (!expected) {
+            Log.debug(
+              `Loopback sibling ${siblingHost}:${port} not bound (${err.code ?? err.message}) \u2014 skipped, primary already serves`
+            );
+          }
+          if (!settled) {
+            settled = true;
+            resolveSibling(null);
+          }
+        });
+        sibling.listen(port, siblingHost, () => {
+          settled = true;
+          resolveSibling(sibling);
+        });
+      })
+    )
+  ).then(
+    (results) => results.filter((s) => s !== null)
+  );
+}
 async function startServer(config) {
   loadEnv(".env.local");
   loadEnv();
@@ -27820,8 +27871,9 @@ ${reset2}
     }
   });
   return new Promise((resolvePromise) => {
-    server.listen(port, host, () => {
+    server.listen(port, host, async () => {
       if (!cluster.isWorker) writePidfile(port);
+      const siblingServers = await startLoopbackSiblings(port, host, dispatch);
       const displayHost = host === "0.0.0.0" ? "localhost" : host;
       const isDebug = isTruthy(process.env.TINA4_DEBUG);
       const logLevel = (process.env.TINA4_LOG_LEVEL ?? "DEBUG").toUpperCase();
@@ -27884,14 +27936,22 @@ ${reset2}
       }
       let shuttingDown = false;
       const closeListeners = () => new Promise((done) => {
-        let pending = aiServer ? 2 : 1;
+        let pending = 1 + (aiServer ? 1 : 0) + siblingServers.length;
         const one = () => {
           if (--pending === 0) done();
         };
         server.close(one);
         if (aiServer) aiServer.close(one);
+        for (const sibling of siblingServers) {
+          try {
+            sibling.close(one);
+          } catch {
+            one();
+          }
+        }
         server.closeIdleConnections();
         aiServer?.closeIdleConnections();
+        for (const sibling of siblingServers) sibling.closeIdleConnections();
       });
       const gracefulShutdown = async (signal) => {
         if (shuttingDown) return;
@@ -27919,6 +27979,7 @@ ${reset2}
           );
           server.closeAllConnections();
           aiServer?.closeAllConnections();
+          for (const sibling of siblingServers) sibling.closeAllConnections();
         }
         try {
           const orm = await Promise.resolve().then(() => (init_index(), index_exports));
@@ -27946,6 +28007,12 @@ ${reset2}
           stopAllBackgroundTasks();
           if (aiServer) aiServer.close();
           server.close();
+          for (const sibling of siblingServers) {
+            try {
+              sibling.close();
+            } catch {
+            }
+          }
           Promise.resolve().then(() => (init_index(), index_exports)).then((orm) => orm.closeDatabase()).catch(() => {
           });
         },
@@ -35662,6 +35729,7 @@ __export(src_exports2, {
   isValidSessionId: () => isValidSessionId,
   kafkaSecurityConfig: () => kafkaSecurityConfig,
   loadEnv: () => loadEnv,
+  loopbackBindHosts: () => loopbackBindHosts,
   makeCaseInsensitiveHeaders: () => makeCaseInsensitiveHeaders,
   matchCronField: () => matchCronField,
   matchesCron: () => matchesCron,
@@ -43053,6 +43121,7 @@ var init_baseModel = __esm({
   "src/baseModel.ts"() {
     "use strict";
     init_database();
+    init_modelCollection();
     init_validation();
     init_queryBuilder();
     init_sqlite();
@@ -43288,6 +43357,30 @@ var init_baseModel = __esm({
       static getPkColumn() {
         return this.getDbColumn(this.getPkField());
       }
+      /**
+       * Shared read tail for the collection-returning finders (where / all / select
+       * / find filter-form / withTrashed). Runs the SAME two calls `db.fetch()`
+       * makes — the page fetch AND the COUNT probe over the SAME base SQL — hydrates
+       * the rows into model instances, and returns a ModelCollection carrying the
+       * total (ADR-0064).
+       *
+       * The total is FREE: `probeTotal` is the exact `COUNT(*)` probe `db.fetch()`
+       * already runs; the ORM used to discard it. ZERO extra queries beyond that one
+       * probe. `sql` MUST NOT carry its own LIMIT/OFFSET — `adapterFetch` applies
+       * limit/offset to the page, and the probe wraps the un-limited SQL so it counts
+       * the WHOLE filtered set, not the page.
+       */
+      static async _collect(sql, params, limit, offset, include) {
+        const db = this.getDb();
+        const rows = await adapterFetch(db, sql, params, limit, offset);
+        const data = Array.isArray(rows) ? rows : rows?.data ?? [];
+        const total = await probeTotal(db, sql, params, limit) ?? data.length;
+        const instances = data.map((row) => new this(row));
+        if (include) {
+          await this._eagerLoad(instances, include);
+        }
+        return new ModelCollection(instances, total, limit, offset);
+      }
       /**
        * Find a record by primary key.
        * @param id Primary key value.
@@ -43340,7 +43433,6 @@ var init_baseModel = __esm({
           );
         }
         const lim = typeof limit === "number" ? limit : 100;
-        const db = ModelClass.getDb();
         const conditions = [];
         const params = [];
         if (filter) {
@@ -43360,16 +43452,7 @@ var init_baseModel = __esm({
         if (orderBy) {
           sql += ` ORDER BY ${orderBy}`;
         }
-        const rows = await adapterFetch(db, sql, params, lim, offset);
-        const data = rows?.data ?? rows;
-        const instances = (Array.isArray(data) ? data : []).map((row) => {
-          const inst = new this(row);
-          return inst;
-        });
-        if (include) {
-          await ModelClass._eagerLoad(instances, include);
-        }
-        return instances;
+        return ModelClass._collect(sql, params, lim, offset, include);
       }
       /**
        * Load a record into this instance via selectOne.
@@ -43437,7 +43520,6 @@ var init_baseModel = __esm({
        */
       static async all(limit = DEFAULT_ROW_CAP, offset = 0, include, orderBy) {
         const ModelClass = this;
-        const db = ModelClass.getDb();
         const conditions = [];
         if (ModelClass.softDelete) {
           conditions.push("is_deleted = 0");
@@ -43447,13 +43529,8 @@ var init_baseModel = __esm({
         }
         const whereClause = conditions.length > 0 ? ` WHERE ${conditions.join(" AND ")}` : "";
         const orderClause = orderBy ? ` ORDER BY ${orderBy}` : "";
-        const sql = `SELECT * FROM "${ModelClass.tableName}"${whereClause}${orderClause} LIMIT ${limit} OFFSET ${offset}`;
-        const rows = await adapterQuery(db, sql, []);
-        const instances = rows.map((row) => new ModelClass(row));
-        if (include) {
-          await ModelClass._eagerLoad(instances, include);
-        }
-        return instances;
+        const sql = `SELECT * FROM "${ModelClass.tableName}"${whereClause}${orderClause}`;
+        return ModelClass._collect(sql, [], limit, offset, include);
       }
       /**
        * Query records with a WHERE clause.
@@ -43468,7 +43545,6 @@ var init_baseModel = __esm({
        */
       static async where(conditions, params, limit = DEFAULT_ROW_CAP, offset = 0, include, orderBy) {
         const ModelClass = this;
-        const db = ModelClass.getDb();
         const parts = [];
         if (ModelClass.softDelete) {
           parts.push("is_deleted = 0");
@@ -43478,13 +43554,8 @@ var init_baseModel = __esm({
         }
         parts.push(`(${conditions})`);
         const orderClause = orderBy ? ` ORDER BY ${orderBy}` : "";
-        const sql = `SELECT * FROM "${ModelClass.tableName}" WHERE ${parts.join(" AND ")}${orderClause} LIMIT ${limit} OFFSET ${offset}`;
-        const rows = await adapterQuery(db, sql, params);
-        const instances = rows.map((row) => new ModelClass(row));
-        if (include) {
-          await ModelClass._eagerLoad(instances, include);
-        }
-        return instances;
+        const sql = `SELECT * FROM "${ModelClass.tableName}" WHERE ${parts.join(" AND ")}${orderClause}`;
+        return ModelClass._collect(sql, params, limit, offset, include);
       }
       /**
        * Save this instance (insert or update). Returns this on success (fluent
@@ -43964,10 +44035,7 @@ var init_baseModel = __esm({
        */
       static async select(sql, params, limit = DEFAULT_ROW_CAP, offset = 0) {
         const ModelClass = this;
-        const db = ModelClass.getDb();
-        const paged = SQLTranslator.appendLimit(sql, limit, offset);
-        const rows = await adapterQuery(db, paged, params);
-        return rows.map((row) => new ModelClass(row));
+        return ModelClass._collect(sql, params, limit, offset);
       }
       static async selectOne(sql, params, include) {
         const ModelClass = this;
@@ -44039,7 +44107,6 @@ var init_baseModel = __esm({
        */
       static async withTrashed(conditions, params, limit = DEFAULT_ROW_CAP, offset = 0) {
         const ModelClass = this;
-        const db = ModelClass.getDb();
         const parts = [];
         if (ModelClass.tableFilter) {
           parts.push(ModelClass.tableFilter);
@@ -44051,14 +44118,7 @@ var init_baseModel = __esm({
         if (parts.length > 0) {
           sql += ` WHERE ${parts.join(" AND ")}`;
         }
-        if (limit !== void 0) {
-          sql += ` LIMIT ${limit}`;
-        }
-        if (offset !== void 0) {
-          sql += ` OFFSET ${offset}`;
-        }
-        const rows = await adapterQuery(db, sql, params);
-        return rows.map((row) => new ModelClass(row));
+        return ModelClass._collect(sql, params, limit, offset);
       }
       /**
        * Count records matching conditions (respects soft delete and table filter).
@@ -46866,6 +46926,7 @@ __export(index_exports, {
   InvalidId: () => InvalidId,
   LocalStorage: () => LocalStorage,
   Migration: () => Migration,
+  ModelCollection: () => ModelCollection,
   MongodbAdapter: () => MongodbAdapter,
   MssqlAdapter: () => MssqlAdapter,
   MysqlAdapter: () => MysqlAdapter,
@@ -46969,6 +47030,7 @@ var init_index = __esm({
   "src/index.ts"() {
     init_types();
     init_databaseResult();
+    init_modelCollection();
     init_database();
     init_database();
     init_databaseUrl();
@@ -47028,6 +47090,7 @@ export {
   InvalidId,
   LocalStorage,
   Migration,
+  ModelCollection,
   MongodbAdapter,
   MssqlAdapter,
   MysqlAdapter,