tina4-nodejs 3.13.131 → 3.13.133

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",
@@ -25884,12 +25888,46 @@ function sanitizeSecurity(reqs, schemes) {
   });
 }
 function generate2(routes, models = []) {
+  const schemes = resolveSecuritySchemes();
+  const spec = {
+    openapi: resolveOpenApiVersion(),
+    info: buildInfo(),
+    servers: resolveServers(),
+    paths: {},
+    components: {
+      schemas: {},
+      // Configurable security schemes (v3.13.42): bearerFormat via env, optional
+      // apiKey scheme, plus any programmatically-registered schemes (which may
+      // override bearerAuth — e.g. an oauth2 scheme with scopes).
+      securitySchemes: schemes
+    }
+  };
+  const tableToSchema = /* @__PURE__ */ new Map();
+  buildComponentSchemas(models, spec, tableToSchema);
+  const ctx = {
+    models,
+    tableToSchema,
+    schemes,
+    // Default scheme secured routes use when no explicit meta.security is set.
+    defaultScheme: process.env.TINA4_SWAGGER_DEFAULT_SCHEME ?? "bearerAuth",
+    // Path filters (comma-separated raw-path prefixes).
+    includePrefixes: csv(process.env.TINA4_SWAGGER_INCLUDE),
+    excludePrefixes: csv(process.env.TINA4_SWAGGER_EXCLUDE),
+    // Reusable custom schemas referenced by routes via meta.requestSchema/responseSchemas.
+    refSchemas: /* @__PURE__ */ new Set(),
+    usedTags: [],
+    seenIds: /* @__PURE__ */ new Set()
+  };
+  for (const route of routes) {
+    buildOperation(route, spec, ctx);
+  }
+  buildRefSchemas(spec, ctx.refSchemas);
+  buildTags(spec, ctx.usedTags);
+  return spec;
+}
+function buildInfo() {
   const info = {
     title: process.env.TINA4_SWAGGER_TITLE ?? "Tina4 API",
-    // The app's version, defaulting to 1.0.0 — NOT the framework's (Node shipped
-    // 0.0.1). description defaults to the empty string, not a canned sentence.
-    // Both are the settled cross-framework defaults (parity with the Python
-    // master); TINA4_SWAGGER_VERSION / _DESCRIPTION still override.
     version: process.env.TINA4_SWAGGER_VERSION ?? "1.0.0",
     description: process.env.TINA4_SWAGGER_DESCRIPTION ?? ""
   };
@@ -25906,135 +25944,134 @@ function generate2(routes, models = []) {
     const [name, url] = licenseRaw.split("|").map((s) => s.trim());
     info.license = url ? { name, url } : { name };
   }
-  const schemes = resolveSecuritySchemes();
-  const spec = {
-    openapi: resolveOpenApiVersion(),
-    info,
-    servers: resolveServers(),
-    paths: {},
-    components: {
-      schemas: {},
-      // Configurable security schemes (v3.13.42): bearerFormat via env, optional
-      // apiKey scheme, plus any programmatically-registered schemes (which may
-      // override bearerAuth — e.g. an oauth2 scheme with scopes).
-      securitySchemes: schemes
-    }
-  };
-  const defaultScheme = process.env.TINA4_SWAGGER_DEFAULT_SCHEME ?? "bearerAuth";
-  const includePrefixes = csv(process.env.TINA4_SWAGGER_INCLUDE);
-  const excludePrefixes = csv(process.env.TINA4_SWAGGER_EXCLUDE);
-  const refSchemas = /* @__PURE__ */ new Set();
-  const tableToSchema = /* @__PURE__ */ new Map();
+  return info;
+}
+function buildComponentSchemas(models, spec, tableToSchema) {
   for (const model of models) {
     const schemaKey = schemaNameForModel(model);
     tableToSchema.set(model.tableName, schemaKey);
     spec.components.schemas[schemaKey] = modelToSchema(model);
   }
-  const usedTags = [];
-  const seenIds = /* @__PURE__ */ new Set();
-  for (const route of routes) {
-    if (!isIncludedPath(route.pattern, includePrefixes, excludePrefixes)) continue;
-    const openApiPath = patternToOpenAPI(route.pattern);
-    const method = route.method.toLowerCase();
-    if (!spec.paths[openApiPath]) {
-      spec.paths[openApiPath] = {};
-    }
-    const tags = route.meta?.tags ?? inferTags(route.pattern);
-    for (const t of tags) {
-      if (!usedTags.includes(t)) usedTags.push(t);
-    }
-    const operation = {
-      operationId: uniqueOperationId(method, openApiPath, seenIds),
-      summary: route.meta?.summary ?? `${route.method} ${route.pattern}`,
-      tags,
-      responses: route.meta?.responses ?? {
-        "200": { description: "Successful response" }
-      }
-    };
-    if (route.meta?.description) operation.description = route.meta.description;
-    if (route.meta?.deprecated) operation.deprecated = true;
-    const pathParams = extractPathParams(route.pattern);
-    if (pathParams.length > 0) {
-      operation.parameters = pathParams.map(({ name, schema }) => ({
-        name,
-        in: "path",
-        required: true,
-        schema
-      }));
+}
+function buildOperation(route, spec, ctx) {
+  if (!isIncludedPath(route.pattern, ctx.includePrefixes, ctx.excludePrefixes)) return;
+  const openApiPath = patternToOpenAPI(route.pattern);
+  const method = route.method.toLowerCase();
+  if (!spec.paths[openApiPath]) {
+    spec.paths[openApiPath] = {};
+  }
+  const tags = route.meta?.tags ?? inferTags(route.pattern);
+  for (const t of tags) {
+    if (!ctx.usedTags.includes(t)) ctx.usedTags.push(t);
+  }
+  const operation = {
+    operationId: uniqueOperationId(method, openApiPath, ctx.seenIds),
+    summary: route.meta?.summary ?? `${route.method} ${route.pattern}`,
+    tags,
+    responses: route.meta?.responses ?? {
+      "200": { description: "Successful response" }
     }
-    if (method === "get" && !route.pattern.includes("[id]") && !route.pattern.includes("[...")) {
-      const modelName = inferModelFromPath(route.pattern);
-      if (modelName && models.some((m) => m.tableName === modelName)) {
-        operation.parameters = [
-          ...operation.parameters ?? [],
-          { name: "page", in: "query", schema: { type: "integer", default: 1 } },
-          { name: "limit", in: "query", schema: { type: "integer", default: 20 } },
-          { name: "sort", in: "query", schema: { type: "string" }, description: "Sort fields (prefix with - for descending)" }
-        ];
-      }
+  };
+  if (route.meta?.description) operation.description = route.meta.description;
+  if (route.meta?.deprecated) operation.deprecated = true;
+  const parameters = operationParameters(route, method, ctx.models);
+  if (parameters.length > 0) operation.parameters = parameters;
+  operationRequestBody(route, method, operation, ctx);
+  operationResponseSchemas(route, operation, ctx.refSchemas);
+  operationSecurity(route, method, operation, ctx.schemes, ctx.defaultScheme);
+  spec.paths[openApiPath][method] = operation;
+}
+function operationParameters(route, method, models) {
+  let parameters = [];
+  const pathParams = extractPathParams(route.pattern);
+  if (pathParams.length > 0) {
+    parameters = pathParams.map(({ name, schema }) => ({
+      name,
+      in: "path",
+      required: true,
+      schema
+    }));
+  }
+  if (method === "get" && !route.pattern.includes("[id]") && !route.pattern.includes("[...")) {
+    const modelName = inferModelFromPath(route.pattern);
+    if (modelName && models.some((m) => m.tableName === modelName)) {
+      parameters = [
+        ...parameters,
+        { name: "page", in: "query", schema: { type: "integer", default: 1 } },
+        { name: "limit", in: "query", schema: { type: "integer", default: 20 } },
+        { name: "sort", in: "query", schema: { type: "string" }, description: "Sort fields (prefix with - for descending)" }
+      ];
     }
-    const reqSchemaRef = parseRequestSchema(route.meta?.requestSchema);
-    if (reqSchemaRef && (method === "post" || method === "put" || method === "patch")) {
-      refSchemas.add(reqSchemaRef.name);
-      const media = {
-        schema: { $ref: `#/components/schemas/${reqSchemaRef.name}` }
-      };
-      if (route.meta?.example !== void 0) media.example = route.meta.example;
+  }
+  return parameters;
+}
+function mediaWithExample(schema, example) {
+  const media = { schema };
+  if (example !== void 0) media.example = example;
+  return media;
+}
+function operationRequestBody(route, method, operation, ctx) {
+  const reqSchemaRef = parseRequestSchema(route.meta?.requestSchema);
+  if (reqSchemaRef && (method === "post" || method === "put" || method === "patch")) {
+    ctx.refSchemas.add(reqSchemaRef.name);
+    const media = mediaWithExample({ $ref: `#/components/schemas/${reqSchemaRef.name}` }, route.meta?.example);
+    operation.requestBody = {
+      content: { [reqSchemaRef.contentType]: media }
+    };
+  } else if (method === "post" || method === "put") {
+    const modelName = inferModelFromPath(route.pattern);
+    const schemaKey = modelName ? ctx.tableToSchema.get(modelName) : void 0;
+    if (schemaKey) {
+      const sref = `#/components/schemas/${schemaKey}`;
       operation.requestBody = {
-        content: { [reqSchemaRef.contentType]: media }
+        required: true,
+        content: { "application/json": mediaWithExample({ $ref: sref }, route.meta?.example) }
       };
-    } else if (method === "post" || method === "put") {
-      const modelName = inferModelFromPath(route.pattern);
-      const schemaKey = modelName ? tableToSchema.get(modelName) : void 0;
-      if (schemaKey) {
-        const sref = `#/components/schemas/${schemaKey}`;
-        const media = { schema: { $ref: sref } };
-        if (route.meta?.example !== void 0) media.example = route.meta.example;
-        operation.requestBody = {
-          required: true,
-          content: { "application/json": media }
-        };
-        if (route.meta?.responses === void 0) {
-          operation.responses = {
-            "200": { description: "Successful response", content: { "application/json": { schema: { $ref: sref } } } }
-          };
-        }
-      } else if (route.meta?.example !== void 0) {
-        operation.requestBody = {
-          content: { "application/json": { schema: inferSchema(route.meta.example), example: route.meta.example } }
+      if (route.meta?.responses === void 0) {
+        operation.responses = {
+          "200": { description: "Successful response", content: { "application/json": { schema: { $ref: sref } } } }
         };
       }
+    } else if (route.meta?.example !== void 0) {
+      operation.requestBody = {
+        content: { "application/json": { schema: inferSchema(route.meta.example), example: route.meta.example } }
+      };
     }
-    const respSchemas = parseResponseSchemas(route.meta?.responseSchemas);
-    if (respSchemas.length > 0) {
-      const responses = operation.responses;
-      for (const { status: status2, name, isList } of respSchemas) {
-        refSchemas.add(name);
-        const sref = `#/components/schemas/${name}`;
-        const schema = isList ? { type: "array", items: { $ref: sref } } : { $ref: sref };
-        responses[status2] = {
-          description: status2.startsWith("2") ? "Successful response" : "Response",
-          content: { "application/json": { schema } }
-        };
-      }
+  }
+}
+function operationResponseSchemas(route, operation, refSchemas) {
+  const respSchemas = parseResponseSchemas(route.meta?.responseSchemas);
+  if (respSchemas.length > 0) {
+    const responses = operation.responses;
+    for (const { status: status2, name, isList } of respSchemas) {
+      refSchemas.add(name);
+      const sref = `#/components/schemas/${name}`;
+      const schema = isList ? { type: "array", items: { $ref: sref } } : { $ref: sref };
+      responses[status2] = {
+        description: status2.startsWith("2") ? "Successful response" : "Response",
+        content: { "application/json": { schema } }
+      };
     }
-    const hasExplicitSecurity = route.meta?.security !== void 0 || route.meta?.scopes !== void 0 && route.meta.scopes.length > 0;
-    if (hasExplicitSecurity) {
-      const normalized = normalizeSecurity(route.meta?.security, route.meta?.scopes);
-      operation.security = normalized.length > 0 ? sanitizeSecurity(normalized, schemes) : [];
-      if (normalized.length > 0) {
-        const responses = operation.responses;
-        if (!responses["401"]) responses["401"] = { description: "Unauthorized" };
-      }
-    } else if (routeRequiresAuth(route, method)) {
-      const requirements = [{ [defaultScheme]: [] }];
-      if (defaultScheme === "bearerAuth" && schemes.ssoSession) requirements.push({ ssoSession: [] });
-      operation.security = sanitizeSecurity(requirements, schemes);
+  }
+}
+function operationSecurity(route, method, operation, schemes, defaultScheme) {
+  const hasExplicitSecurity = route.meta?.security !== void 0 || route.meta?.scopes !== void 0 && route.meta.scopes.length > 0;
+  if (hasExplicitSecurity) {
+    const normalized = normalizeSecurity(route.meta?.security, route.meta?.scopes);
+    operation.security = normalized.length > 0 ? sanitizeSecurity(normalized, schemes) : [];
+    if (normalized.length > 0) {
       const responses = operation.responses;
       if (!responses["401"]) responses["401"] = { description: "Unauthorized" };
     }
-    spec.paths[openApiPath][method] = operation;
+  } else if (routeRequiresAuth(route, method)) {
+    const requirements = [{ [defaultScheme]: [] }];
+    if (defaultScheme === "bearerAuth" && schemes.ssoSession) requirements.push({ ssoSession: [] });
+    operation.security = sanitizeSecurity(requirements, schemes);
+    const responses = operation.responses;
+    if (!responses["401"]) responses["401"] = { description: "Unauthorized" };
   }
+}
+function buildRefSchemas(spec, refSchemas) {
   if (refSchemas.size > 0) {
     const schemas = spec.components.schemas;
     for (const name of refSchemas) {
@@ -26043,10 +26080,11 @@ function generate2(routes, models = []) {
       }
     }
   }
+}
+function buildTags(spec, usedTags) {
   if (usedTags.length > 0) {
     spec.tags = usedTags.map((name) => ({ name }));
   }
-  return spec;
 }
 function routeRequiresAuth(route, method) {
   if (route.noAuth) return false;
@@ -27297,7 +27335,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 +27592,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 +27905,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 +27970,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 +28013,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 +28041,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 +35763,7 @@ __export(src_exports2, {
   isValidSessionId: () => isValidSessionId,
   kafkaSecurityConfig: () => kafkaSecurityConfig,
   loadEnv: () => loadEnv,
+  loopbackBindHosts: () => loopbackBindHosts,
   makeCaseInsensitiveHeaders: () => makeCaseInsensitiveHeaders,
   matchCronField: () => matchCronField,
   matchesCron: () => matchesCron,
@@ -43053,6 +43155,7 @@ var init_baseModel = __esm({
   "src/baseModel.ts"() {
     "use strict";
     init_database();
+    init_modelCollection();
     init_validation();
     init_queryBuilder();
     init_sqlite();
@@ -43288,6 +43391,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 +43467,6 @@ var init_baseModel = __esm({
           );
         }
         const lim = typeof limit === "number" ? limit : 100;
-        const db = ModelClass.getDb();
         const conditions = [];
         const params = [];
         if (filter) {
@@ -43360,16 +43486,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 +43554,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 +43563,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 +43579,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 +43588,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 +44069,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 +44141,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 +44152,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 +46960,7 @@ __export(index_exports, {
   InvalidId: () => InvalidId,
   LocalStorage: () => LocalStorage,
   Migration: () => Migration,
+  ModelCollection: () => ModelCollection,
   MongodbAdapter: () => MongodbAdapter,
   MssqlAdapter: () => MssqlAdapter,
   MysqlAdapter: () => MysqlAdapter,
@@ -46969,6 +47064,7 @@ var init_index = __esm({
   "src/index.ts"() {
     init_types();
     init_databaseResult();
+    init_modelCollection();
     init_database();
     init_database();
     init_databaseUrl();
@@ -47028,6 +47124,7 @@ export {
   InvalidId,
   LocalStorage,
   Migration,
+  ModelCollection,
   MongodbAdapter,
   MssqlAdapter,
   MysqlAdapter,