@lunora/do 1.0.0-alpha.37 → 1.0.0-alpha.39

package/dist/index.mjs

@@ -3,16 +3,17 @@ export { AGGREGATE_SQL_FUNCTION, aggregateSqlFunction, matchesStaticWhere, norma
 export { aggregateTableName, coerceAggregateNumber, encodeAggregateKey, foldAggregateTally, readAggregateValue } from './packem_shared/aggregateTableName-CxNqY1Sl.mjs';
 export { CountRlsUnsupportedError, mergeWhere, planAggregateLookup, selectIndexForAggregate, selectIndexForCount, selectIndexForGroupBy } from './packem_shared/CountRlsUnsupportedError-BGxj0pgS.mjs';
 export { AUTH_METRICS_BUCKETS_TABLE, AUTH_METRICS_BUCKET_MS, AUTH_METRICS_BUCKET_RETENTION, AUTH_METRICS_TABLE, ensureAuthMetricsTables, readAuthMetrics, recordAuthEvent } from './packem_shared/AUTH_METRICS_BUCKETS_TABLE-CiHHYeJi.mjs';
-export { c as createMetrics, a as createTracer, d as dispatchRootSpan } from './packem_shared/context-telemetry-DWfYDxCS.mjs';
-export { NotUniqueError, assertValidClientId, createShardCtxDb, normalizeIdStructurally } from './packem_shared/NotUniqueError-Ca21uDuU.mjs';
+export { c as createMetrics, a as createTracer, d as dispatchRootSpan } from './packem_shared/context-telemetry-CqcOObBl.mjs';
+export { NotUniqueError, assertValidClientId, createShardCtxDb, normalizeIdStructurally } from './packem_shared/NotUniqueError-DbtlWwcG.mjs';
 export { DATA_MIGRATION_STATE_TABLE, readMigrationStatus, runDataMigration } from './packem_shared/DATA_MIGRATION_STATE_TABLE-CYwBpyTr.mjs';
 export { SCAN_DEP, createDependencyTracker, depKey } from './packem_shared/SCAN_DEP-DLJF8dsj.mjs';
 export { renderSql } from './packem_shared/renderSql-D6eUcn2N.mjs';
 export { diffExternalSource } from './packem_shared/diffExternalSource-CovHfdyo.mjs';
-export { materializeExternalRows, materializeExternalRowsIncremental, readExternalSourceBaseline, runExternalSourceTick } from './packem_shared/materializeExternalRows-DlQWMlw_.mjs';
-export { isSoftDeleted, isSourceDue, liftSourceId, pullExternalSourceIncrementalTick, pullExternalSourceTick } from './packem_shared/isSoftDeleted-YLKR6JYw.mjs';
+export { materializeExternalRows, materializeExternalRowsIncremental, readExternalSourceBaseline, runExternalSourceTick } from './packem_shared/materializeExternalRows-BtEGs1Fv.mjs';
+export { isSoftDeleted, isSourceDue, liftSourceId, pullExternalSourceIncrementalTick, pullExternalSourceTick } from './packem_shared/isSoftDeleted-CFJmhjFP.mjs';
 export { FUNCTION_METRICS_BUCKETS_TABLE, FUNCTION_METRICS_BUCKET_MS, FUNCTION_METRICS_BUCKET_RETENTION, FUNCTION_METRICS_INDEX_TABLE, FUNCTION_METRICS_TABLE, ensureFunctionMetricsTables, readFunctionMetricBuckets, readFunctionMetricIndexHits, readFunctionMetrics, readFunctionMetricsTotals, recordFunctionMetric } from './packem_shared/FUNCTION_METRICS_BUCKETS_TABLE-UDNVD7FS.mjs';
-export { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, FLAGS_FUNCTION_PREFIX, RELATION_FUNCTION_PREFIX, facetColumn, listTables, readTablePage, selectMatchingIds } from './packem_shared/ADMIN_FUNCTIONS-DVk02KpP.mjs';
+export { GEO_DEFAULT_PRECISION, boundingBoxGeohashes, coveringGeohashes, encodeGeohash, haversineMeters, pointInBoundingBox } from './packem_shared/GEO_DEFAULT_PRECISION-BWnsNmpP.mjs';
+export { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, FLAGS_FUNCTION_PREFIX, RELATION_FUNCTION_PREFIX, facetColumn, listTables, readTablePage, selectMatchingIds } from './packem_shared/ADMIN_FUNCTIONS-CnZkbXH_.mjs';
 export { LogBuffer } from './packem_shared/LogBuffer-B_Ezju_N.mjs';
 export { MAIL_RETENTION, MAIL_TABLE, clearCapturedMail, ensureMailTable, readCapturedMail, recordCapturedMail } from './packem_shared/MAIL_RETENTION-CPpgl-dX.mjs';
 export { default as NotFoundError } from './packem_shared/NotFoundError-C70b9hLw.mjs';
@@ -20,23 +21,24 @@ export { armRestore, readBookmark } from './packem_shared/armRestore-4Px61hHS.mj
 export { applySelect, buildSeekWhere, decodeCursor, encodeCursor, normalizeOrderKeys, softDeleteScope } from './packem_shared/applySelect-WQY8m62C.mjs';
 export { RANK_TIEBREAK, encodePartitionKey, matchesRankStaticWhere, rankTableName, resolveRankPartition, sortColumnName } from './packem_shared/RANK_TIEBREAK-CXhdcA1o.mjs';
 export { ReactiveCache, reactiveCacheKey } from './packem_shared/ReactiveCache-DnSvbjil.mjs';
-export { serveRelationFanout } from './packem_shared/serveRelationFanout-FdrPflv1.mjs';
+export { serveRelationFanout } from './packem_shared/serveRelationFanout-k7HTh3CC.mjs';
 export { DEFAULT_MAX_RELATION_KEYS, assertFlatPredicate, assertShapeShardable, containsRelationPredicate, isRelationPredicate, resolveRelationPredicates } from './packem_shared/DEFAULT_MAX_RELATION_KEYS-BEan1CRD.mjs';
 export { applyOnDelete, fanOutScalarCounts, resolveWith, runRowValidators } from './packem_shared/applyOnDelete-BXSq3S70.mjs';
 export { RLS_UNWRAP_SYMBOL, RlsRequiredError, guardWriter } from './packem_shared/RLS_UNWRAP_SYMBOL-DTvHvRzY.mjs';
 export { buildFtsMatch, ftsTableName, scoreDocument, stringifySearchText, tokenizeSearch } from './packem_shared/buildFtsMatch-BLEMawrp.mjs';
 export { M as MIN_ADMIN_TOKEN_LENGTH, a as MIN_AUTH_SECRET_LENGTH, b as buildSecurityAudit } from './packem_shared/security-audit-CucgBice.mjs';
 export { SESSION_DO_TTL_DEFAULT, SessionDO } from './packem_shared/SESSION_DO_TTL_DEFAULT-BnSKgVO4.mjs';
-export { ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, ShardDO } from './packem_shared/ROOT_DO_SIZE_WARN_BYTES-CBlw_ir3.mjs';
+export { ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, ShardDO } from './packem_shared/ROOT_DO_SIZE_WARN_BYTES-CJGwzfoT.mjs';
 export { SHARD_REGISTRY_DO_NAME, ShardRegistryDO } from './packem_shared/SHARD_REGISTRY_DO_NAME-D99roc-r.mjs';
 export { MAX_SQL_ROWS, assertReadonly, runReadonlySql } from './packem_shared/MAX_SQL_ROWS-iFAA8FbD.mjs';
 export { createSystemReader } from './packem_shared/createSystemReader-D12eNH13.mjs';
 export { ConflictError } from './packem_shared/ConflictError-CLoq37xH.mjs';
 export { hasTrigger, runTriggers } from './packem_shared/hasTrigger-5N6_Fx0A.mjs';
+export { selectExpiredIds } from './packem_shared/selectExpiredIds-C5W29Upb.mjs';
 export { compileWhereSql } from './packem_shared/compileWhereSql-DE6yfRcQ.mjs';
 export { CDC_LOG_TABLE, applyCdcChanges, readCdcChanges, trimCdcChanges } from './packem_shared/CDC_LOG_TABLE-uwOJxJJZ.mjs';
-export { backfillAggregateIndexes, backfillRankIndexes } from './packem_shared/backfillAggregateIndexes-DDoT-UUI.mjs';
-export { runShardMigrations } from './packem_shared/runShardMigrations-DFzx6Qld.mjs';
+export { backfillAggregateIndexes, backfillRankIndexes } from './packem_shared/backfillAggregateIndexes-BGTwynwh.mjs';
+export { runShardMigrations } from './packem_shared/runShardMigrations-BVax6rYu.mjs';
 export { stableStringify } from './packem_shared/stableStringify-mC40mZts.mjs';
 export { stableWireKey } from './packem_shared/stableWireKey-DKuXO7T5.mjs';
 export { subscriptionListDeltas } from './packem_shared/subscriptionListDeltas-CT76bYny.mjs';

package/dist/packem_shared/{ADMIN_FUNCTIONS-DVk02KpP.mjs → ADMIN_FUNCTIONS-CnZkbXH_.mjs}

@@ -25,6 +25,7 @@ const ADMIN_FUNCTIONS = {
   getFanoutMetrics: "__lunora_admin__:getFanoutMetrics",
   getFunctionStats: "__lunora_admin__:getFunctionStats",
   getIssues: "__lunora_admin__:getIssues",
+  getMetricHistory: "__lunora_admin__:getMetricHistory",
   getMetricSeries: "__lunora_admin__:getMetricSeries",
   listSubscriptions: "__lunora_admin__:listSubscriptions",
   listTableIndexes: "__lunora_admin__:listTableIndexes",

package/dist/packem_shared/GEO_DEFAULT_PRECISION-BWnsNmpP.mjs

@@ -0,0 +1,114 @@
+const BASE32 = "0123456789bcdefghjkmnpqrstuvwxyz";
+const GEO_DEFAULT_PRECISION = 9;
+const EARTH_RADIUS_METERS = 63710088e-1;
+const CELL_WIDTH_METERS = [Number.POSITIVE_INFINITY, 5009400, 1252300, 156500, 39100, 4900, 1200, 152.9, 38.2, 4.77, 1.19, 0.149, 0.037];
+const clampPrecision = (precision) => Math.min(Math.max(Math.trunc(precision), 1), 12);
+const encodeGeohash = (point, precision) => {
+  const chars = clampPrecision(precision);
+  let latMin = -90;
+  let latMax = 90;
+  let lngMin = -180;
+  let lngMax = 180;
+  let hash = "";
+  let bit = 0;
+  let index = 0;
+  let even = true;
+  while (hash.length < chars) {
+    if (even) {
+      const mid = (lngMin + lngMax) / 2;
+      if (point.lng >= mid) {
+        index = index * 2 + 1;
+        lngMin = mid;
+      } else {
+        index *= 2;
+        lngMax = mid;
+      }
+    } else {
+      const mid = (latMin + latMax) / 2;
+      if (point.lat >= mid) {
+        index = index * 2 + 1;
+        latMin = mid;
+      } else {
+        index *= 2;
+        latMax = mid;
+      }
+    }
+    even = !even;
+    if (bit < 4) {
+      bit += 1;
+    } else {
+      hash += BASE32[index] ?? "0";
+      bit = 0;
+      index = 0;
+    }
+  }
+  return hash;
+};
+const haversineMeters = (a, b) => {
+  const toRadians = (degrees) => degrees * Math.PI / 180;
+  const dLat = toRadians(b.lat - a.lat);
+  const dLng = toRadians(b.lng - a.lng);
+  const lat1 = toRadians(a.lat);
+  const lat2 = toRadians(b.lat);
+  const h = Math.sin(dLat / 2) ** 2 + Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLng / 2) ** 2;
+  return 2 * EARTH_RADIUS_METERS * Math.asin(Math.min(1, Math.sqrt(h)));
+};
+const precisionForRadius = (radiusMeters) => {
+  for (let length = CELL_WIDTH_METERS.length - 1; length >= 1; length -= 1) {
+    const width = CELL_WIDTH_METERS[length];
+    if (width !== void 0 && width >= radiusMeters) {
+      return length;
+    }
+  }
+  return 1;
+};
+const NEIGHBOURS = {
+  east: ["bc01fg45238967deuvhjyznpkmstqrwx", "bc01fg45238967deuvhjyznpkmstqrwx"],
+  north: ["p0r21436x8zb9dcf5h7kjnmqesgutwvy", "bc01fg45238967deuvhjyznpkmstqrwx"],
+  south: ["14365h7k9dcfesgujnmqp0r2twvyx8zb", "238967debc01fg45kmstqrwxuvhjyznp"],
+  west: ["238967debc01fg45kmstqrwxuvhjyznp", "238967debc01fg45kmstqrwxuvhjyznp"]
+};
+const BORDERS = {
+  east: ["bcfguvyz", "prxz"],
+  north: ["prxz", "bcfguvyz"],
+  south: ["028b", "0145hjnp"],
+  west: ["0145hjnp", "028b"]
+};
+const adjacent = (hash, direction) => {
+  const lower = hash.toLowerCase();
+  const lastChar = lower.at(-1) ?? "";
+  let base = lower.slice(0, -1);
+  const type = lower.length % 2 === 0 ? 0 : 1;
+  if (BORDERS[direction][type].includes(lastChar) && base !== "") {
+    base = adjacent(base, direction);
+  }
+  return base + (BASE32[NEIGHBOURS[direction][type].indexOf(lastChar)] ?? "");
+};
+const coveringGeohashes = (center, radiusMeters) => {
+  const precision = precisionForRadius(Math.max(radiusMeters, 1));
+  const origin = encodeGeohash(center, precision);
+  const north = adjacent(origin, "north");
+  const south = adjacent(origin, "south");
+  const cells = [
+    origin,
+    north,
+    south,
+    adjacent(origin, "east"),
+    adjacent(origin, "west"),
+    adjacent(north, "east"),
+    adjacent(north, "west"),
+    adjacent(south, "east"),
+    adjacent(south, "west")
+  ];
+  return [...new Set(cells)];
+};
+const pointInBoundingBox = (point, box) => point.lat >= box.sw.lat && point.lat <= box.ne.lat && point.lng >= box.sw.lng && point.lng <= box.ne.lng;
+const boundingBoxCenter = (box) => {
+  return { lat: (box.sw.lat + box.ne.lat) / 2, lng: (box.sw.lng + box.ne.lng) / 2 };
+};
+const boundingBoxGeohashes = (box) => {
+  const center = boundingBoxCenter(box);
+  return coveringGeohashes(center, Math.max(haversineMeters(center, box.ne), 1));
+};
+
+export { GEO_DEFAULT_PRECISION, boundingBoxCenter, boundingBoxGeohashes, coveringGeohashes, encodeGeohash, haversineMeters, pointInBoundingBox };

package/dist/packem_shared/{NotUniqueError-Ca21uDuU.mjs → NotUniqueError-DbtlWwcG.mjs}

@@ -6,8 +6,9 @@ import { mergeWhere, CountRlsUnsupportedError, selectIndexForGroupBy, selectInde
 import { appendCdcChange } from './CDC_LOG_TABLE-uwOJxJJZ.mjs';
 export { CDC_LOG_TABLE, applyCdcChanges, bumpCdcEpoch, minCdcSeq, readCdcChanges, readCdcCursor, readCdcEpoch, trimCdcChanges } from './CDC_LOG_TABLE-uwOJxJJZ.mjs';
 import { r as runDrizzle } from './do-exec-5eQy5cEi.mjs';
-import { i as isFtsAvailable, D as DOC_COLUMN$1, r as rowToDocument, A as AGG_KEY, a as AGG_VALUE, b as AGG_COUNT, d as aggUpsertSql, j as jsonPathSql, q as quoteIdentifier, t as tableColumns, e as qualifiedJsonPathSql } from './do-sql-BCHCWtrD.mjs';
+import { i as isFtsAvailable, D as DOC_COLUMN$1, r as rowToDocument, A as AGG_KEY, a as AGG_VALUE, b as AGG_COUNT, g as geoTableName, d as aggUpsertSql, j as jsonPathSql, q as quoteIdentifier, t as tableColumns, e as qualifiedJsonPathSql } from './do-sql-CGAgiQUz.mjs';
 import { param } from './renderSql-D6eUcn2N.mjs';
+import { encodeGeohash, GEO_DEFAULT_PRECISION, coveringGeohashes, boundingBoxGeohashes, pointInBoundingBox, haversineMeters } from './GEO_DEFAULT_PRECISION-BWnsNmpP.mjs';
 import { sortColumnName, matchesRankStaticWhere, encodePartitionKey, rankTableName, resolveRankPartition, RANK_TIEBREAK } from './RANK_TIEBREAK-CXhdcA1o.mjs';
 import { stringifySearchText, ftsTableName, tokenizeSearch, buildFtsMatch, scoreDocument } from './buildFtsMatch-BLEMawrp.mjs';
 import { s as serializeSqlValue } from './serialize-sql-BlRUoiQe.mjs';
@@ -21,10 +22,10 @@ import { createSystemReader } from './createSystemReader-D12eNH13.mjs';
 import { ConflictError } from './ConflictError-CLoq37xH.mjs';
 import { runTriggers } from './hasTrigger-5N6_Fx0A.mjs';
 import { compileWhereSql } from './compileWhereSql-DE6yfRcQ.mjs';
-export { backfillAggregateIndexes, backfillRankIndexes } from './backfillAggregateIndexes-DDoT-UUI.mjs';
+export { backfillAggregateIndexes, backfillRankIndexes } from './backfillAggregateIndexes-BGTwynwh.mjs';
 export { C as CLIENT_WATERMARK_TABLE, G as GLOBAL_SHAPE_SNAPSHOT_TABLE, I as IDEMPOTENCY_TABLE, c as advanceClientWatermark, d as deleteGlobalShapeSnapshot, e as deleteGlobalShapeSnapshotsForConnection, m as migrateClientWatermark, b as migrateGlobalShapeSnapshot, r as readClientWatermark, f as readGlobalShapeSnapshot, g as readIdempotent, t as trimIdempotent, w as writeGlobalShapeSnapshot, h as writeIdempotent } from './ctx-db-idempotency-BdcNpvY4.mjs';
-export { runShardMigrations } from './runShardMigrations-DFzx6Qld.mjs';
-export { a as selectShapeMemberIds, s as selectShapeRows } from './ctx-db-shapes-Cz9dHyh1.mjs';
+export { runShardMigrations } from './runShardMigrations-BVax6rYu.mjs';
+export { a as selectShapeMemberIds, s as selectShapeRows } from './ctx-db-shapes-DTeFiHYS.mjs';
 
 const rankIndexFieldsUnchanged = (index, previous, next) => {
   const fields = [...index.partitionBy ?? [], ...index.sortBy.map((key) => key.field), ...index.where ? Object.keys(index.where) : []];
@@ -314,8 +315,28 @@ const createCompanionSync = (deps) => {
       }
     }
   };
+  const syncGeo = (tableName, id, document) => {
+    const indexes = schema.tables[tableName]?.geoIndexes;
+    if (!indexes || indexes.length === 0) {
+      return;
+    }
+    for (const index of indexes) {
+      const geoTable = geoTableName(tableName, index.name);
+      runDrizzle(sql$1, sql`DELETE FROM ${sql.identifier(geoTable)} WHERE ${sql.identifier("__id__")} = ${id}`);
+      const point = document?.[index.field];
+      if (point !== null && typeof point === "object" && typeof point.lat === "number" && typeof point.lng === "number") {
+        const { lat, lng } = point;
+        const hash = encodeGeohash({ lat, lng }, index.precision ?? GEO_DEFAULT_PRECISION);
+        runDrizzle(
+          sql$1,
+          sql`INSERT INTO ${sql.identifier(geoTable)} (${sql.identifier("__id__")}, ${sql.identifier("__geohash__")}, ${sql.identifier("__lat__")}, ${sql.identifier("__lng__")}) VALUES (${id}, ${hash}, ${lat}, ${lng})`
+        );
+      }
+    }
+  };
   const syncCompanionsForInsert = (tableName, id, document) => {
     syncSearch(tableName, id, document);
+    syncGeo(tableName, id, document);
     syncAggregates(tableName, void 0, document);
     syncRanks(tableName, id, void 0, document);
     invalidateCache(tableName, id);
@@ -329,6 +350,7 @@ const createCompanionSync = (deps) => {
     ensureRankBackfilledForTable,
     syncAggregates,
     syncCompanionsForInsert,
+    syncGeo,
     syncRanks,
     syncSearch
   };
@@ -599,6 +621,123 @@ const searchViaScan = (sql$1, tableName, search, limit, scopeCondition) => {
   const docs = scored.map((entry) => entry.doc);
   return typeof limit === "number" ? docs.slice(0, Math.max(0, Math.floor(limit))) : docs;
 };
+const createGeoBuilder = (geo, tableName) => {
+  const staged = geo;
+  const builder = {
+    near: (point, radiusMeters) => {
+      if (staged.within) {
+        throw new LunoraError("INTERNAL", `geo index "${staged.indexName}" on table "${tableName}": call .near() or .within(), not both`);
+      }
+      staged.near = { point: { lat: point.lat, lng: point.lng }, radiusMeters };
+      return builder;
+    },
+    within: (box) => {
+      if (staged.near) {
+        throw new LunoraError("INTERNAL", `geo index "${staged.indexName}" on table "${tableName}": call .near() or .within(), not both`);
+      }
+      staged.within = { ne: { lat: box.ne.lat, lng: box.ne.lng }, sw: { lat: box.sw.lat, lng: box.sw.lng } };
+      return builder;
+    }
+  };
+  return builder;
+};
+const readGeoPoint = (document, field) => {
+  const value = document[field];
+  if (value === null || typeof value !== "object") {
+    return void 0;
+  }
+  const { lat, lng } = value;
+  return typeof lat === "number" && typeof lng === "number" ? { lat, lng } : void 0;
+};
+const scoreGeoRow = (record, geo) => {
+  const point = readGeoPoint(record, geo.definition.field);
+  if (!point) {
+    return void 0;
+  }
+  const creationTime = typeof record["_creationTime"] === "number" ? record["_creationTime"] : 0;
+  if (geo.near) {
+    const distance = haversineMeters(geo.near.point, point);
+    return distance <= geo.near.radiusMeters ? { creationTime, distance } : void 0;
+  }
+  return pointInBoundingBox(point, geo.within) ? { creationTime, distance: 0 } : void 0;
+};
+const runGeoFetch = (sql$1, tableName, geo, limit, scopeCondition) => {
+  if (!geo.near && !geo.within) {
+    throw new LunoraError("INTERNAL", `geo index "${geo.indexName}" on table "${tableName}": call .near(point, radius) or .within(box)`);
+  }
+  const prefixes = geo.near ? coveringGeohashes(geo.near.point, geo.near.radiusMeters) : boundingBoxGeohashes(geo.within);
+  const geoTable = geoTableName(tableName, geo.indexName);
+  const prefixClauses = prefixes.map(
+    (prefix) => sql`(g.${sql.identifier("__geohash__")} >= ${prefix} AND g.${sql.identifier("__geohash__")} < ${`${prefix}{`})`
+  );
+  const whereClauses = [sql`(${sql.join(prefixClauses, sql` OR `)})`];
+  if (scopeCondition) {
+    whereClauses.push(scopeCondition);
+  }
+  const query = sql`SELECT m.id, m._creationTime, m.${sql.identifier(DOC_COLUMN$1)} FROM ${sql.identifier(geoTable)} g JOIN ${sql.identifier(tableName)} m ON m.id = g.${sql.identifier("__id__")} WHERE ${sql.join(whereClauses, sql` AND `)}`;
+  const rows = runDrizzle(sql$1, query).toArray();
+  const scored = [];
+  for (const row of rows) {
+    const record = rowToDocument(row);
+    const score = record ? scoreGeoRow(record, geo) : void 0;
+    if (record && score) {
+      scored.push({ creationTime: score.creationTime, distance: score.distance, doc: record });
+    }
+  }
+  scored.sort((a, b) => a.distance - b.distance || b.creationTime - a.creationTime);
+  const docs = scored.map((entry) => entry.doc);
+  return typeof limit === "number" ? docs.slice(0, Math.max(0, Math.floor(limit))) : docs;
+};
+const runGeoTerminal = (sql, tableName, stage, scopeCondition, limit) => {
+  const { geo } = stage;
+  if (!geo) {
+    throw new LunoraError("INTERNAL", "runGeoTerminal called without a staged geo query");
+  }
+  const filtered = stage.inMemoryFilters.length > 0;
+  const docs = runGeoFetch(sql, tableName, geo, filtered ? void 0 : limit, scopeCondition);
+  if (!filtered) {
+    return docs;
+  }
+  const result = [];
+  for (const record of docs) {
+    if (stage.inMemoryFilters.every((predicate) => predicate(record))) {
+      result.push(record);
+      if (typeof limit === "number" && result.length >= limit) {
+        break;
+      }
+    }
+  }
+  return result;
+};
+const runPlainFetch = (sql$1, tableName, stage, scopeCondition, orderClause, limit) => {
+  const whereClauses = [];
+  for (const condition of stage.sqlConditions) {
+    whereClauses.push(sql`${jsonPathSql(condition.field)} ${sql.raw(condition.comparator)} ${serializeSqlValue(condition.value)}`);
+  }
+  if (scopeCondition) {
+    whereClauses.push(scopeCondition);
+  }
+  let query = sql`SELECT id, _creationTime, ${sql.identifier(DOC_COLUMN$1)} FROM ${sql.identifier(tableName)}`;
+  if (whereClauses.length > 0) {
+    query = sql`${query} WHERE ${sql.join(whereClauses, sql` AND `)}`;
+  }
+  query = sql`${query} ORDER BY ${orderClause}`;
+  if (typeof limit === "number" && stage.inMemoryFilters.length === 0) {
+    query = sql`${query} LIMIT ${sql.raw(String(Math.max(0, Math.floor(limit))))}`;
+  }
+  const rows = runDrizzle(sql$1, query).toArray();
+  const docs = [];
+  for (const row of rows) {
+    const record = rowToDocument(row);
+    if (record && stage.inMemoryFilters.every((predicate) => predicate(record))) {
+      docs.push(record);
+      if (typeof limit === "number" && docs.length >= limit) {
+        break;
+      }
+    }
+  }
+  return docs;
+};
 const doWhereSqlStrategy = { fieldRef: jsonPathSql, serialize: serializeSqlValue };
 const makeRelationExistsSqlStrategy = (onRead) => {
   let aliasCounter = 0;
@@ -774,36 +913,10 @@ const buildReader = (sql$1, schema, tableName, onIndexUse = () => void 0) => {
     if (stage.search) {
       return runSearchFetch(limit);
     }
-    const whereClauses = [];
-    for (const condition of stage.sqlConditions) {
-      whereClauses.push(sql`${jsonPathSql(condition.field)} ${sql.raw(condition.comparator)} ${serializeSqlValue(condition.value)}`);
-    }
-    if (scopeCondition) {
-      whereClauses.push(scopeCondition);
+    if (stage.geo) {
+      return runGeoTerminal(sql$1, tableName, stage, scopeCondition, limit);
     }
-    let query = sql`SELECT id, _creationTime, ${sql.identifier(DOC_COLUMN$1)} FROM ${sql.identifier(tableName)}`;
-    if (whereClauses.length > 0) {
-      query = sql`${query} WHERE ${sql.join(whereClauses, sql` AND `)}`;
-    }
-    query = sql`${query} ORDER BY ${buildOrderClause()}`;
-    if (typeof limit === "number" && stage.inMemoryFilters.length === 0) {
-      query = sql`${query} LIMIT ${sql.raw(String(Math.max(0, Math.floor(limit))))}`;
-    }
-    const rows = runDrizzle(sql$1, query).toArray();
-    const docs = [];
-    for (const row of rows) {
-      const record = rowToDocument(row);
-      if (!record) {
-        continue;
-      }
-      if (stage.inMemoryFilters.every((predicate) => predicate(record))) {
-        docs.push(record);
-        if (typeof limit === "number" && docs.length >= limit) {
-          break;
-        }
-      }
-    }
-    return docs;
+    return runPlainFetch(sql$1, tableName, stage, scopeCondition, buildOrderClause(), limit);
   };
   const reader = {
     // eslint-disable-next-line @typescript-eslint/require-await -- TableReaderLike returns Promises (the D1 twin awaits real I/O); the DO impl is synchronous over local SQLite
@@ -828,6 +941,9 @@ const buildReader = (sql$1, schema, tableName, onIndexUse = () => void 0) => {
       if (stage.search) {
         throw new LunoraError("INTERNAL", "pagination is not supported on search queries; use .take(n) or .collect()");
       }
+      if (stage.geo) {
+        throw new LunoraError("INTERNAL", "pagination is not supported on geo queries; use .take(n) or .collect()");
+      }
       return paginateStage(sql$1, tableName, stage, options, scopeCondition);
     },
     // eslint-disable-next-line @typescript-eslint/require-await -- TableReaderLike returns Promises (the D1 twin awaits real I/O); the DO impl is synchronous over local SQLite
@@ -842,6 +958,20 @@ const buildReader = (sql$1, schema, tableName, onIndexUse = () => void 0) => {
       }
       return rows[0] ?? null;
     },
+    withGeoIndex(indexName, build) {
+      const definition = (tableDefinition.geoIndexes ?? []).find((index) => index.name === indexName);
+      if (!definition) {
+        throw new LunoraError("INTERNAL", `unknown geo index "${indexName}" on table "${tableName}"`);
+      }
+      onIndexUse(tableName, indexName, "geo");
+      const geoStage = { definition, indexName };
+      stage.geo = geoStage;
+      build(createGeoBuilder(geoStage, tableName));
+      if (!geoStage.near && !geoStage.within) {
+        throw new LunoraError("INTERNAL", `geo index "${indexName}" on table "${tableName}" requires a .near(point, radius) or .within(box) call`);
+      }
+      return reader;
+    },
     withIndex(indexName, range) {
       const definition = tableDefinition.indexes.find((index) => index.name === indexName);
       if (!definition) {
@@ -1090,6 +1220,7 @@ const createShardCtxDb = (options) => {
     ensureRankBackfilledForTable,
     syncAggregates,
     syncCompanionsForInsert,
+    syncGeo,
     syncRanks,
     syncSearch
   } = createCompanionSync({
@@ -1291,6 +1422,7 @@ const createShardCtxDb = (options) => {
           sql`UPDATE ${sql.identifier(tableName)} SET ${sql.identifier(DOC_COLUMN$1)} = ${JSON.stringify(merged)} WHERE id = ${id} AND ${sql.identifier(DOC_COLUMN$1)} = ${existingJson}`
         );
         syncSearch(tableName, id, merged);
+        syncGeo(tableName, id, void 0);
         syncAggregates(tableName, existing, merged);
         syncRanks(tableName, id, existing, void 0);
         cache?.invalidate(tableName, id);
@@ -1308,6 +1440,7 @@ const createShardCtxDb = (options) => {
         sql`DELETE FROM ${sql.identifier(tableName)} WHERE id = ${id} AND ${sql.identifier(DOC_COLUMN$1)} = ${existingJson}`
       );
       syncSearch(tableName, id, void 0);
+      syncGeo(tableName, id, void 0);
       syncAggregates(tableName, existing, void 0);
       syncRanks(tableName, id, existing, void 0);
       cache?.invalidate(tableName, id);
@@ -1682,6 +1815,7 @@ const createShardCtxDb = (options) => {
         sql`UPDATE ${sql.identifier(tableName)} SET ${sql.identifier(DOC_COLUMN$1)} = ${JSON.stringify(merged)} WHERE id = ${id} AND ${sql.identifier(DOC_COLUMN$1)} = ${existingJson}`
       );
       syncSearch(tableName, id, merged);
+      syncGeo(tableName, id, merged);
       syncAggregates(tableName, existing, merged);
       syncRanks(tableName, id, existing, merged);
       cache?.invalidate(tableName, id);
@@ -1878,6 +2012,7 @@ const createShardCtxDb = (options) => {
         sql`UPDATE ${sql.identifier(tableName)} SET _creationTime = ${creationTime}, ${sql.identifier(DOC_COLUMN$1)} = ${JSON.stringify(replaced)} WHERE id = ${id} AND ${sql.identifier(DOC_COLUMN$1)} = ${existingJson}`
       );
       syncSearch(tableName, id, replaced);
+      syncGeo(tableName, id, replaced);
       syncAggregates(tableName, previous, replaced);
       syncRanks(tableName, id, previous, replaced);
       cache?.invalidate(tableName, id);