tina4-nodejs 3.13.103 → 3.13.105

package/packages/orm/src/adapters/postgres.ts

@@ -585,6 +585,8 @@ function fieldTypeToPostgres(def: FieldDefinition): string {
       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:

package/packages/orm/src/baseModel.ts

@@ -11,6 +11,7 @@ import { SQLiteAdapter } from "./adapters/sqlite.js";
 import { QueryCache, SQLTranslator } from "./sqlTranslator.js";
 import { Log } from "../../core/src/index.js";
 import type { DatabaseAdapter, FieldDefinition, RelationshipDefinition } from "./types.js";
+import { Point, DEFAULT_SRID, SpatialNotSupportedError } from "./point.js";
 
 /**
  * Convert a snake_case name to camelCase.
@@ -40,6 +41,11 @@ export function toDbFieldValue(def: FieldDefinition | undefined, value: unknown)
   if (def?.type === "json" && value !== null && value !== undefined && typeof value !== "string") {
     return JSON.stringify(value);
   }
+  if (def?.type === "point" && value !== null && value !== undefined) {
+    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;
 }
 
@@ -59,6 +65,11 @@ export function fromDbFieldValue(def: FieldDefinition | undefined, value: unknow
       return value; // leave the raw string in place
     }
   }
+  if (def?.type === "point" && value !== null && value !== undefined) {
+    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;
 }
 
@@ -231,7 +242,9 @@ export class BaseModel {
       // the same object (e.g. a json field `default: {}` — mutating a.meta must
       // not leak into b.meta). Parity with the Python master's per-instance
       // deepcopy and Ruby's Marshal round-trip.
-      if (dv !== null && typeof dv === "object") dv = structuredClone(dv);
+      if (def.type === "point" && dv !== null && dv !== undefined) {
+        dv = fromDbFieldValue(def, dv);
+      } else if (dv !== null && typeof dv === "object") dv = structuredClone(dv);
       this[name] = dv;
     }
 
@@ -356,7 +369,7 @@ export class BaseModel {
    * @returns A QueryBuilder instance bound to this model's table and database.
    */
   static query(): QueryBuilder {
-    return QueryBuilder.fromTable(this.tableName, this.getDb());
+    return QueryBuilder.fromTable(this.tableName, this.getDb(), this.getPkColumn());
   }
 
   /**
@@ -1019,7 +1032,7 @@ export class BaseModel {
     for (const key of Object.keys(ModelClass.fields)) {
       if (this[key] !== undefined) {
         const outKey = case_ === "snake" ? (ModelClass.fieldMapping[key] ?? key) : key;
-        result[outKey] = this[key];
+        result[outKey] = this[key] instanceof Point ? (this[key] as Point).geojson : this[key];
       }
     }
     // Include soft delete field
@@ -1100,6 +1113,21 @@ export class BaseModel {
     return result;
   }
 
+  toFeature(geometryField?: string, include?: string[]): Record<string, unknown> {
+    const ModelClass = this.constructor as typeof BaseModel;
+    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: BaseModel[], geometryField?: string, include?: string[]): Record<string, unknown> {
+    return { type: "FeatureCollection", features: models.map((model) => model.toFeature(geometryField, include)) };
+  }
+
   /**
    * Convert to an associative object (alias for toDict).
    */
@@ -1159,7 +1187,10 @@ export class BaseModel {
    */
   static async createTable(): Promise<boolean> {
     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);
 
     // Prefer the adapter's createTable — every adapter implements it and the
     // async variants (PostgreSQL/MySQL/MSSQL/Firebird) emit engine-aware DDL
@@ -1190,7 +1221,7 @@ export class BaseModel {
         mappedFields["is_deleted"] = { type: "integer", default: 0 };
       }
       await adapterCreateTable(db, this.tableName, mappedFields);
-      return true;
+      return this.createSpatialIndexes(db, pointFields);
     }
 
     // Fallback: build SQL manually (SQLite-only dialect — used only when an
@@ -1257,6 +1288,15 @@ export class BaseModel {
     return true;
   }
 
+  private static async createSpatialIndexes(db: DatabaseAdapter, fields: Array<[string, FieldDefinition]>): Promise<boolean> {
+    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.
    */
@@ -1345,15 +1385,28 @@ export class BaseModel {
   /**
    * 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(): void {
     const ModelClass = this as unknown as typeof BaseModel;
     modelQueryCache.clearTag((ModelClass.tableName ?? "").toLowerCase());
+    try {
+      const db: any = ModelClass.getDb();
+      if (typeof db?.cacheClear === "function") db.cacheClear();
+    } catch {
+      // A resolvable DB is not guaranteed at every clearCache() call site
+      // (module-import time in odd bootstraps, tests that mutate bindings);
+      // never let a cache-clear crash a save/delete.
+    }
   }
 
   /**

package/packages/orm/src/index.ts

@@ -56,6 +56,8 @@ export type { ValidationError } from "./validation.js";
 export { BaseModel, snakeToCamel, camelToSnake } from "./baseModel.js";
 export { QueryBuilder } from "./queryBuilder.js";
 export { SQLTranslator, QueryCache } from "./sqlTranslator.js";
+export { Point, SpatialNotSupportedError, DEFAULT_SRID } from "./point.js";
+export type { GeoJsonPoint } from "./point.js";
 export {
   DEFAULT_DATABASE_CONNECT_TIMEOUT_SECONDS,
   CONNECT_TIMEOUT_TOLERANCE_MS,

package/packages/orm/src/migration.ts

@@ -297,7 +297,16 @@ const MIGRATION_TABLE = "tina4_migration";
  * sql_mode, so they are always correct there.
  */
 function mt(db: DatabaseAdapter): string {
-  return engineOf(db) === "mysql" ? `\`${MIGRATION_TABLE}\`` : `"${MIGRATION_TABLE}"`;
+  const engine = engineOf(db);
+
+  // Firebird: leave it UNQUOTED so it folds to the upper-case TINA4_MIGRATION
+  // that the PHP and Python masters create. A quoted lower-case identifier is a
+  // DIFFERENT, case-sensitive table there, so a quoted spelling cannot see a
+  // ledger written by another Tina4 language — while tableExists() matches
+  // case-insensitively and reports it present, so the INSERT fails alone.
+  if (engine === "firebird") return MIGRATION_TABLE;
+
+  return engine === "mysql" ? `\`${MIGRATION_TABLE}\`` : `"${MIGRATION_TABLE}"`;
 }
 
 /**
@@ -347,9 +356,9 @@ async function ensureMigrationTableOn(db: DatabaseAdapter): Promise<void> {
         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 {
       // Engine-aware bookkeeping DDL (non-Firebird). Each engine spells an
@@ -517,11 +526,11 @@ async function recordApplied(
 
   if (isFirebirdAdapter(db)) {
     // Firebird: generate the id from the sequence.
-    const rows = await adapterQuery<{ NEXT_ID: number }>(db,
+    const rows = await adapterQuery<{ next_id: number }>(db,
       "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(", ");

package/packages/orm/src/point.ts

@@ -0,0 +1,105 @@
+export const DEFAULT_SRID = 4326;
+
+export class SpatialNotSupportedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SpatialNotSupportedError";
+  }
+}
+
+export type GeoJsonPoint = { type: "Point"; coordinates: [number, number] };
+
+/** Immutable SRID-aware longitude/latitude point (ADR-0057). */
+export class Point {
+  readonly lon: number;
+  readonly lat: number;
+  readonly srid: number;
+
+  constructor(lon: unknown, lat: unknown, srid: unknown = 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(): string { return `POINT(${formatCoordinate(this.lon)} ${formatCoordinate(this.lat)})`; }
+  get ewkt(): string { return `SRID=${this.srid};${this.wkt}`; }
+  get geojson(): GeoJsonPoint { return { type: "Point", coordinates: [this.lon, this.lat] }; }
+  toJSON(): GeoJsonPoint { return this.geojson; }
+  toArray(): [number, number] { return [this.lon, this.lat]; }
+
+  static parse(value: unknown, srid = DEFAULT_SRID): Point {
+    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 as Record<string, unknown>, 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: unknown, srid = DEFAULT_SRID): [string, "ewkt" | "geojson"] {
+    if (value instanceof Point || Array.isArray(value)) return [Point.parse(value, srid).ewkt, "ewkt"];
+    if (value && typeof value === "object") {
+      const candidate = value as Record<string, unknown>;
+      const geometry = String(candidate.type).toLowerCase() === "feature"
+        ? candidate.geometry as Record<string, unknown> : candidate;
+      const allowed = 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");
+  }
+
+  private static fromGeoJson(data: Record<string, unknown>, srid: number): Point {
+    const geometry = String(data.type).toLowerCase() === "feature"
+      ? data.geometry as Record<string, unknown> : 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);
+  }
+
+  private static fromWkb(raw: Uint8Array, srid: number): Point {
+    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 & 0x20000000) !== 0) {
+      srid = view.getUint32(5, little);
+      offset = 9;
+    }
+    const code = (typeWord & ~(0x20000000 | 0x40000000 | 0x80000000)) % 1000;
+    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);
+  }
+}
+
+function formatCoordinate(value: number): string {
+  return Object.is(value, -0) ? "0" : Number(value.toPrecision(15)).toString();
+}

package/packages/orm/src/queryBuilder.ts

@@ -20,11 +20,14 @@
 import type { DatabaseAdapter } from "./types.js";
 import { getAdapter, adapterFetch, adapterFetchOne, probeTotal } from "./database.js";
 import { DatabaseResult } from "./databaseResult.js";
+import { Point, DEFAULT_SRID } from "./point.js";
+import { SQLTranslator } from "./sqlTranslator.js";
 
 export class QueryBuilder {
   private table: string;
   private db: DatabaseAdapter | undefined;
   private columns: string[] = ["*"];
+  private selectParams: unknown[] = [];
   private wheres: [string, string][] = [];
   private params: unknown[] = [];
   private joinClauses: string[] = [];
@@ -32,15 +35,18 @@ export class QueryBuilder {
   private havings: string[] = [];
   private havingParams: unknown[] = [];
   private orderByCols: string[] = [];
+  private orderByParams: unknown[] = [];
+  private primaryKey: string | undefined;
   private limitVal: number | undefined;
   private offsetVal: number | undefined;
 
   /**
    * Private constructor — use static factory methods.
    */
-  private constructor(table: string, db?: DatabaseAdapter) {
+  private constructor(table: string, db?: DatabaseAdapter, primaryKey?: string) {
     this.table = table;
     this.db = db;
+    this.primaryKey = primaryKey;
   }
 
   /**
@@ -50,8 +56,8 @@ export class QueryBuilder {
    * @param db - Optional database adapter.
    * @returns A new QueryBuilder instance.
    */
-  static fromTable(tableName: string, db?: DatabaseAdapter): QueryBuilder {
-    return new QueryBuilder(tableName, db);
+  static fromTable(tableName: string, db?: DatabaseAdapter, primaryKey?: string): QueryBuilder {
+    return new QueryBuilder(tableName, db, primaryKey);
   }
 
   /**
@@ -63,6 +69,7 @@ export class QueryBuilder {
   select(...cols: string[]): QueryBuilder {
     if (cols.length > 0) {
       this.columns = cols;
+      this.selectParams = [];
     }
     return this;
   }
@@ -152,6 +159,46 @@ export class QueryBuilder {
     return this;
   }
 
+  withinDistance(column: string, pointValue: unknown, radiusMetres: number, srid = DEFAULT_SRID): QueryBuilder {
+    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(), column, point.srid), [point.lon, point.lat, radius]);
+  }
+
+  intersects(column: string, geometry: unknown, srid = DEFAULT_SRID): QueryBuilder {
+    const [bound, form] = Point.geometryBinding(geometry, srid);
+    return this.where(SQLTranslator.intersects(this.engine(), column, form, srid), [bound]);
+  }
+
+  bbox(column: string, minLon: unknown, minLat: unknown, maxLon: unknown, maxLat: unknown, srid = DEFAULT_SRID): QueryBuilder {
+    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(), column, srid), values);
+  }
+
+  selectDistance(column: string, pointValue: unknown, alias = "distance", srid = DEFAULT_SRID): QueryBuilder {
+    const point = Point.parse(pointValue, srid);
+    this.columns.push(SQLTranslator.distanceAs(this.engine(), column, alias, point.srid));
+    this.selectParams.push(point.lon, point.lat);
+    return this;
+  }
+
+  orderByDistance(column: string, pointValue: unknown, direction: "ASC" | "DESC" = "ASC", srid = DEFAULT_SRID): QueryBuilder {
+    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(), column, 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.
    *
@@ -225,7 +272,7 @@ export class QueryBuilder {
   async get(): Promise<DatabaseResult> {
     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 : undefined;
     const rows = await adapterFetch(
@@ -265,7 +312,7 @@ export class QueryBuilder {
   async first<T = Record<string, unknown>>(): Promise<T | null> {
     this.ensureDb();
     const sql = this.toSql();
-    const allParams = [...this.params, ...this.havingParams];
+    const allParams = [...this.selectParams, ...this.params, ...this.havingParams, ...this.orderByParams];
 
     return adapterFetchOne<T>(
       this.db!,
@@ -284,9 +331,18 @@ export class QueryBuilder {
 
     // Build a count query by replacing columns
     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];
 
@@ -544,4 +600,9 @@ export class QueryBuilder {
       }
     }
   }
+
+  private engine(): string {
+    this.ensureDb();
+    return this.db!.getDatabaseType();
+  }
 }

package/packages/orm/src/sqlTranslator.ts

@@ -20,7 +20,70 @@
 // ── SQL Translator ───────────────────────────────────────────
 
 import { DatabaseUrl } from "./databaseUrl.js";
+import { DEFAULT_SRID, SpatialNotSupportedError } from "./point.js";
 export class SQLTranslator {
+  private static readonly SPATIAL_ENGINES = new Set(["postgres", "postgresql"]);
+  private static readonly SPATIAL_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+
+  static requireSpatial(engine: string, feature: string): string {
+    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: string, what = "column"): string {
+    if (!SQLTranslator.SPATIAL_IDENTIFIER.test(name)) throw new TypeError(`Spatial ${what} is not a valid SQL identifier: ${name}`);
+    return name;
+  }
+
+  static pointColumnType(engine: string, srid = DEFAULT_SRID): string {
+    SQLTranslator.requireSpatial(engine, "PointField");
+    return `geography(Point,${srid})`;
+  }
+
+  static spatialIndex(engine: string, table: string, column: string): string {
+    SQLTranslator.requireSpatial(engine, "spatial index creation");
+    table = SQLTranslator.spatialIdentifier(table, "table");
+    column = SQLTranslator.spatialIdentifier(column);
+    return `CREATE INDEX IF NOT EXISTS ${table.replaceAll(".", "_")}_${column}_gist ON ${table} USING GIST (${column})`;
+  }
+
+  static pointLiteral(engine: string, srid = DEFAULT_SRID): string {
+    SQLTranslator.requireSpatial(engine, "spatial predicates");
+    return `ST_SetSRID(ST_MakePoint(?, ?), ${srid})::geography`;
+  }
+
+  static withinDistance(engine: string, column: string, srid = DEFAULT_SRID): string {
+    return `ST_DWithin(${SQLTranslator.spatialIdentifier(column)}, ${SQLTranslator.pointLiteral(engine, srid)}, ?)`;
+  }
+
+  static distance(engine: string, column: string, srid = DEFAULT_SRID): string {
+    return `ST_Distance(${SQLTranslator.spatialIdentifier(column)}, ${SQLTranslator.pointLiteral(engine, srid)})`;
+  }
+
+  static distanceAs(engine: string, column: string, alias: string, srid = DEFAULT_SRID): string {
+    return `${SQLTranslator.distance(engine, column, srid)} AS ${SQLTranslator.spatialIdentifier(alias, "result alias")}`;
+  }
+
+  static geometryLiteral(engine: string, form: "ewkt" | "geojson", srid = DEFAULT_SRID): string {
+    SQLTranslator.requireSpatial(engine, "spatial predicates");
+    return form === "ewkt" ? "ST_GeogFromText(?)" : `ST_SetSRID(ST_GeomFromGeoJSON(?), ${srid})::geography`;
+  }
+
+  static intersects(engine: string, column: string, form: "ewkt" | "geojson" = "ewkt", srid = DEFAULT_SRID): string {
+    return `ST_Intersects(${SQLTranslator.spatialIdentifier(column)}, ${SQLTranslator.geometryLiteral(engine, form, srid)})`;
+  }
+
+  static bbox(engine: string, column: string, srid = DEFAULT_SRID): string {
+    SQLTranslator.requireSpatial(engine, "bbox");
+    return `ST_Intersects(${SQLTranslator.spatialIdentifier(column)}, ST_MakeEnvelope(?, ?, ?, ?, ${srid})::geography)`;
+  }
   /**
    * Convert LIMIT/OFFSET to Firebird ROWS...TO syntax.
    *

package/packages/orm/src/types.ts

@@ -1,4 +1,4 @@
-export type FieldType = "string" | "integer" | "number" | "numeric" | "decimal" | "boolean" | "datetime" | "text" | "json" | "foreignKey";
+export type FieldType = "string" | "integer" | "number" | "numeric" | "decimal" | "boolean" | "datetime" | "text" | "json" | "foreignKey" | "point";
 
 export interface FieldDefinition {
   type: FieldType;
@@ -24,6 +24,10 @@ export interface FieldDefinition {
   references?: string;
   /** For type "foreignKey": override the has-many property name on the referenced model */
   relatedName?: string;
+  /** For type "point": spatial reference id (default WGS 84 / 4326). */
+  srid?: number;
+  /** For type "point": create the provider's spatial index (default true). */
+  spatialIndex?: boolean;
 }
 
 export interface RelationshipDefinition {

package/packages/swagger/dist/index.js

@@ -34,6 +34,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;
   }
@@ -215,7 +223,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" };
     }

package/packages/swagger/src/generator.ts

@@ -92,6 +92,14 @@ function resolveSecuritySchemes(): Record<string, Record<string, unknown>> {
     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" };
+  }
   // Registered schemes win (let an app override bearerAuth or add oauth2).
   for (const [name, def] of Object.entries(registeredSchemes)) {
     schemes[name] = def;
@@ -348,7 +356,9 @@ export function generate(
         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 as Record<string, unknown>;
       if (!responses["401"]) responses["401"] = { description: "Unauthorized" };
     }

package/types/core/src/index.d.ts

@@ -55,6 +55,8 @@ export { HtmlElement, htmlElement, addHtmlHelpers, Raw, SafeString } from "./htm
 export { renderErrorOverlay, isDebugMode } from "./errorOverlay.js";
 export { AI_TOOLS, isInstalled, showMenu, installSelected, installAll, generateContext } from "./ai.js";
 export type { AiTool } from "./ai.js";
+export { Sso, SSO, SsoError } from "./sso.js";
+export type { SsoOptions } from "./sso.js";
 export { Ai, AiError, AiConfigError, AiHTTPError, AiTimeoutError, AiParseError } from "./aiClient.js";
 export type { ChatResponse, AiMessage, AiChatOptions, AiEmbedOptions } from "./aiClient.js";
 export type { ImapMessage, ImapFullMessage, ImapAttachment } from "./messenger.js";