tina4-nodejs 3.13.103 → 3.13.105

package/packages/orm/dist/index.js

@@ -582,13 +582,172 @@ var init_databaseUrl = __esm({
   }
 });
 
+// src/point.ts
+function formatCoordinate(value) {
+  return Object.is(value, -0) ? "0" : Number(value.toPrecision(15)).toString();
+}
+var DEFAULT_SRID, SpatialNotSupportedError, Point;
+var init_point = __esm({
+  "src/point.ts"() {
+    "use strict";
+    DEFAULT_SRID = 4326;
+    SpatialNotSupportedError = class extends Error {
+      constructor(message) {
+        super(message);
+        this.name = "SpatialNotSupportedError";
+      }
+    };
+    Point = class _Point {
+      lon;
+      lat;
+      srid;
+      constructor(lon, lat, srid = DEFAULT_SRID) {
+        if (typeof lon === "boolean" || typeof lat === "boolean" || typeof srid === "boolean") {
+          throw new TypeError("Point longitude, latitude and SRID must be numbers");
+        }
+        this.lon = Number(lon);
+        this.lat = Number(lat);
+        this.srid = Number(srid);
+        if (!Number.isFinite(this.lon) || !Number.isFinite(this.lat) || !Number.isInteger(this.srid)) {
+          throw new TypeError("Point longitude and latitude must be finite numbers and SRID must be an integer");
+        }
+        if (this.srid === DEFAULT_SRID) {
+          if (this.lon < -180 || this.lon > 180) throw new RangeError(`Point longitude ${this.lon} is outside -180..180; Tina4 uses longitude, latitude order`);
+          if (this.lat < -90 || this.lat > 90) throw new RangeError(`Point latitude ${this.lat} is outside -90..90; Tina4 uses longitude, latitude order`);
+        }
+        Object.freeze(this);
+      }
+      get wkt() {
+        return `POINT(${formatCoordinate(this.lon)} ${formatCoordinate(this.lat)})`;
+      }
+      get ewkt() {
+        return `SRID=${this.srid};${this.wkt}`;
+      }
+      get geojson() {
+        return { type: "Point", coordinates: [this.lon, this.lat] };
+      }
+      toJSON() {
+        return this.geojson;
+      }
+      toArray() {
+        return [this.lon, this.lat];
+      }
+      static parse(value, srid = DEFAULT_SRID) {
+        if (value instanceof _Point) return value;
+        if (Array.isArray(value)) {
+          if (value.length < 2) throw new TypeError("Point coordinate pair needs longitude and latitude");
+          return new _Point(value[0], value[1], srid);
+        }
+        if (value && typeof value === "object" && !(value instanceof Uint8Array)) {
+          return _Point.fromGeoJson(value, srid);
+        }
+        if (value instanceof Uint8Array) return _Point.fromWkb(value, srid);
+        if (typeof value === "string") {
+          const text = value.trim();
+          const match = /^(?:SRID\s*=\s*(\d+)\s*;\s*)?POINT\s*(?:Z|M|ZM)?\s*\(\s*([-+0-9.eE]+)\s+([-+0-9.eE]+)(?:\s+[-+0-9.eE]+)*\s*\)$/i.exec(text);
+          if (match) return new _Point(match[2], match[3], match[1] ? Number(match[1]) : srid);
+          if (text.length >= 42 && text.length % 2 === 0 && /^[0-9a-f]+$/i.test(text)) {
+            return _Point.fromWkb(Uint8Array.from(Buffer.from(text, "hex")), srid);
+          }
+        }
+        throw new TypeError("Point must be Point, [longitude, latitude], WKT/EWKT, GeoJSON or WKB/EWKB");
+      }
+      static geometryBinding(value, srid = DEFAULT_SRID) {
+        if (value instanceof _Point || Array.isArray(value)) return [_Point.parse(value, srid).ewkt, "ewkt"];
+        if (value && typeof value === "object") {
+          const candidate = value;
+          const geometry = String(candidate.type).toLowerCase() === "feature" ? candidate.geometry : candidate;
+          const allowed = /* @__PURE__ */ new Set(["point", "linestring", "polygon", "multipoint", "multilinestring", "multipolygon", "geometrycollection"]);
+          if (!geometry || !allowed.has(String(geometry.type).toLowerCase())) throw new TypeError("GeoJSON geometry has an unsupported type");
+          return [JSON.stringify(geometry), "geojson"];
+        }
+        if (typeof value === "string" && /^\s*(?:SRID\s*=\s*\d+\s*;\s*)?(?:POINT|LINESTRING|POLYGON|MULTIPOINT|MULTILINESTRING|MULTIPOLYGON|GEOMETRYCOLLECTION)\b/i.test(value)) {
+          return [/^\s*SRID/i.test(value) ? value.trim() : `SRID=${srid};${value.trim()}`, "ewkt"];
+        }
+        throw new TypeError("Geometry must be Point, coordinate pair, WKT/EWKT or GeoJSON");
+      }
+      static fromGeoJson(data, srid) {
+        const geometry = String(data.type).toLowerCase() === "feature" ? data.geometry : data;
+        if (!geometry || String(geometry.type).toLowerCase() !== "point") throw new TypeError("Point GeoJSON type must be Point");
+        const coordinates = geometry.coordinates;
+        if (!Array.isArray(coordinates) || coordinates.length < 2) throw new TypeError("Point GeoJSON coordinates must be [longitude, latitude]");
+        return new _Point(coordinates[0], coordinates[1], srid);
+      }
+      static fromWkb(raw, srid) {
+        if (raw.byteLength < 21) throw new TypeError("Point WKB is too short");
+        const view = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);
+        const little = raw[0] === 1;
+        const typeWord = view.getUint32(1, little);
+        let offset = 5;
+        if ((typeWord & 536870912) !== 0) {
+          srid = view.getUint32(5, little);
+          offset = 9;
+        }
+        const code = (typeWord & ~(536870912 | 1073741824 | 2147483648)) % 1e3;
+        if (code !== 1 || raw.byteLength < offset + 16) throw new TypeError("WKB geometry is not a Point");
+        return new _Point(view.getFloat64(offset, little), view.getFloat64(offset + 8, little), srid);
+      }
+    };
+  }
+});
+
 // src/sqlTranslator.ts
 var SQLTranslator, QueryCache;
 var init_sqlTranslator = __esm({
   "src/sqlTranslator.ts"() {
     "use strict";
     init_databaseUrl();
+    init_point();
     SQLTranslator = class _SQLTranslator {
+      static SPATIAL_ENGINES = /* @__PURE__ */ new Set(["postgres", "postgresql"]);
+      static SPATIAL_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+      static requireSpatial(engine, feature) {
+        const name = String(engine || "unknown").toLowerCase();
+        if (!_SQLTranslator.SPATIAL_ENGINES.has(name)) {
+          throw new SpatialNotSupportedError(
+            `${feature} is not supported on the '${name}' database engine. Tina4 GIS support is PostGIS-first: use PostgreSQL with CREATE EXTENSION postgis. Tina4 will not replace a spatial query with an approximate coordinate query.`
+          );
+        }
+        return name;
+      }
+      static spatialIdentifier(name, what = "column") {
+        if (!_SQLTranslator.SPATIAL_IDENTIFIER.test(name)) throw new TypeError(`Spatial ${what} is not a valid SQL identifier: ${name}`);
+        return name;
+      }
+      static pointColumnType(engine, srid = DEFAULT_SRID) {
+        _SQLTranslator.requireSpatial(engine, "PointField");
+        return `geography(Point,${srid})`;
+      }
+      static spatialIndex(engine, table2, column2) {
+        _SQLTranslator.requireSpatial(engine, "spatial index creation");
+        table2 = _SQLTranslator.spatialIdentifier(table2, "table");
+        column2 = _SQLTranslator.spatialIdentifier(column2);
+        return `CREATE INDEX IF NOT EXISTS ${table2.replaceAll(".", "_")}_${column2}_gist ON ${table2} USING GIST (${column2})`;
+      }
+      static pointLiteral(engine, srid = DEFAULT_SRID) {
+        _SQLTranslator.requireSpatial(engine, "spatial predicates");
+        return `ST_SetSRID(ST_MakePoint(?, ?), ${srid})::geography`;
+      }
+      static withinDistance(engine, column2, srid = DEFAULT_SRID) {
+        return `ST_DWithin(${_SQLTranslator.spatialIdentifier(column2)}, ${_SQLTranslator.pointLiteral(engine, srid)}, ?)`;
+      }
+      static distance(engine, column2, srid = DEFAULT_SRID) {
+        return `ST_Distance(${_SQLTranslator.spatialIdentifier(column2)}, ${_SQLTranslator.pointLiteral(engine, srid)})`;
+      }
+      static distanceAs(engine, column2, alias, srid = DEFAULT_SRID) {
+        return `${_SQLTranslator.distance(engine, column2, srid)} AS ${_SQLTranslator.spatialIdentifier(alias, "result alias")}`;
+      }
+      static geometryLiteral(engine, form, srid = DEFAULT_SRID) {
+        _SQLTranslator.requireSpatial(engine, "spatial predicates");
+        return form === "ewkt" ? "ST_GeogFromText(?)" : `ST_SetSRID(ST_GeomFromGeoJSON(?), ${srid})::geography`;
+      }
+      static intersects(engine, column2, form = "ewkt", srid = DEFAULT_SRID) {
+        return `ST_Intersects(${_SQLTranslator.spatialIdentifier(column2)}, ${_SQLTranslator.geometryLiteral(engine, form, srid)})`;
+      }
+      static bbox(engine, column2, srid = DEFAULT_SRID) {
+        _SQLTranslator.requireSpatial(engine, "bbox");
+        return `ST_Intersects(${_SQLTranslator.spatialIdentifier(column2)}, ST_MakeEnvelope(?, ?, ?, ?, ${srid})::geography)`;
+      }
       /**
        * Convert LIMIT/OFFSET to Firebird ROWS...TO syntax.
        *
@@ -8773,6 +8932,12 @@ function enforceRouteAuth(req2, res, match, isDevAdmin) {
     }
   }
   if (!resolvedToken) {
+    const sso = req2.session?.get?.("_tina4_sso");
+    const identity = sso?.identity;
+    if (identity?.issuer && identity?.subject) {
+      req2.user = identity;
+      return false;
+    }
     const sessionToken = req2.session?.get?.("token");
     if (sessionToken && validToken(sessionToken)) {
       resolvedToken = sessionToken;
@@ -17084,17 +17249,67 @@ var init_mongoBackend = __esm({
             process.stdout.write("__OK__");
           }
           else if (operation === "retry") {
-            // Explicit manual re-queue (always re-enqueues). data = JSON
-            // { id, delaySeconds }.
+            // Explicit manual re-queue. Serves BOTH Queue.retry(id) (revive
+            // a dead-letter job) AND job.retry() (manual re-queue of a live
+            // reserved/pending job) so the Mongo backend matches
+            // LiteBackend's dual behaviour.
+            //
+            // 1) DL revival (Queue.retry(id) after fail exhausted retries).
+            //    Pre-3.13.105 this branch was BROKEN: the search filter was
+            //    { queue: queueName, id, status: "failed" } -- three separate
+            //    reasons it could never match. dead_letter() inserts under
+            //    queueName + ".dead_letter" (not queueName), carries
+            //    status "dead" (not "failed"), and the original under
+            //    queueName was already acked to "completed" by the time the
+            //    DL was written. Now we look up in the DL namespace by id,
+            //    delete the DL doc first (so an interrupted retry never
+            //    leaves both a DL and a fresh pending doc), and upsert the
+            //    original back to pending -- re-hydrating if the original
+            //    was purged (housekeeping) so a retry always works.
+            // 2) Live-doc manual re-queue (job.retry() on a job the caller
+            //    just popped and wants back in pending). The live-doc path
+            //    is preserved from before 3.13.105.
+            //
+            // Returns __OK__ when either path acted; __NOT_FOUND__ when
+            // neither the DL nor the live doc existed, so Queue.retry(id)
+            // can now report the pre-3.13.105 blanket-true as false for
+            // unknown ids. data = JSON { id, delaySeconds }.
             const info = JSON.parse(data);
+            const dlTopic = queueName + ".dead_letter";
+            const now = new Date().toISOString();
             const avail = info.delaySeconds > 0
               ? new Date(Date.now() + info.delaySeconds * 1000).toISOString()
-              : new Date().toISOString();
-            await col.updateOne(
-              { queue: queueName, id: info.id },
-              { $set: { status: "pending", availableAt: avail, reservedAt: null }, $inc: { attempts: 1 } },
-            );
-            process.stdout.write("__OK__");
+              : now;
+            const dlDoc = await col.findOne({ queue: dlTopic, id: info.id });
+            if (dlDoc !== null) {
+              await col.deleteOne({ _id: dlDoc._id });
+              const payload = dlDoc.payload ?? {};
+              const priority = dlDoc.priority ?? 0;
+              await col.updateOne(
+                { queue: queueName, id: info.id },
+                {
+                  $set: {
+                    status: "pending",
+                    availableAt: avail,
+                    reservedAt: null,
+                    error: null,
+                    payload,
+                    priority,
+                    id: info.id,
+                    createdAt: dlDoc.createdAt ?? now,
+                  },
+                  $inc: { attempts: 1 },
+                },
+                { upsert: true },
+              );
+              process.stdout.write("__OK__");
+            } else {
+              const result = await col.updateOne(
+                { queue: queueName, id: info.id },
+                { $set: { status: "pending", availableAt: avail, reservedAt: null }, $inc: { attempts: 1 } },
+              );
+              process.stdout.write(result.matchedCount > 0 ? "__OK__" : "__NOT_FOUND__");
+            }
           }
           else if (operation === "deadLetters") {
             const docs = await col.find({ queue: queueName + ".dead_letter" }).toArray();
@@ -17139,10 +17354,20 @@ var init_mongoBackend = __esm({
             process.stdout.write(String(revived));
           }
           else if (operation === "purge") {
-            // Delete docs by status (default: all for the topic). data = JSON { status }.
+            // Delete docs by status (default: every doc for the topic).
+            // Pre-3.13.105 this filtered by { queue: queueName, status } for
+            // EVERY status -- correct for pending/reserved/completed, wrong
+            // for the dead-letter states (dead/failed/dead_letter) which
+            // live under queueName + ".dead_letter" and carry status "dead".
+            // A purge("dead") therefore deleted nothing and returned 0.
+            // data = JSON { status }.
             const info = data ? JSON.parse(data) : {};
-            const filter = { queue: queueName };
-            if (info.status) filter.status = info.status;
+            const isDead = info.status && ["dead", "failed", "dead_letter"].includes(info.status);
+            const filter = isDead
+              ? { queue: queueName + ".dead_letter" }
+              : (info.status
+                ? { queue: queueName, status: info.status }
+                : { queue: queueName });
             const res = await col.deleteMany(filter);
             process.stdout.write(String(res.deletedCount || 0));
           }
@@ -17239,9 +17464,15 @@ var init_mongoBackend = __esm({
       fail(queue, id, error, maxRetries, retryBackoff = 0) {
         this.execSync("fail", queue, JSON.stringify({ id, error, maxRetries, retryBackoff }));
       }
-      /** Explicit manual re-queue (always re-enqueues regardless of the retry limit). */
+      /**
+       * Revive a specific dead-letter job by id. Returns true if the DL was found
+       * and revived, false otherwise (parity with LiteBackend.retry(queue, id)
+       * and Python's mongo_backend.retry_job()). Pre-3.13.105 this returned void
+       * and Queue.retry(id) reported success for every call, even for unknown ids.
+       */
       retry(queue, id, delaySeconds = 0) {
-        this.execSync("retry", queue, JSON.stringify({ id, delaySeconds }));
+        const out = this.execSync("retry", queue, JSON.stringify({ id, delaySeconds }));
+        return out.includes("__OK__");
       }
       /** Jobs that exceeded max retries (the `<queue>.dead_letter` collection topic). */
       deadLetters(queue, maxRetries) {
@@ -17910,10 +18141,20 @@ var init_liteBackend = __esm({
        * Explicit re-queue requested by the caller (job.retry()).
        *
        * Always re-enqueues regardless of the retry limit — manual override,
-       * distinct from the automatic failJob() path.
+       * distinct from the automatic failJob() path. Cleans up BOTH the
+       * reservation record AND any dead-letter file for this id, so a caller
+       * that iterates deadLetters() and calls .retry() on each doesn't leave
+       * the failed/ directory carrying duplicates (PY-12-05, 3.13.105).
+       * Aligns with retry(queue, jobId) which had always unlinked the
+       * dead-letter file -- two spellings of the same intent that previously
+       * diverged.
        */
       retryJob(queue, job, delaySeconds) {
         this.clearReservation(queue, job.id);
+        try {
+          unlinkSync6(join17(this.ensureFailedDir(queue), `${job.id}.queue-data`));
+        } catch {
+        }
         job.attempts = (job.attempts || 0) + 1;
         job.error = void 0;
         this.requeue(queue, job, delaySeconds ?? 0, void 0);
@@ -18112,7 +18353,19 @@ var init_queue = __esm({
         }
       }
       /**
-       * Count jobs filtered by status. Defaults to "pending".
+       * Count jobs by status. Defaults to "pending".
+       *
+       * ``"pending"`` counts jobs waiting to be popped -- INCLUDES retryable-
+       * but-attempted ones, because they live in the pending queue under the
+       * auto-retry lifecycle (see failed()).
+       * ``"reserved"`` counts jobs a consumer has popped but not yet
+       * completed/failed (in-flight against the visibility timeout).
+       * ``"completed"`` counts jobs the consumer has finished successfully.
+       * ``"failed"``, ``"dead"``, ``"dead_letter"`` are ALIASES that all count
+       * the dead-letter store -- jobs whose attempts >= maxRetries and that
+       * have given up. Use deadLetters() to list them. Retryable-but-attempted
+       * jobs are NOT counted by size("failed"); use failed() to list them or
+       * size("pending") to include them in a total.
        */
       size(status2 = "pending") {
         const q = this.topic;
@@ -18162,13 +18415,17 @@ var init_queue = __esm({
       /**
        * Get jobs that failed at least once but are still being retried
        * (0 < attempts < maxRetries). These live in the pending queue under the
-       * auto-retry lifecycle; dead-lettered jobs are returned by deadLetters().
+       * auto-retry lifecycle (fail() re-queues them with an incremented attempts
+       * count and a retryBackoff delay) so pop() picks them up again. They are
+       * NOT counted by size("failed") -- that alias counts the dead-letter store,
+       * matching deadLetters(). To include retryable-failed jobs in a total, use
+       * size("pending"). Terminal failures are returned by deadLetters().
        */
       failed() {
-        if (this.externalBackend?.failed) {
-          return this.externalBackend.failed(this.topic, this._maxRetries);
-        }
-        return this.liteBackend.failed(this.topic, this._maxRetries);
+        const raw = this.externalBackend?.failed ? this.externalBackend.failed(this.topic, this._maxRetries) : this.liteBackend.failed(this.topic, this._maxRetries);
+        return raw.map(
+          (data) => createJob({ ...data, topic: data.topic ?? this.topic }, this)
+        );
       }
       /**
        * Retry all dead letter jobs for this queue's topic.
@@ -18180,8 +18437,8 @@ var init_queue = __esm({
       retry(jobId, delaySeconds) {
         if (jobId) {
           if (this.externalBackend?.retry) {
-            this.externalBackend.retry(this.topic, jobId, delaySeconds);
-            return true;
+            const result = this.externalBackend.retry(this.topic, jobId, delaySeconds);
+            return result === void 0 ? true : Boolean(result);
           }
           return this.liteBackend.retry(this.topic, jobId, delaySeconds);
         }
@@ -18190,8 +18447,8 @@ var init_queue = __esm({
         let retried = false;
         for (const job of deadJobs) {
           if (this.externalBackend?.retry) {
-            this.externalBackend.retry(this.topic, job.id, delaySeconds);
-            retried = true;
+            const result = this.externalBackend.retry(this.topic, job.id, delaySeconds);
+            if (result === void 0 || Boolean(result)) retried = true;
           } else if (this.liteBackend.retry(this.topic, job.id, delaySeconds)) {
             retried = true;
           }
@@ -18199,13 +18456,28 @@ var init_queue = __esm({
         return retried;
       }
       /**
-       * Get dead letter jobs — failed jobs that exceeded max retries.
+       * Get jobs that exceeded max_retries -- terminal failures.
+       *
+       * Same set counted by size("failed") / size("dead") / size("dead_letter")
+       * (three aliases for the dead-letter store). To LIST retryable-but-
+       * attempted jobs (attempts > 0 AND attempts < maxRetries) that are still
+       * being auto-retried, use failed() -- those live in the pending queue and
+       * are NOT dead letters.
+       *
+       * Returns Job objects with the failure reason on ``.error`` (not raw dicts)
+       * so callers can iterate uniformly with the rest of the queue API and, in
+       * particular, call ``.retry()`` on each to manually revive it:
+       *
+       *     for (const job of queue.deadLetters()) {
+       *       Log.warn(`revived ${job.id}: ${job.error}`);
+       *       job.retry();
+       *     }
        */
       deadLetters(maxRetries) {
-        if (this.externalBackend?.deadLetters) {
-          return this.externalBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries);
-        }
-        return this.liteBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries);
+        const raw = this.externalBackend?.deadLetters ? this.externalBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries) : this.liteBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries);
+        return raw.map(
+          (data) => createJob({ ...data, topic: data.topic ?? this.topic }, this)
+        );
       }
       /**
        * Delete messages by status (e.g. "completed", "failed", "dead").
@@ -23324,6 +23596,14 @@ function resolveSecuritySchemes() {
     const apiKeyIn = ["header", "query", "cookie"].includes(rawIn) ? rawIn : "header";
     schemes.apiKeyAuth = { type: "apiKey", name: apiKeyName, in: apiKeyIn };
   }
+  const ssoIssuer = (process.env.TINA4_SSO_ISSUER ?? "").replace(/\/$/, "");
+  if (ssoIssuer) {
+    schemes.oidc = {
+      type: "openIdConnect",
+      openIdConnectUrl: `${ssoIssuer}/.well-known/openid-configuration`
+    };
+    schemes.ssoSession = { type: "apiKey", in: "cookie", name: "tina4_session" };
+  }
   for (const [name, def] of Object.entries(registeredSchemes)) {
     schemes[name] = def;
   }
@@ -23505,7 +23785,9 @@ function generate(routes, models = []) {
         if (!responses["401"]) responses["401"] = { description: "Unauthorized" };
       }
     } else if (routeRequiresAuth(route, method)) {
-      operation.security = sanitizeSecurity([{ [defaultScheme]: [] }], schemes);
+      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" };
     }
@@ -23819,6 +24101,298 @@ var init_src = __esm({
   }
 });
 
+// ../core/src/sso.ts
+var sso_exports = {};
+__export(sso_exports, {
+  SSO: () => Sso,
+  Sso: () => Sso,
+  SsoError: () => SsoError
+});
+import { createHash as createHash9, randomBytes as randomBytes5, timingSafeEqual as timingSafeEqual3 } from "node:crypto";
+var SsoError, Sso;
+var init_sso = __esm({
+  "../core/src/sso.ts"() {
+    "use strict";
+    SsoError = class extends Error {
+    };
+    Sso = class _Sso {
+      static PENDING_KEY = "_tina4_sso_pending";
+      static SESSION_KEY = "_tina4_sso";
+      issuer;
+      clientId;
+      clientSecret;
+      redirectUri;
+      scopes;
+      verify;
+      postLogoutRedirectUri;
+      claimMap;
+      timeout;
+      metadata = {};
+      static mountedRouters = /* @__PURE__ */ new WeakSet();
+      constructor(options = {}) {
+        this.issuer = (options.issuer ?? process.env.TINA4_SSO_ISSUER ?? "").replace(/\/$/, "");
+        this.clientId = options.clientId ?? process.env.TINA4_SSO_CLIENT_ID ?? "";
+        this.clientSecret = options.clientSecret ?? process.env.TINA4_SSO_CLIENT_SECRET;
+        this.redirectUri = options.redirectUri ?? process.env.TINA4_SSO_REDIRECT_URI ?? "";
+        this.scopes = options.scopes ?? this.jsonEnv("TINA4_SSO_SCOPES", ["openid", "profile", "email"]);
+        this.verify = options.verify ?? process.env.TINA4_SSO_VERIFY ?? "introspection";
+        this.postLogoutRedirectUri = options.postLogoutRedirectUri ?? process.env.TINA4_SSO_POST_LOGOUT_REDIRECT_URI;
+        this.claimMap = options.claimMap ?? this.jsonEnv("TINA4_SSO_CLAIM_MAP", {});
+        this.timeout = options.timeout ?? 1e4;
+        this.validateConfig();
+      }
+      static async fromIssuer(options = {}) {
+        const value = new _Sso(options);
+        await value.discover();
+        return value;
+      }
+      static configured() {
+        return ["TINA4_SSO_ISSUER", "TINA4_SSO_CLIENT_ID", "TINA4_SSO_REDIRECT_URI"].every((key) => Boolean(process.env[key]));
+      }
+      jsonEnv(name, fallback) {
+        const raw = process.env[name];
+        if (!raw) return fallback;
+        try {
+          return JSON.parse(raw);
+        } catch {
+          throw new SsoError(`${name} must be valid JSON`);
+        }
+      }
+      static secureUrl(value, name) {
+        let url;
+        try {
+          url = new URL(value);
+        } catch {
+          throw new SsoError(`${name} must be an absolute URL`);
+        }
+        const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+        if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+          throw new SsoError(`${name} must use HTTPS except on loopback`);
+        }
+      }
+      validateConfig() {
+        if (!this.issuer || !this.clientId || !this.redirectUri) {
+          throw new SsoError("TINA4_SSO_ISSUER, TINA4_SSO_CLIENT_ID and TINA4_SSO_REDIRECT_URI are required");
+        }
+        _Sso.secureUrl(this.issuer, "issuer");
+        _Sso.secureUrl(this.redirectUri, "redirect URI");
+        if (!["introspection", "jwks"].includes(this.verify)) throw new SsoError("TINA4_SSO_VERIFY must be introspection or jwks");
+        if (this.verify === "jwks") throw new SsoError("jwks verification requires an installed cryptography capability");
+        if (this.verify === "introspection" && !this.clientSecret) throw new SsoError("introspection verification requires TINA4_SSO_CLIENT_SECRET");
+        if (!Array.isArray(this.scopes) || !this.scopes.includes("openid")) throw new SsoError("TINA4_SSO_SCOPES must be a list containing openid");
+      }
+      async requestJson(url, form, bearer, basic = false) {
+        const headers = { Accept: "application/json" };
+        let body;
+        if (form) {
+          const parameters = new URLSearchParams();
+          for (const [key, value] of Object.entries(form)) parameters.set(key, String(value));
+          body = parameters.toString();
+          headers["Content-Type"] = "application/x-www-form-urlencoded";
+        }
+        if (bearer) headers.Authorization = `Bearer ${bearer}`;
+        if (basic) headers.Authorization = `Basic ${Buffer.from(`${this.clientId}:${this.clientSecret}`).toString("base64")}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        try {
+          const response = await fetch(url, { method: form ? "POST" : "GET", headers, body, signal: controller.signal });
+          if (!response.ok) throw new SsoError("OIDC provider request failed");
+          const result = await response.json();
+          if (!result || typeof result !== "object" || Array.isArray(result)) throw new SsoError("OIDC provider returned a non-object response");
+          return result;
+        } catch (error) {
+          if (error instanceof SsoError) throw error;
+          throw new SsoError("OIDC provider request failed");
+        } finally {
+          clearTimeout(timer);
+        }
+      }
+      async discover(force = false) {
+        if (Object.keys(this.metadata).length && !force) return { ...this.metadata };
+        const result = await this.requestJson(`${this.issuer}/.well-known/openid-configuration`);
+        if (result.issuer !== this.issuer) throw new SsoError("OIDC discovery issuer does not exactly match configuration");
+        const required = ["authorization_endpoint", "token_endpoint"];
+        if (this.verify === "introspection") required.push("introspection_endpoint");
+        for (const key of required) {
+          if (!result[key]) throw new SsoError(`OIDC discovery is missing ${key}`);
+          _Sso.secureUrl(result[key], key);
+        }
+        this.metadata = result;
+        return { ...result };
+      }
+      static safeReturn(value) {
+        if (!value || !value.startsWith("/") || value.startsWith("//") || value.includes("\\")) return "/";
+        return [...value].some((char) => char.charCodeAt(0) < 32) ? "/" : value;
+      }
+      session(value) {
+        return value?.session ?? value;
+      }
+      async login(requestOrSession, returnTo = "/") {
+        const session = this.session(requestOrSession);
+        if (!session) throw new SsoError("SSO login requires a Tina4 Session");
+        const state = randomBytes5(32).toString("base64url");
+        const nonce = randomBytes5(32).toString("base64url");
+        const verifier = randomBytes5(64).toString("base64url");
+        const challenge = createHash9("sha256").update(verifier).digest("base64url");
+        session.set(_Sso.PENDING_KEY, { state, nonce, verifier, return_to: _Sso.safeReturn(returnTo), created_at: Math.floor(Date.now() / 1e3) });
+        const metadata = await this.discover();
+        const query = new URLSearchParams({
+          client_id: this.clientId,
+          redirect_uri: this.redirectUri,
+          response_type: "code",
+          scope: this.scopes.join(" "),
+          state,
+          nonce,
+          code_challenge: challenge,
+          code_challenge_method: "S256"
+        });
+        return `${metadata.authorization_endpoint}?${query}`;
+      }
+      static equal(left, right) {
+        const a = Buffer.from(String(left ?? ""));
+        const b = Buffer.from(String(right ?? ""));
+        return a.length === b.length && timingSafeEqual3(a, b);
+      }
+      static jwtPayload(token) {
+        try {
+          return JSON.parse(Buffer.from(token.split(".")[1], "base64url").toString());
+        } catch {
+          throw new SsoError("provider returned an invalid ID token");
+        }
+      }
+      async introspect(accessToken) {
+        const metadata = await this.discover();
+        const result = await this.requestJson(metadata.introspection_endpoint, { token: accessToken, token_type_hint: "access_token" }, void 0, true);
+        if (result.active !== true || result.iss !== this.issuer) throw new SsoError("OIDC access token is inactive or has the wrong issuer");
+        const audience = result.aud ?? result.client_id;
+        const valid = (Array.isArray(audience) ? audience.includes(this.clientId) : audience === this.clientId) || result.client_id === this.clientId;
+        if (!valid) throw new SsoError("OIDC token audience mismatch");
+        return result;
+      }
+      claim(claims, configured, fallback) {
+        let value = claims;
+        for (const part of (configured ?? fallback).split(".")) value = value && typeof value === "object" ? value[part] : void 0;
+        return value;
+      }
+      normalize(claims) {
+        const subject = this.claim(claims, this.claimMap.subject, "sub");
+        const issuer = this.claim(claims, this.claimMap.issuer, "iss") ?? this.issuer;
+        if (!subject || issuer !== this.issuer) throw new SsoError("OIDC identity is missing a valid issuer or subject");
+        const roles = [...this.claim(claims, this.claimMap.roles, "realm_access.roles") ?? [], ...claims.resource_access?.[this.clientId]?.roles ?? []];
+        const groups = this.claim(claims, this.claimMap.groups, "groups") ?? [];
+        return {
+          issuer,
+          subject,
+          username: this.claim(claims, this.claimMap.username, "preferred_username") ?? null,
+          email: this.claim(claims, this.claimMap.email, "email") ?? null,
+          name: this.claim(claims, this.claimMap.name, "name") ?? null,
+          roles: [...new Set(roles.map(String))].sort(),
+          groups: [...new Set(groups.map(String))].sort()
+        };
+      }
+      async callback(requestOrSession, query) {
+        const session = this.session(requestOrSession);
+        const values = query ?? requestOrSession?.query ?? {};
+        const pending = session?.get(_Sso.PENDING_KEY);
+        session?.delete(_Sso.PENDING_KEY);
+        if (!pending || !values.code || !_Sso.equal(values.state, pending.state)) throw new SsoError("OIDC callback state is invalid or already consumed");
+        if (Math.floor(Date.now() / 1e3) - Number(pending.created_at ?? 0) > 600) throw new SsoError("OIDC callback state has expired");
+        const metadata = await this.discover();
+        const tokens = await this.requestJson(metadata.token_endpoint, {
+          grant_type: "authorization_code",
+          code: values.code,
+          redirect_uri: this.redirectUri,
+          client_id: this.clientId,
+          code_verifier: pending.verifier
+        }, void 0, Boolean(this.clientSecret));
+        if (!tokens.access_token || !tokens.id_token) throw new SsoError("OIDC token response is incomplete");
+        if (this.verify === "jwks") throw new SsoError("JWKS verification requires an installed cryptography capability");
+        const claims = await this.introspect(tokens.access_token);
+        if (!_Sso.equal(_Sso.jwtPayload(tokens.id_token).nonce, pending.nonce)) throw new SsoError("OIDC ID token nonce mismatch");
+        if (metadata.userinfo_endpoint) Object.assign(claims, await this.requestJson(metadata.userinfo_endpoint, void 0, tokens.access_token));
+        const identity = this.normalize(claims);
+        session.regenerate();
+        session.set(_Sso.SESSION_KEY, {
+          version: 1,
+          identity,
+          access_token: tokens.access_token,
+          refresh_token: tokens.refresh_token,
+          id_token: tokens.id_token,
+          expires_at: Math.floor(Date.now() / 1e3) + Number(tokens.expires_in ?? 0)
+        });
+        return { identity, return_to: _Sso.safeReturn(pending.return_to) };
+      }
+      identity(requestOrSession) {
+        const stored = this.session(requestOrSession)?.get(_Sso.SESSION_KEY);
+        const identity = stored?.identity ?? null;
+        if (identity && requestOrSession?.session) requestOrSession.user = identity;
+        return identity;
+      }
+      async refresh(requestOrSession) {
+        const session = this.session(requestOrSession);
+        const stored = session?.get(_Sso.SESSION_KEY);
+        if (!stored?.refresh_token) {
+          session?.delete(_Sso.SESSION_KEY);
+          throw new SsoError("OIDC session cannot be refreshed");
+        }
+        try {
+          const metadata = await this.discover();
+          const tokens = await this.requestJson(metadata.token_endpoint, {
+            grant_type: "refresh_token",
+            refresh_token: stored.refresh_token,
+            client_id: this.clientId
+          }, void 0, Boolean(this.clientSecret));
+          const claims = await this.introspect(tokens.access_token);
+          if (metadata.userinfo_endpoint) Object.assign(claims, await this.requestJson(metadata.userinfo_endpoint, void 0, tokens.access_token));
+          const identity = this.normalize(claims);
+          session.set(_Sso.SESSION_KEY, {
+            ...stored,
+            identity,
+            access_token: tokens.access_token,
+            refresh_token: tokens.refresh_token ?? stored.refresh_token,
+            id_token: tokens.id_token ?? stored.id_token,
+            expires_at: Math.floor(Date.now() / 1e3) + Number(tokens.expires_in ?? 0)
+          });
+          return identity;
+        } catch (error) {
+          session?.delete(_Sso.SESSION_KEY);
+          throw error;
+        }
+      }
+      async logout(requestOrSession, returnTo = "/") {
+        const session = this.session(requestOrSession);
+        const stored = session?.get(_Sso.SESSION_KEY);
+        session?.destroy();
+        const endpoint = (await this.discover()).end_session_endpoint;
+        const target = this.postLogoutRedirectUri ?? _Sso.safeReturn(returnTo);
+        if (!endpoint) return target;
+        const params = new URLSearchParams({ post_logout_redirect_uri: target, client_id: this.clientId });
+        if (stored?.id_token) params.set("id_token_hint", stored.id_token);
+        return `${endpoint}?${params}`;
+      }
+      static async mountConfigured(router) {
+        if (_Sso.mountedRouters.has(router) || !_Sso.configured()) return false;
+        const owned = /* @__PURE__ */ new Set(["GET /auth/login", "GET /auth/callback", "POST /auth/logout"]);
+        const collisions = router.getRoutes().map((route) => `${route.method} ${route.pattern}`).filter((route) => owned.has(route));
+        if (collisions.length) throw new SsoError(`SSO route collision: ${collisions.join(", ")}`);
+        const sso = await _Sso.fromIssuer();
+        router.get("/auth/login", async (req2, res) => res.redirect(await sso.login(req2, req2.query?.return_to ?? "/")));
+        router.get("/auth/callback", async (req2, res) => {
+          try {
+            return res.redirect((await sso.callback(req2)).return_to);
+          } catch (error) {
+            const message = error instanceof SsoError ? error.message : "OIDC callback failed";
+            return res.error("SSO_CALLBACK_FAILED", message, 400);
+          }
+        });
+        router.post("/auth/logout", async (req2, res) => res.redirect(await sso.logout(req2, req2.query?.return_to ?? "/")));
+        _Sso.mountedRouters.add(router);
+        return true;
+      }
+    };
+  }
+});
+
 // ../core/src/docsAutoDiscovery.ts
 var docsAutoDiscovery_exports = {};
 __export(docsAutoDiscovery_exports, {
@@ -23888,7 +24462,7 @@ var init_docsAutoDiscovery = __esm({
 
 // ../core/src/server.ts
 import { createServer as createServer2 } from "node:http";
-import { randomBytes as randomBytes5 } from "node:crypto";
+import { randomBytes as randomBytes6 } from "node:crypto";
 import { resolve as resolve14, dirname as dirname11, join as join24, relative as relative8 } from "node:path";
 import { existsSync as existsSync22, readdirSync as readdirSync14, readFileSync as readFileSync21, statSync as statSync15 } from "node:fs";
 import { isatty } from "node:tty";
@@ -24528,7 +25102,7 @@ async function renderDispatchError(err, req2, res, templatesDir) {
       }
     }
   }
-  const requestId = Log.getRequestId() ?? randomBytes5(4).toString("hex");
+  const requestId = Log.getRequestId() ?? randomBytes6(4).toString("hex");
   if (wantsJson(req2)) {
     const body = negotiatedErrorBody(500, "Internal Server Error", requestId);
     res.raw.writeHead(500, { "Content-Type": "application/json" });
@@ -24599,7 +25173,7 @@ function serveStaticAsset(ctx) {
   return false;
 }
 async function serveNotFound(ctx) {
-  const requestId = Log.getRequestId() ?? randomBytes5(4).toString("hex");
+  const requestId = Log.getRequestId() ?? randomBytes6(4).toString("hex");
   if (wantsJson(ctx.req)) {
     const body = negotiatedErrorBody(404, "Not Found", requestId);
     ctx.res.raw.writeHead(404, httpReason(404), { "Content-Type": "application/json" });
@@ -24719,7 +25293,7 @@ async function dispatchInner(ctx, rawReq, rawRes, requestId) {
   }
 }
 async function runDispatch(ctx, rawReq, rawRes) {
-  const requestId = Log.sanitizeRequestId(rawReq.headers["x-request-id"]) ?? randomBytes5(4).toString("hex");
+  const requestId = Log.sanitizeRequestId(rawReq.headers["x-request-id"]) ?? randomBytes6(4).toString("hex");
   if (!rawRes.headersSent) rawRes.setHeader("x-request-id", requestId);
   return Log.runWithRequestId(requestId, () => dispatchInner(ctx, rawReq, rawRes, requestId));
 }
@@ -24853,6 +25427,8 @@ ${reset2}
     console.log(`
   No routes directory found at ${routesDir}`);
   }
+  const { Sso: Sso2 } = await Promise.resolve().then(() => (init_sso(), sso_exports));
+  await Sso2.mountConfigured(router);
   if (attachCsrfFromEnv()) {
     console.log(`
   \x1B[36mCSRF\x1B[0m protection enabled (TINA4_CSRF)`);
@@ -25845,7 +26421,7 @@ var init_mqttMessage = __esm({
 // ../core/src/mqtt.ts
 import net2 from "node:net";
 import tls from "node:tls";
-import { randomBytes as randomBytes6 } from "node:crypto";
+import { randomBytes as randomBytes7 } from "node:crypto";
 import { existsSync as existsSync24, readFileSync as readFileSync22 } from "node:fs";
 var MqttError, MqttTimeoutError, CONNECT, CONNACK, PUBLISH, PUBACK, SUBSCRIBE, SUBACK, PINGREQ, PINGRESP, DISCONNECT, PROTOCOL_LEVEL, DEFAULT_PORT, DEFAULT_TLS_PORT, DEFAULT_URL, DEFAULT_KEEPALIVE, SUBSCRIPTION_REFUSED, MAX_REMAINING_LENGTH, QOS2_REFUSED_MESSAGE, CONNACK_RETURN_CODES, Mqtt;
 var init_mqtt = __esm({
@@ -25933,7 +26509,7 @@ var init_mqtt = __esm({
         this.caFile = options.caFile ?? (Env.str("TINA4_MQTT_CA_FILE") || null);
         this.tlsVerify = options.tlsVerify ?? Env.bool("TINA4_MQTT_TLS_VERIFY", true);
         let cid = options.clientId ?? (Env.str("TINA4_MQTT_CLIENT_ID") || null);
-        if (cid === null || cid === "") cid = "tina4-" + randomBytes6(8).toString("hex");
+        if (cid === null || cid === "") cid = "tina4-" + randomBytes7(8).toString("hex");
         this.clientId = cid;
         this.keepalive = options.keepalive ?? Env.int("TINA4_MQTT_KEEPALIVE", DEFAULT_KEEPALIVE);
         this.cleanSession = options.cleanSession ?? true;
@@ -26863,7 +27439,7 @@ var init_service = __esm({
 import http from "node:http";
 import https from "node:https";
 import { URL as URL2 } from "node:url";
-import { randomBytes as randomBytes7 } from "node:crypto";
+import { randomBytes as randomBytes8 } from "node:crypto";
 import { promises as fsp, createWriteStream } from "node:fs";
 import { basename as basename5 } from "node:path";
 import { pipeline } from "node:stream/promises";
@@ -27161,7 +27737,7 @@ var init_api = __esm({
           return { http_code: null, body: null, headers: {}, error: "upload requires filePath or fileBytes" };
         }
         const partContentType = guessContentType(uploadName);
-        const boundary = "----Tina4Boundary" + randomBytes7(16).toString("hex");
+        const boundary = "----Tina4Boundary" + randomBytes8(16).toString("hex");
         const bodyBuffer = buildMultipartBody(boundary, fieldName, uploadName, content, partContentType, extraFields);
         const contentType = `multipart/form-data; boundary=${boundary}`;
         return this.execute("POST", this.buildUrl(path8), bodyBuffer, contentType, headers);
@@ -31993,10 +32569,13 @@ __export(src_exports2, {
   RouteGroup: () => RouteGroup,
   RouteRef: () => RouteRef,
   Router: () => Router,
+  SSO: () => Sso,
   SafeString: () => SafeString2,
   SecurityHeadersMiddleware: () => SecurityHeadersMiddleware,
   ServiceRunner: () => ServiceRunner,
   Session: () => Session,
+  Sso: () => Sso,
+  SsoError: () => SsoError,
   TAKEOVER_KILLED: () => TAKEOVER_KILLED,
   TAKEOVER_NOTHING: () => TAKEOVER_NOTHING,
   TAKEOVER_REFUSALS: () => TAKEOVER_REFUSALS,
@@ -32233,6 +32812,7 @@ var init_src2 = __esm({
     init_htmlElement();
     init_errorOverlay();
     init_ai();
+    init_sso();
     init_aiClient();
     init_liteBackend();
     init_rabbitmqBackend();
@@ -33331,6 +33911,8 @@ function fieldTypeToPostgres(def) {
       return "TEXT";
     case "json":
       return "JSONB";
+    case "point":
+      return SQLTranslator.pointColumnType("postgres", def.srid ?? 4326);
     case "string":
       return def.maxLength ? `VARCHAR(${def.maxLength})` : "VARCHAR(255)";
     default:
@@ -37847,7 +38429,9 @@ function buildAddColumnSql(adapter, table2, colName, def) {
   return sql;
 }
 function mt(db) {
-  return engineOf(db) === "mysql" ? `\`${MIGRATION_TABLE}\`` : `"${MIGRATION_TABLE}"`;
+  const engine = engineOf(db);
+  if (engine === "firebird") return MIGRATION_TABLE;
+  return engine === "mysql" ? `\`${MIGRATION_TABLE}\`` : `"${MIGRATION_TABLE}"`;
 }
 function deriveDescription(name) {
   return name.replace(/^\d+_/, "").replace(/_/g, " ");
@@ -37870,9 +38454,9 @@ async function ensureMigrationTableOn(db) {
         id INTEGER NOT NULL PRIMARY KEY,
         migration_name VARCHAR(500) NOT NULL UNIQUE,
         description VARCHAR(500),
-        batch INTEGER NOT NULL DEFAULT 1,
+        batch INTEGER DEFAULT 1 NOT NULL,
         executed_at VARCHAR(50) NOT NULL,
-        passed INTEGER NOT NULL DEFAULT 1
+        passed INTEGER DEFAULT 1 NOT NULL
       )`);
     } else {
       const idCol = migrationIdColumn(db);
@@ -37969,7 +38553,7 @@ async function recordApplied(db, name, batch, passed = 1) {
       "SELECT GEN_ID(GEN_TINA4_MIGRATION_ID, 1) AS NEXT_ID FROM RDB$DATABASE"
     );
     insertCols.unshift("id");
-    values.unshift(rows[0]?.NEXT_ID ?? 1);
+    values.unshift(rows[0]?.next_id ?? 1);
   }
   const placeholders = insertCols.map(() => "?").join(", ");
   await adapterExecute(
@@ -38954,10 +39538,13 @@ var init_queryBuilder = __esm({
     "use strict";
     init_database();
     init_databaseResult();
+    init_point();
+    init_sqlTranslator();
     QueryBuilder = class _QueryBuilder {
       table;
       db;
       columns = ["*"];
+      selectParams = [];
       wheres = [];
       params = [];
       joinClauses = [];
@@ -38965,14 +39552,17 @@ var init_queryBuilder = __esm({
       havings = [];
       havingParams = [];
       orderByCols = [];
+      orderByParams = [];
+      primaryKey;
       limitVal;
       offsetVal;
       /**
        * Private constructor — use static factory methods.
        */
-      constructor(table2, db) {
+      constructor(table2, db, primaryKey) {
         this.table = table2;
         this.db = db;
+        this.primaryKey = primaryKey;
       }
       /**
        * Create a QueryBuilder for a table.
@@ -38981,8 +39571,8 @@ var init_queryBuilder = __esm({
        * @param db - Optional database adapter.
        * @returns A new QueryBuilder instance.
        */
-      static fromTable(tableName, db) {
-        return new _QueryBuilder(tableName, db);
+      static fromTable(tableName, db, primaryKey) {
+        return new _QueryBuilder(tableName, db, primaryKey);
       }
       /**
        * Set the columns to select.
@@ -38993,6 +39583,7 @@ var init_queryBuilder = __esm({
       select(...cols) {
         if (cols.length > 0) {
           this.columns = cols;
+          this.selectParams = [];
         }
         return this;
       }
@@ -39074,6 +39665,41 @@ var init_queryBuilder = __esm({
         this.orderByCols.push(expression);
         return this;
       }
+      withinDistance(column2, pointValue, radiusMetres, srid = DEFAULT_SRID) {
+        const radius = Number(radiusMetres);
+        if (!Number.isFinite(radius) || radius < 0) throw new RangeError("Spatial radius must be finite and greater than or equal to zero");
+        const point = Point.parse(pointValue, srid);
+        return this.where(SQLTranslator.withinDistance(this.engine(), column2, point.srid), [point.lon, point.lat, radius]);
+      }
+      intersects(column2, geometry, srid = DEFAULT_SRID) {
+        const [bound, form] = Point.geometryBinding(geometry, srid);
+        return this.where(SQLTranslator.intersects(this.engine(), column2, form, srid), [bound]);
+      }
+      bbox(column2, minLon, minLat, maxLon, maxLat, srid = DEFAULT_SRID) {
+        const values = [minLon, minLat, maxLon, maxLat].map(Number);
+        if (!values.every(Number.isFinite)) throw new TypeError("Bounding-box coordinates must be finite numbers");
+        const [west, south, east, north] = values;
+        new Point(west, south, srid);
+        new Point(east, north, srid);
+        if (west > east || south > north) throw new RangeError("Bounding box must be ordered west, south, east, north");
+        return this.where(SQLTranslator.bbox(this.engine(), column2, srid), values);
+      }
+      selectDistance(column2, pointValue, alias = "distance", srid = DEFAULT_SRID) {
+        const point = Point.parse(pointValue, srid);
+        this.columns.push(SQLTranslator.distanceAs(this.engine(), column2, alias, point.srid));
+        this.selectParams.push(point.lon, point.lat);
+        return this;
+      }
+      orderByDistance(column2, pointValue, direction = "ASC", srid = DEFAULT_SRID) {
+        const order = direction.toUpperCase();
+        if (order !== "ASC" && order !== "DESC") throw new TypeError("Distance order direction must be ASC or DESC");
+        if (!this.primaryKey) throw new Error("Stable spatial ordering needs a primary key; use BaseModel.query() or pass one to fromTable()");
+        const point = Point.parse(pointValue, srid);
+        this.orderByCols.push(`${SQLTranslator.distance(this.engine(), column2, point.srid)} ${order}`);
+        this.orderByParams.push(point.lon, point.lat);
+        this.orderByCols.push(`${SQLTranslator.spatialIdentifier(this.primaryKey, "primary key")} ASC`);
+        return this;
+      }
       /**
        * Set LIMIT and optional OFFSET.
        *
@@ -39139,7 +39765,7 @@ var init_queryBuilder = __esm({
       async get() {
         this.ensureDb();
         const sql = this.toSql();
-        const allParams = [...this.params, ...this.havingParams];
+        const allParams = [...this.selectParams, ...this.params, ...this.havingParams, ...this.orderByParams];
         const queryParams = allParams.length > 0 ? allParams : void 0;
         const rows = await adapterFetch(
           this.db,
@@ -39167,7 +39793,7 @@ var init_queryBuilder = __esm({
       async first() {
         this.ensureDb();
         const sql = this.toSql();
-        const allParams = [...this.params, ...this.havingParams];
+        const allParams = [...this.selectParams, ...this.params, ...this.havingParams, ...this.orderByParams];
         return adapterFetchOne(
           this.db,
           sql,
@@ -39182,9 +39808,18 @@ var init_queryBuilder = __esm({
       async count() {
         this.ensureDb();
         const original = this.columns;
+        const originalSelectParams = this.selectParams;
+        const originalOrder = this.orderByCols;
+        const originalOrderParams = this.orderByParams;
         this.columns = ["COUNT(*) as cnt"];
+        this.selectParams = [];
+        this.orderByCols = [];
+        this.orderByParams = [];
         const sql = this.toSql();
         this.columns = original;
+        this.selectParams = originalSelectParams;
+        this.orderByCols = originalOrder;
+        this.orderByParams = originalOrderParams;
         const allParams = [...this.params, ...this.havingParams];
         const row = await adapterFetchOne(
           this.db,
@@ -39369,6 +40004,10 @@ var init_queryBuilder = __esm({
           }
         }
       }
+      engine() {
+        this.ensureDb();
+        return this.db.getDatabaseType();
+      }
     };
   }
 });
@@ -39392,6 +40031,11 @@ function toDbFieldValue(def, value) {
   if (def?.type === "json" && value !== null && value !== void 0 && typeof value !== "string") {
     return JSON.stringify(value);
   }
+  if (def?.type === "point" && value !== null && value !== void 0) {
+    const point = Point.parse(value, def.srid ?? DEFAULT_SRID);
+    if (point.srid !== (def.srid ?? DEFAULT_SRID)) throw new TypeError(`Point field expects SRID ${def.srid ?? DEFAULT_SRID}; received ${point.srid}`);
+    return point.ewkt;
+  }
   return value;
 }
 function fromDbFieldValue(def, value) {
@@ -39402,6 +40046,11 @@ function fromDbFieldValue(def, value) {
       return value;
     }
   }
+  if (def?.type === "point" && value !== null && value !== void 0) {
+    const point = Point.parse(value, def.srid ?? DEFAULT_SRID);
+    if (point.srid !== (def.srid ?? DEFAULT_SRID)) throw new TypeError(`Point field expects SRID ${def.srid ?? DEFAULT_SRID}; received ${point.srid}`);
+    return point;
+  }
   return value;
 }
 function _pluralRelKeys() {
@@ -39437,6 +40086,7 @@ var init_baseModel = __esm({
     init_sqlite();
     init_sqlTranslator();
     init_src2();
+    init_point();
     _fkRegistry = /* @__PURE__ */ new Map();
     EAGER_IN_CHUNK = 500;
     modelQueryCache = new QueryCache({ defaultTtl: 0, maxSize: 500 });
@@ -39492,7 +40142,9 @@ var init_baseModel = __esm({
         for (const [name, def] of Object.entries(fields0)) {
           if (def.default === void 0) continue;
           let dv = typeof def.default === "function" ? def.default() : def.default;
-          if (dv !== null && typeof dv === "object") dv = structuredClone(dv);
+          if (def.type === "point" && dv !== null && dv !== void 0) {
+            dv = fromDbFieldValue(def, dv);
+          } else if (dv !== null && typeof dv === "object") dv = structuredClone(dv);
           this[name] = dv;
         }
         if (data) {
@@ -39594,7 +40246,7 @@ var init_baseModel = __esm({
        * @returns A QueryBuilder instance bound to this model's table and database.
        */
       static query() {
-        return QueryBuilder.fromTable(this.tableName, this.getDb());
+        return QueryBuilder.fromTable(this.tableName, this.getDb(), this.getPkColumn());
       }
       /**
        * Get the database adapter for this model.
@@ -40047,7 +40699,7 @@ var init_baseModel = __esm({
         for (const key of Object.keys(ModelClass.fields)) {
           if (this[key] !== void 0) {
             const outKey = case_ === "snake" ? ModelClass.fieldMapping[key] ?? key : key;
-            result[outKey] = this[key];
+            result[outKey] = this[key] instanceof Point ? this[key].geojson : this[key];
           }
         }
         if (ModelClass.softDelete && this.is_deleted !== void 0) {
@@ -40107,6 +40759,19 @@ var init_baseModel = __esm({
         }
         return result;
       }
+      toFeature(geometryField, include) {
+        const ModelClass = this.constructor;
+        const pointFields = Object.entries(ModelClass.fields).filter(([, def]) => def.type === "point").map(([name]) => name);
+        const field = geometryField ?? pointFields[0];
+        if (!field || !pointFields.includes(field)) throw new Error("toFeature() needs a declared point field");
+        const properties = this.toDict(include, "camel");
+        const geometry = properties[field] ?? null;
+        delete properties[field];
+        return { type: "Feature", geometry, properties };
+      }
+      static featureCollection(models, geometryField, include) {
+        return { type: "FeatureCollection", features: models.map((model) => model.toFeature(geometryField, include)) };
+      }
       /**
        * Convert to an associative object (alias for toDict).
        */
@@ -40157,7 +40822,10 @@ var init_baseModel = __esm({
        */
       static async createTable() {
         const db = this.getDb();
-        if (await adapterTableExists(db, this.tableName)) return true;
+        const pointFields = Object.entries(this.fields).filter(([, def]) => def.type === "point");
+        const engine = db.getDatabaseType();
+        if (pointFields.length > 0) SQLTranslator.requireSpatial(engine, "PointField");
+        if (await adapterTableExists(db, this.tableName)) return this.createSpatialIndexes(db, pointFields);
         if (typeof db.createTable === "function" || typeof db.createTableAsync === "function") {
           const mappedFields = {};
           for (const [fieldName, def] of Object.entries(this.fields)) {
@@ -40173,7 +40841,7 @@ var init_baseModel = __esm({
             mappedFields["is_deleted"] = { type: "integer", default: 0 };
           }
           await adapterCreateTable(db, this.tableName, mappedFields);
-          return true;
+          return this.createSpatialIndexes(db, pointFields);
         }
         const typeMap = {
           integer: "INTEGER",
@@ -40220,6 +40888,14 @@ var init_baseModel = __esm({
         }
         return true;
       }
+      static async createSpatialIndexes(db, fields) {
+        for (const [fieldName, def] of fields) {
+          SQLTranslator.pointColumnType(db.getDatabaseType(), def.srid ?? DEFAULT_SRID);
+          if (def.spatialIndex === false) continue;
+          await adapterExecute(db, SQLTranslator.spatialIndex(db.getDatabaseType(), this.tableName, this.getDbColumn(fieldName)));
+        }
+        return true;
+      }
       /**
        * Find a record by primary key or throw an error if not found.
        */
@@ -40291,15 +40967,25 @@ var init_baseModel = __esm({
       /**
        * Invalidate every cached query that touches this model's table.
        *
-       * Tag-scoped, NOT a wholesale flush: a cached JOIN on another model that reads
-       * this table is busted too (it carries this table's tag), while a query that
-       * never touches this table is left intact. Called after every ORM write
-       * (save/delete/forceDelete/restore) so a read-after-write never serves a
-       * stale/deleted row (CACHE-DEC-01).
+       * Tag-scoped in the ORM layer (a cached JOIN on another model that reads
+       * this table is busted too because it carries this table's tag; a query
+       * that never touches this table is left intact), then cascaded to the
+       * DB layer on this model's bound connection so an out-of-band write /
+       * deliberate refresh / race-with-another-process cannot leave stale rows
+       * in db.fetch()'s persistent cache. Called after every ORM write
+       * (save/delete/forceDelete/restore) so a read-after-write never serves
+       * a stale/deleted row (CACHE-DEC-01). PY-06-22 (3.13.105) added the
+       * DB-layer cascade -- previously the two cache layers disagreed under
+       * TINA4_AUTO_CACHING=true + TINA4_DB_CACHE=true.
        */
       static clearCache() {
         const ModelClass = this;
         modelQueryCache.clearTag((ModelClass.tableName ?? "").toLowerCase());
+        try {
+          const db = ModelClass.getDb();
+          if (typeof db?.cacheClear === "function") db.cacheClear();
+        } catch {
+        }
       }
       /**
        * Execute a raw SQL SELECT and return results as model instances.
@@ -41159,7 +41845,7 @@ var init_seeder = __esm({
 
 // src/docstore.ts
 import { DatabaseSync as DatabaseSync4 } from "node:sqlite";
-import { randomBytes as randomBytes8 } from "node:crypto";
+import { randomBytes as randomBytes9 } from "node:crypto";
 import { mkdirSync as mkdirSync19 } from "node:fs";
 import { dirname as dirname14, isAbsolute as isAbsolute6, join as join31 } from "node:path";
 function iso(d) {
@@ -41511,8 +42197,8 @@ var init_docstore = __esm({
     OID_RE = /^[0-9a-fA-F]{24}$/;
     ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})?$/;
     ObjectId = class _ObjectId {
-      static _counter = randomBytes8(3).readUIntBE(0, 3);
-      static _process = randomBytes8(5);
+      static _counter = randomBytes9(3).readUIntBE(0, 3);
+      static _process = randomBytes9(5);
       _bytes;
       constructor(oid) {
         if (oid === void 0 || oid === null) {
@@ -41940,7 +42626,7 @@ var init_attachment = __esm({
 });
 
 // src/realtime/storage.ts
-import { randomBytes as randomBytes9 } from "node:crypto";
+import { randomBytes as randomBytes10 } from "node:crypto";
 import { mkdirSync as mkdirSync20, readFileSync as readFileSync26, writeFileSync as writeFileSync17, unlinkSync as unlinkSync8, statSync as statSync18 } from "node:fs";
 import { resolve as resolve19, sep as sep5 } from "node:path";
 import { createRequire as createRequire8 } from "node:module";
@@ -41951,7 +42637,7 @@ function storageKey(filename = "") {
     const clean = raw.replace(UNSAFE, "").slice(0, 12);
     if (clean) ext = `.${clean}`;
   }
-  return `${randomBytes9(16).toString("hex")}${ext}`;
+  return `${randomBytes10(16).toString("hex")}${ext}`;
 }
 function selectStorage(storage) {
   if (storage) return storage;
@@ -42399,6 +43085,7 @@ __export(index_exports, {
   CachedDatabaseAdapter: () => CachedDatabaseAdapter,
   Cursor: () => Cursor,
   DEFAULT_DATABASE_CONNECT_TIMEOUT_SECONDS: () => DEFAULT_DATABASE_CONNECT_TIMEOUT_SECONDS,
+  DEFAULT_SRID: () => DEFAULT_SRID,
   Database: () => Database,
   DatabaseResult: () => DatabaseResult,
   DatabaseUrl: () => DatabaseUrl,
@@ -42414,6 +43101,7 @@ __export(index_exports, {
   NOT_REQUIRED_ON_ADAPTER: () => NOT_REQUIRED_ON_ADAPTER,
   ObjectId: () => ObjectId,
   OdbcAdapter: () => OdbcAdapter,
+  Point: () => Point,
   PostgresAdapter: () => PostgresAdapter,
   QueryBuilder: () => QueryBuilder,
   QueryCache: () => QueryCache,
@@ -42426,6 +43114,7 @@ __export(index_exports, {
   S3Storage: () => S3Storage,
   SQLTranslator: () => SQLTranslator,
   SQLiteAdapter: () => SQLiteAdapter,
+  SpatialNotSupportedError: () => SpatialNotSupportedError,
   SqliteCollection: () => SqliteCollection,
   SqliteDatabase: () => SqliteDatabase,
   adapterColumns: () => adapterColumns,
@@ -42519,6 +43208,7 @@ var init_index = __esm({
     init_baseModel();
     init_queryBuilder();
     init_sqlTranslator();
+    init_point();
     init_connectTimeout();
     init_cachedDatabase();
     init_fakeData2();
@@ -42542,6 +43232,7 @@ export {
   CachedDatabaseAdapter,
   Cursor,
   DEFAULT_DATABASE_CONNECT_TIMEOUT_SECONDS,
+  DEFAULT_SRID,
   Database,
   DatabaseResult,
   DatabaseUrl,
@@ -42557,6 +43248,7 @@ export {
   NOT_REQUIRED_ON_ADAPTER,
   ObjectId,
   OdbcAdapter,
+  Point,
   PostgresAdapter,
   QueryBuilder,
   QueryCache,
@@ -42569,6 +43261,7 @@ export {
   S3Storage,
   SQLTranslator,
   SQLiteAdapter,
+  SpatialNotSupportedError,
   SqliteCollection,
   SqliteDatabase,
   adapterColumns,