@atscript/db 0.1.103 → 0.1.104

package/dist/{db-readable-mhPp-MPv.d.cts → db-readable-BepVc21V.d.cts}

@@ -55,6 +55,14 @@ interface TGenericLogger {
 declare const NoopLogger: TGenericLogger;
 //#endregion
 //#region src/table/table-metadata.d.ts
+/** Returns true if the annotated type IS the `db.geoPoint` primitive (tag-based). */
+declare function isGeoPointType(fieldType: TAtscriptAnnotatedType): boolean;
+/**
+ * Returns true if the annotated type is acceptable for `@db.index.geo`:
+ * the `db.geoPoint` primitive or a structurally identical `number[]`
+ * (excluding `db.vector`, which is semantically an embedding).
+ */
+declare function isGeoIndexableType(fieldType: TAtscriptAnnotatedType): boolean;
 /**
  * Computed metadata for a database table or view.
  *
@@ -87,6 +95,8 @@ declare class TableMetadata {
   versionField?: string;
   /** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
   quantityRefByField: Map<string, string>;
+  /** Logical paths annotated with `@db.encrypted` — stored as one opaque ciphertext column. */
+  encryptedFields: Set<string>;
   pathToPhysical: Map<string, string>;
   physicalToPath: Map<string, string>;
   flattenedParents: Set<string>;
@@ -140,6 +150,14 @@ declare class TableMetadata {
    * Scans `@db.*` and `@meta.id` annotations on a field during flattening.
    */
   private _scanGenericAnnotations;
+  /**
+   * Build-time diagnostics for `@db.encrypted` (§6 of the field-encryption
+   * spec). Mirrors the compile-time AnnotationSpec validation so models built
+   * from pre-compiled types still fail fast.
+   */
+  private _validateEncryptedField;
+  /** Build-time diagnostics for `@db.index.geo` (§3 of the geo-index spec). */
+  private _validateGeoIndexField;
   private _addIndexField;
   /**
    * Classifies each field as column, flattened, json, or parent-object.
@@ -216,9 +234,13 @@ interface TRelationInfo {
 interface TFieldMeta {
   sortable: boolean;
   filterable: boolean;
+  /** Present (true) when the field is `@db.encrypted` — stored as ciphertext at rest. */
+  encrypted?: boolean;
+  /** Present (true) when the field carries a `@db.index.geo` geospatial index. */
+  geo?: boolean;
 }
 /** Built-in CRUD operation names; map 1:1 to public method names. */
-type TCrudOp = "query" | "pages" | "one" | "insert" | "update" | "replace" | "remove";
+type TCrudOp = "query" | "pages" | "one" | "geo" | "insert" | "update" | "replace" | "remove";
 /**
  * CRUD permissions advertised in `/meta`. Key absent → operation is denied or
  * not exposed. Key present → operation is allowed; the `string[]` value is the
@@ -230,6 +252,8 @@ type TCrudPermissions = Partial<Record<TCrudOp, string[]>>;
 interface TMetaResponse {
   searchable: boolean;
   vectorSearchable: boolean;
+  /** Whether the adapter supports `geoSearch()` AND the table declares a geo index. */
+  geoSearchable?: boolean;
   searchIndexes: TSearchIndexInfo[];
   primaryKeys: string[];
   preferredId: string[];
@@ -330,7 +354,7 @@ interface TDbUpdateResult {
 interface TDbDeleteResult {
   deletedCount: number;
 }
-type TDbIndexType = "plain" | "unique" | "fulltext";
+type TDbIndexType = "plain" | "unique" | "fulltext" | "geo";
 interface TDbIndexField {
   name: string;
   sort: "asc" | "desc";
@@ -436,6 +460,19 @@ interface TDbFieldMeta {
    * Undefined for non-FK fields or when the target cannot be resolved.
    */
   fkTargetField?: TDbFieldMeta;
+  /**
+   * `@db.encrypted` — the value is AES-256-GCM encrypted by the core layer
+   * before reaching the adapter. Adapters must map the column to an unbounded
+   * text type and veto filtering/sorting (`canFilterField`/`canSortField`).
+   * The descriptor's `designType` is forced to `'string'` (ciphertext envelope);
+   * the declared type stays available via `type` for validation.
+   */
+  encrypted?: boolean;
+  /**
+   * The field's declared type is the `db.geoPoint` primitive (`[lng, lat]` tuple).
+   * Adapters map this to their native geo storage (e.g. MongoDB GeoJSON Point).
+   */
+  isGeoPoint?: boolean;
 }
 interface TValueFormatterPair {
   /** Converts a JS value to storage representation (write + filter paths). */
@@ -906,6 +943,14 @@ declare abstract class BaseDbAdapter {
     dropIndex(name: string): Promise<void>;
     prefix?: string;
     shouldSkipType?(type: TDbIndex["type"]): boolean;
+    /**
+     * Index types declared on the model but not supported by this adapter —
+     * warns and skips (models stay portable; sync never errors on these).
+     */
+    warnUnsupportedTypes?: {
+      adapter: string;
+      types: ReadonlyArray<TDbIndex["type"]>;
+    };
   }): Promise<void>;
   /**
    * Returns available search indexes for this adapter.
@@ -960,6 +1005,32 @@ declare abstract class BaseDbAdapter {
     data: Array<Record<string, unknown>>;
     count: number;
   }>;
+  /**
+   * Whether this adapter supports geospatial search (`geoSearch()` and the
+   * `$geoWithin` filter operator). Override in adapters that do (MongoDB in v1).
+   */
+  isGeoSearchable(): boolean;
+  /**
+   * Distance-ranked geospatial search. Results sorted by distance ascending;
+   * each row carries a `$distance` field (meters from the query point).
+   * `$maxDistance` / `$minDistance` (meters) ride in `query.controls`.
+   *
+   * @param point - `[lng, lat]` query point (GeoJSON coordinate order).
+   * @param query - Filter, select, skip/limit, $maxDistance/$minDistance.
+   * @param indexName - Optional geo index to target (multi-geo documents).
+   */
+  geoSearch(_point: [number, number], _query: DbQuery, _indexName?: string): Promise<Array<Record<string, unknown>>>;
+  /**
+   * Distance-ranked geospatial search with count (for paginated results).
+   *
+   * @param point - `[lng, lat]` query point (GeoJSON coordinate order).
+   * @param query - Filter, select, skip/limit, $maxDistance/$minDistance.
+   * @param indexName - Optional geo index to target (multi-geo documents).
+   */
+  geoSearchWithCount(_point: [number, number], _query: DbQuery, _indexName?: string): Promise<{
+    data: Array<Record<string, unknown>>;
+    count: number;
+  }>;
   /**
    * Fetches records and total count in one call.
    * Default: two parallel calls. Adapters may override for single-query optimization.
@@ -1207,6 +1278,66 @@ declare class DocumentFieldMapper extends FieldMappingStrategy {
   translatePatchKeys(update: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
 }
 //#endregion
+//#region src/encryption.d.ts
+/**
+ * Configuration for field-level encryption at rest (`@db.encrypted`).
+ * Passed to `DbSpace` via the options bag.
+ */
+interface TDbEncryptionOptions {
+  /** Key used for all new writes. */
+  defaultKeyId: string;
+  /**
+   * Key registry: keyId → 32-byte key (Buffer, or base64/hex/utf8 string).
+   * Decryption looks keys up by the keyId recorded in each value's envelope,
+   * so old keys stay in the registry for as long as data encrypted with them exists.
+   */
+  keys?: Record<string, string | Buffer>;
+  /**
+   * Alternative/supplement to `keys`: async resolver (KMS, Vault, env indirection).
+   * Called once per keyId, result cached for the process lifetime.
+   */
+  resolveKey?: (keyId: string) => Promise<string | Buffer> | string | Buffer;
+  /**
+   * What to do when a stored value is NOT a valid envelope (pre-existing
+   * plaintext rows, e.g. when @db.encrypted is added to a live column).
+   *  - 'error' (default): fail the read with DbError("ENC_NOT_ENCRYPTED")
+   *  - 'passthrough': return the raw value as-is (migration window mode);
+   *    the value gets encrypted on its next write.
+   */
+  onUnencrypted?: "error" | "passthrough";
+}
+/** Decryption context — carried into error messages (never the key itself). */
+interface TDecryptContext {
+  table?: string;
+  field?: string;
+}
+/**
+ * AES-256-GCM envelope encryption service for `@db.encrypted` fields.
+ *
+ * Owned by `DbSpace` and shared across all tables in the space. Values are
+ * `JSON.stringify`'d before encryption (type-exact round-trips) and stored as
+ * a single ASCII envelope string: `aes1$<keyId>$<iv>$<tag>$<ciphertext>`.
+ *
+ * Key material is validated eagerly at construction (`ENC_KEY_INVALID`);
+ * `resolveKey` lookups are cached per keyId for the process lifetime.
+ */
+declare class DbEncryption {
+  readonly defaultKeyId: string;
+  readonly onUnencrypted: "error" | "passthrough";
+  private readonly _keys;
+  private readonly _resolveKey?;
+  private readonly _resolved;
+  constructor(options: TDbEncryptionOptions);
+  /** True when `value` looks like an encryption envelope produced by this service. */
+  isEnvelope(value: unknown): value is string;
+  /** Encrypts a JSON-serializable value into an envelope string using the default key. */
+  encrypt(value: unknown): Promise<string>;
+  /** Decrypts an envelope string back into its plaintext value. */
+  decrypt(envelope: string, ctx?: TDecryptContext): Promise<unknown>;
+  private _decryptFailed;
+  private _getKey;
+}
+//#endregion
 //#region src/table/db-readable.d.ts
 /**
  * Extracts nav prop names from a query's `$with` array.
@@ -1266,8 +1397,16 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   /** Strategy for mapping between logical field shapes and physical storage. */
   protected readonly _fieldMapper: FieldMappingStrategy;
   protected _writeTableResolver?: TWriteTableResolver;
+  /** Encryption service for `@db.encrypted` fields — set by `DbSpace` from its options. */
+  protected _encryption?: DbEncryption;
   private _metaIdPhysical;
   constructor(_type: T, adapter: A, logger?: TGenericLogger, _tableResolver?: TTableResolver | undefined);
+  /**
+   * Sets the encryption service used for `@db.encrypted` fields.
+   * Called by `DbSpace` after table/view creation when the space was
+   * configured with an `encryption` options block.
+   */
+  setEncryption(encryption: DbEncryption | undefined): void;
   /** Ensures metadata is built. Called before any metadata access. */
   protected _ensureBuilt(): void;
   /**
@@ -1277,6 +1416,28 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
    */
   getMetadata(): TableMetadata;
   protected _ensureSearchable(): void;
+  /** Engine-agnostic query-time guards (encrypted-field refs, $geoWithin shape). */
+  protected _guardQuery(query: Uniquery | undefined): void;
+  private _encryptedPathsCache?;
+  /** Pre-split `encryptedFields` paths — computed once, reused on every read/write. */
+  protected get _encryptedPaths(): Array<{
+    path: string;
+    segments: string[];
+    leaf: string;
+  }>;
+  /**
+   * Walks all but the last of `segments` down from `root`, returning the
+   * object holding the leaf — or `undefined` when the path is unreachable
+   * (a missing, non-object, or array step). With `cloneParents`, every
+   * traversed object is shallow-cloned and re-linked so caller-shared
+   * nested objects are never mutated.
+   */
+  protected _walkToLeafParent(root: Record<string, unknown>, segments: string[], cloneParents: boolean): Record<string, unknown> | undefined;
+  /**
+   * Decrypts `@db.encrypted` fields on reconstructed rows (in place).
+   * Non-envelope stored values follow the configured `onUnencrypted` policy.
+   */
+  protected _decryptRows(rows: Array<Record<string, unknown>>): Promise<void>;
   /** Whether this readable is a view (overridden in AtscriptDbView). */
   get isView(): boolean;
   /** Returns the underlying adapter with its concrete type preserved. */
@@ -1438,6 +1599,38 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   }>;
   /** Resolves overloaded vector search arguments into canonical form. */
   private _resolveVectorSearchArgs;
+  /** Whether the underlying adapter supports geospatial search. */
+  isGeoSearchable(): boolean;
+  /**
+   * Distance-ranked geospatial search (mirrors {@link vectorSearch}).
+   * Results are sorted by distance ascending; each row carries a computed
+   * `$distance` field (meters from the query point). `$maxDistance` /
+   * `$minDistance` (meters) ride in `query.controls`; user `$sort` is rejected.
+   *
+   * Overloads:
+   * - `geoSearch(point, query?)` — uses the table's only geo index
+   * - `geoSearch(indexName, point, query?)` — targets a specific geo index
+   */
+  geoSearch<Q extends Uniquery<OwnProps, NavType>>(pointOrIndex: [number, number] | string, maybePointOrQuery?: [number, number] | Q, maybeQuery?: Q): Promise<Array<DbResponse<DataType, NavType, Q> & {
+    $distance: number;
+  }>>;
+  /**
+   * Distance-ranked geospatial search with count for paginated results.
+   *
+   * Overloads:
+   * - `geoSearchWithCount(point, query?)` — uses the table's only geo index
+   * - `geoSearchWithCount(indexName, point, query?)` — targets a specific geo index
+   */
+  geoSearchWithCount<Q extends Uniquery<OwnProps, NavType>>(pointOrIndex: [number, number] | string, maybePointOrQuery?: [number, number] | Q, maybeQuery?: Q): Promise<{
+    data: Array<DbResponse<DataType, NavType, Q> & {
+      $distance: number;
+    }>;
+    count: number;
+  }>;
+  /** Resolves overloaded geo search arguments into canonical form. */
+  private _resolveGeoSearchArgs;
+  /** Shared geoSearch validation + query translation. */
+  private _prepareGeoSearch;
   /**
    * Finds a single record by any type-compatible identifier — primary key
    * or single-field unique index.
@@ -1497,4 +1690,4 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   }, thisTableName: string, alias?: string): TDbForeignKey | undefined;
 }
 //#endregion
-export { TMetadataOverrides as $, TDbCollation as A, TDbInsertResult as B, TColumnDiff as C, TDbActionIntent as D, TDbActionInfo as E, TDbForeignKey as F, TExistingColumn as G, TDbRelation as H, TDbIndex as I, TFkLookupResolver as J, TExistingTableOption as K, TDbIndexField as L, TDbDefaultValue as M, TDbDeleteResult as N, TDbActionLevel as O, TDbFieldMeta as P, TMetaResponse as Q, TDbIndexType as R, TCascadeTarget as S, TCrudPermissions as T, TDbStorageType as U, TDbReferentialAction as V, TDbUpdateResult as W, TIdDescriptor as X, TFkLookupTarget as Y, TIdentification as Z, FlatOf$1 as _, FieldMappingStrategy as a, TValueFormatterPair as at, PrimaryKeyOf$1 as b, AggregateExpr$1 as c, Uniquery$1 as ct, AggregateResult as d, TableMetadata as dt, TRelationInfo as et, AtscriptDbWritable as f, NoopLogger as ft, FilterExpr$1 as g, FieldOpsFor as h, DocumentFieldMapper as i, TTableResolver as it, TDbDefaultFn as j, TDbActionProcessor as k, AggregateFn as l, UniqueryControls$1 as lt, DbQuery as m, UniquSelect as mt, DbResponse as n, TSyncColumnResult as nt, BaseDbAdapter as o, TWriteTableResolver as ot, DbControls as p, TGenericLogger as pt, TFieldMeta as q, resolveDesignType as r, TTableOptionDiff as rt, AggregateControls as s, TypedWithRelation as st, AtscriptDbReadable as t, TSearchIndexInfo as tt, AggregateQuery$1 as u, WithRelation$1 as ut, NavPropsOf$1 as v, TCrudOp as w, TCascadeResolver as x, OwnPropsOf$1 as y, TDbInsertManyResult as z };
+export { TIdentification as $, TDbActionLevel as A, TDbIndexType as B, TCascadeResolver as C, TCrudPermissions as D, TCrudOp as E, TDbDeleteResult as F, TDbStorageType as G, TDbInsertResult as H, TDbFieldMeta as I, TExistingTableOption as J, TDbUpdateResult as K, TDbForeignKey as L, TDbCollation as M, TDbDefaultFn as N, TDbActionInfo as O, TDbDefaultValue as P, TIdDescriptor as Q, TDbIndex as R, PrimaryKeyOf$1 as S, TColumnDiff as T, TDbReferentialAction as U, TDbInsertManyResult as V, TDbRelation as W, TFkLookupResolver as X, TFieldMeta as Y, TFkLookupTarget as Z, FieldOpsFor as _, TGenericLogger as _t, TDbEncryptionOptions as a, TTableOptionDiff as at, NavPropsOf$1 as b, BaseDbAdapter as c, TWriteTableResolver as ct, AggregateFn as d, UniqueryControls$1 as dt, TMetaResponse as et, AggregateQuery$1 as f, WithRelation$1 as ft, DbQuery as g, NoopLogger as gt, DbControls as h, isGeoPointType as ht, DbEncryption as i, TSyncColumnResult as it, TDbActionProcessor as j, TDbActionIntent as k, AggregateControls as l, TypedWithRelation as lt, AtscriptDbWritable as m, isGeoIndexableType as mt, DbResponse as n, TRelationInfo as nt, DocumentFieldMapper as o, TTableResolver as ot, AggregateResult as p, TableMetadata as pt, TExistingColumn as q, resolveDesignType as r, TSearchIndexInfo as rt, FieldMappingStrategy as s, TValueFormatterPair as st, AtscriptDbReadable as t, TMetadataOverrides as tt, AggregateExpr$1 as u, Uniquery$1 as ut, FilterExpr$1 as v, UniquSelect as vt, TCascadeTarget as w, OwnPropsOf$1 as x, FlatOf$1 as y, TDbIndexField as z };

package/dist/{db-readable-CXdHBtF6.d.mts → db-readable-Ds01ezjj.d.mts}

@@ -55,6 +55,14 @@ interface TGenericLogger {
 declare const NoopLogger: TGenericLogger;
 //#endregion
 //#region src/table/table-metadata.d.ts
+/** Returns true if the annotated type IS the `db.geoPoint` primitive (tag-based). */
+declare function isGeoPointType(fieldType: TAtscriptAnnotatedType): boolean;
+/**
+ * Returns true if the annotated type is acceptable for `@db.index.geo`:
+ * the `db.geoPoint` primitive or a structurally identical `number[]`
+ * (excluding `db.vector`, which is semantically an embedding).
+ */
+declare function isGeoIndexableType(fieldType: TAtscriptAnnotatedType): boolean;
 /**
  * Computed metadata for a database table or view.
  *
@@ -87,6 +95,8 @@ declare class TableMetadata {
   versionField?: string;
   /** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
   quantityRefByField: Map<string, string>;
+  /** Logical paths annotated with `@db.encrypted` — stored as one opaque ciphertext column. */
+  encryptedFields: Set<string>;
   pathToPhysical: Map<string, string>;
   physicalToPath: Map<string, string>;
   flattenedParents: Set<string>;
@@ -140,6 +150,14 @@ declare class TableMetadata {
    * Scans `@db.*` and `@meta.id` annotations on a field during flattening.
    */
   private _scanGenericAnnotations;
+  /**
+   * Build-time diagnostics for `@db.encrypted` (§6 of the field-encryption
+   * spec). Mirrors the compile-time AnnotationSpec validation so models built
+   * from pre-compiled types still fail fast.
+   */
+  private _validateEncryptedField;
+  /** Build-time diagnostics for `@db.index.geo` (§3 of the geo-index spec). */
+  private _validateGeoIndexField;
   private _addIndexField;
   /**
    * Classifies each field as column, flattened, json, or parent-object.
@@ -216,9 +234,13 @@ interface TRelationInfo {
 interface TFieldMeta {
   sortable: boolean;
   filterable: boolean;
+  /** Present (true) when the field is `@db.encrypted` — stored as ciphertext at rest. */
+  encrypted?: boolean;
+  /** Present (true) when the field carries a `@db.index.geo` geospatial index. */
+  geo?: boolean;
 }
 /** Built-in CRUD operation names; map 1:1 to public method names. */
-type TCrudOp = "query" | "pages" | "one" | "insert" | "update" | "replace" | "remove";
+type TCrudOp = "query" | "pages" | "one" | "geo" | "insert" | "update" | "replace" | "remove";
 /**
  * CRUD permissions advertised in `/meta`. Key absent → operation is denied or
  * not exposed. Key present → operation is allowed; the `string[]` value is the
@@ -230,6 +252,8 @@ type TCrudPermissions = Partial<Record<TCrudOp, string[]>>;
 interface TMetaResponse {
   searchable: boolean;
   vectorSearchable: boolean;
+  /** Whether the adapter supports `geoSearch()` AND the table declares a geo index. */
+  geoSearchable?: boolean;
   searchIndexes: TSearchIndexInfo[];
   primaryKeys: string[];
   preferredId: string[];
@@ -330,7 +354,7 @@ interface TDbUpdateResult {
 interface TDbDeleteResult {
   deletedCount: number;
 }
-type TDbIndexType = "plain" | "unique" | "fulltext";
+type TDbIndexType = "plain" | "unique" | "fulltext" | "geo";
 interface TDbIndexField {
   name: string;
   sort: "asc" | "desc";
@@ -436,6 +460,19 @@ interface TDbFieldMeta {
    * Undefined for non-FK fields or when the target cannot be resolved.
    */
   fkTargetField?: TDbFieldMeta;
+  /**
+   * `@db.encrypted` — the value is AES-256-GCM encrypted by the core layer
+   * before reaching the adapter. Adapters must map the column to an unbounded
+   * text type and veto filtering/sorting (`canFilterField`/`canSortField`).
+   * The descriptor's `designType` is forced to `'string'` (ciphertext envelope);
+   * the declared type stays available via `type` for validation.
+   */
+  encrypted?: boolean;
+  /**
+   * The field's declared type is the `db.geoPoint` primitive (`[lng, lat]` tuple).
+   * Adapters map this to their native geo storage (e.g. MongoDB GeoJSON Point).
+   */
+  isGeoPoint?: boolean;
 }
 interface TValueFormatterPair {
   /** Converts a JS value to storage representation (write + filter paths). */
@@ -906,6 +943,14 @@ declare abstract class BaseDbAdapter {
     dropIndex(name: string): Promise<void>;
     prefix?: string;
     shouldSkipType?(type: TDbIndex["type"]): boolean;
+    /**
+     * Index types declared on the model but not supported by this adapter —
+     * warns and skips (models stay portable; sync never errors on these).
+     */
+    warnUnsupportedTypes?: {
+      adapter: string;
+      types: ReadonlyArray<TDbIndex["type"]>;
+    };
   }): Promise<void>;
   /**
    * Returns available search indexes for this adapter.
@@ -960,6 +1005,32 @@ declare abstract class BaseDbAdapter {
     data: Array<Record<string, unknown>>;
     count: number;
   }>;
+  /**
+   * Whether this adapter supports geospatial search (`geoSearch()` and the
+   * `$geoWithin` filter operator). Override in adapters that do (MongoDB in v1).
+   */
+  isGeoSearchable(): boolean;
+  /**
+   * Distance-ranked geospatial search. Results sorted by distance ascending;
+   * each row carries a `$distance` field (meters from the query point).
+   * `$maxDistance` / `$minDistance` (meters) ride in `query.controls`.
+   *
+   * @param point - `[lng, lat]` query point (GeoJSON coordinate order).
+   * @param query - Filter, select, skip/limit, $maxDistance/$minDistance.
+   * @param indexName - Optional geo index to target (multi-geo documents).
+   */
+  geoSearch(_point: [number, number], _query: DbQuery, _indexName?: string): Promise<Array<Record<string, unknown>>>;
+  /**
+   * Distance-ranked geospatial search with count (for paginated results).
+   *
+   * @param point - `[lng, lat]` query point (GeoJSON coordinate order).
+   * @param query - Filter, select, skip/limit, $maxDistance/$minDistance.
+   * @param indexName - Optional geo index to target (multi-geo documents).
+   */
+  geoSearchWithCount(_point: [number, number], _query: DbQuery, _indexName?: string): Promise<{
+    data: Array<Record<string, unknown>>;
+    count: number;
+  }>;
   /**
    * Fetches records and total count in one call.
    * Default: two parallel calls. Adapters may override for single-query optimization.
@@ -1207,6 +1278,66 @@ declare class DocumentFieldMapper extends FieldMappingStrategy {
   translatePatchKeys(update: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
 }
 //#endregion
+//#region src/encryption.d.ts
+/**
+ * Configuration for field-level encryption at rest (`@db.encrypted`).
+ * Passed to `DbSpace` via the options bag.
+ */
+interface TDbEncryptionOptions {
+  /** Key used for all new writes. */
+  defaultKeyId: string;
+  /**
+   * Key registry: keyId → 32-byte key (Buffer, or base64/hex/utf8 string).
+   * Decryption looks keys up by the keyId recorded in each value's envelope,
+   * so old keys stay in the registry for as long as data encrypted with them exists.
+   */
+  keys?: Record<string, string | Buffer>;
+  /**
+   * Alternative/supplement to `keys`: async resolver (KMS, Vault, env indirection).
+   * Called once per keyId, result cached for the process lifetime.
+   */
+  resolveKey?: (keyId: string) => Promise<string | Buffer> | string | Buffer;
+  /**
+   * What to do when a stored value is NOT a valid envelope (pre-existing
+   * plaintext rows, e.g. when @db.encrypted is added to a live column).
+   *  - 'error' (default): fail the read with DbError("ENC_NOT_ENCRYPTED")
+   *  - 'passthrough': return the raw value as-is (migration window mode);
+   *    the value gets encrypted on its next write.
+   */
+  onUnencrypted?: "error" | "passthrough";
+}
+/** Decryption context — carried into error messages (never the key itself). */
+interface TDecryptContext {
+  table?: string;
+  field?: string;
+}
+/**
+ * AES-256-GCM envelope encryption service for `@db.encrypted` fields.
+ *
+ * Owned by `DbSpace` and shared across all tables in the space. Values are
+ * `JSON.stringify`'d before encryption (type-exact round-trips) and stored as
+ * a single ASCII envelope string: `aes1$<keyId>$<iv>$<tag>$<ciphertext>`.
+ *
+ * Key material is validated eagerly at construction (`ENC_KEY_INVALID`);
+ * `resolveKey` lookups are cached per keyId for the process lifetime.
+ */
+declare class DbEncryption {
+  readonly defaultKeyId: string;
+  readonly onUnencrypted: "error" | "passthrough";
+  private readonly _keys;
+  private readonly _resolveKey?;
+  private readonly _resolved;
+  constructor(options: TDbEncryptionOptions);
+  /** True when `value` looks like an encryption envelope produced by this service. */
+  isEnvelope(value: unknown): value is string;
+  /** Encrypts a JSON-serializable value into an envelope string using the default key. */
+  encrypt(value: unknown): Promise<string>;
+  /** Decrypts an envelope string back into its plaintext value. */
+  decrypt(envelope: string, ctx?: TDecryptContext): Promise<unknown>;
+  private _decryptFailed;
+  private _getKey;
+}
+//#endregion
 //#region src/table/db-readable.d.ts
 /**
  * Extracts nav prop names from a query's `$with` array.
@@ -1266,8 +1397,16 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   /** Strategy for mapping between logical field shapes and physical storage. */
   protected readonly _fieldMapper: FieldMappingStrategy;
   protected _writeTableResolver?: TWriteTableResolver;
+  /** Encryption service for `@db.encrypted` fields — set by `DbSpace` from its options. */
+  protected _encryption?: DbEncryption;
   private _metaIdPhysical;
   constructor(_type: T, adapter: A, logger?: TGenericLogger, _tableResolver?: TTableResolver | undefined);
+  /**
+   * Sets the encryption service used for `@db.encrypted` fields.
+   * Called by `DbSpace` after table/view creation when the space was
+   * configured with an `encryption` options block.
+   */
+  setEncryption(encryption: DbEncryption | undefined): void;
   /** Ensures metadata is built. Called before any metadata access. */
   protected _ensureBuilt(): void;
   /**
@@ -1277,6 +1416,28 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
    */
   getMetadata(): TableMetadata;
   protected _ensureSearchable(): void;
+  /** Engine-agnostic query-time guards (encrypted-field refs, $geoWithin shape). */
+  protected _guardQuery(query: Uniquery | undefined): void;
+  private _encryptedPathsCache?;
+  /** Pre-split `encryptedFields` paths — computed once, reused on every read/write. */
+  protected get _encryptedPaths(): Array<{
+    path: string;
+    segments: string[];
+    leaf: string;
+  }>;
+  /**
+   * Walks all but the last of `segments` down from `root`, returning the
+   * object holding the leaf — or `undefined` when the path is unreachable
+   * (a missing, non-object, or array step). With `cloneParents`, every
+   * traversed object is shallow-cloned and re-linked so caller-shared
+   * nested objects are never mutated.
+   */
+  protected _walkToLeafParent(root: Record<string, unknown>, segments: string[], cloneParents: boolean): Record<string, unknown> | undefined;
+  /**
+   * Decrypts `@db.encrypted` fields on reconstructed rows (in place).
+   * Non-envelope stored values follow the configured `onUnencrypted` policy.
+   */
+  protected _decryptRows(rows: Array<Record<string, unknown>>): Promise<void>;
   /** Whether this readable is a view (overridden in AtscriptDbView). */
   get isView(): boolean;
   /** Returns the underlying adapter with its concrete type preserved. */
@@ -1438,6 +1599,38 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   }>;
   /** Resolves overloaded vector search arguments into canonical form. */
   private _resolveVectorSearchArgs;
+  /** Whether the underlying adapter supports geospatial search. */
+  isGeoSearchable(): boolean;
+  /**
+   * Distance-ranked geospatial search (mirrors {@link vectorSearch}).
+   * Results are sorted by distance ascending; each row carries a computed
+   * `$distance` field (meters from the query point). `$maxDistance` /
+   * `$minDistance` (meters) ride in `query.controls`; user `$sort` is rejected.
+   *
+   * Overloads:
+   * - `geoSearch(point, query?)` — uses the table's only geo index
+   * - `geoSearch(indexName, point, query?)` — targets a specific geo index
+   */
+  geoSearch<Q extends Uniquery<OwnProps, NavType>>(pointOrIndex: [number, number] | string, maybePointOrQuery?: [number, number] | Q, maybeQuery?: Q): Promise<Array<DbResponse<DataType, NavType, Q> & {
+    $distance: number;
+  }>>;
+  /**
+   * Distance-ranked geospatial search with count for paginated results.
+   *
+   * Overloads:
+   * - `geoSearchWithCount(point, query?)` — uses the table's only geo index
+   * - `geoSearchWithCount(indexName, point, query?)` — targets a specific geo index
+   */
+  geoSearchWithCount<Q extends Uniquery<OwnProps, NavType>>(pointOrIndex: [number, number] | string, maybePointOrQuery?: [number, number] | Q, maybeQuery?: Q): Promise<{
+    data: Array<DbResponse<DataType, NavType, Q> & {
+      $distance: number;
+    }>;
+    count: number;
+  }>;
+  /** Resolves overloaded geo search arguments into canonical form. */
+  private _resolveGeoSearchArgs;
+  /** Shared geoSearch validation + query translation. */
+  private _prepareGeoSearch;
   /**
    * Finds a single record by any type-compatible identifier — primary key
    * or single-field unique index.
@@ -1497,4 +1690,4 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   }, thisTableName: string, alias?: string): TDbForeignKey | undefined;
 }
 //#endregion
-export { TMetadataOverrides as $, TDbCollation as A, TDbInsertResult as B, TColumnDiff as C, TDbActionIntent as D, TDbActionInfo as E, TDbForeignKey as F, TExistingColumn as G, TDbRelation as H, TDbIndex as I, TFkLookupResolver as J, TExistingTableOption as K, TDbIndexField as L, TDbDefaultValue as M, TDbDeleteResult as N, TDbActionLevel as O, TDbFieldMeta as P, TMetaResponse as Q, TDbIndexType as R, TCascadeTarget as S, TCrudPermissions as T, TDbStorageType as U, TDbReferentialAction as V, TDbUpdateResult as W, TIdDescriptor as X, TFkLookupTarget as Y, TIdentification as Z, FlatOf$1 as _, FieldMappingStrategy as a, TValueFormatterPair as at, PrimaryKeyOf$1 as b, AggregateExpr$1 as c, Uniquery$1 as ct, AggregateResult as d, TableMetadata as dt, TRelationInfo as et, AtscriptDbWritable as f, NoopLogger as ft, FilterExpr$1 as g, FieldOpsFor as h, DocumentFieldMapper as i, TTableResolver as it, TDbDefaultFn as j, TDbActionProcessor as k, AggregateFn as l, UniqueryControls$1 as lt, DbQuery as m, UniquSelect as mt, DbResponse as n, TSyncColumnResult as nt, BaseDbAdapter as o, TWriteTableResolver as ot, DbControls as p, TGenericLogger as pt, TFieldMeta as q, resolveDesignType as r, TTableOptionDiff as rt, AggregateControls as s, TypedWithRelation as st, AtscriptDbReadable as t, TSearchIndexInfo as tt, AggregateQuery$1 as u, WithRelation$1 as ut, NavPropsOf$1 as v, TCrudOp as w, TCascadeResolver as x, OwnPropsOf$1 as y, TDbInsertManyResult as z };
+export { TIdentification as $, TDbActionLevel as A, TDbIndexType as B, TCascadeResolver as C, TCrudPermissions as D, TCrudOp as E, TDbDeleteResult as F, TDbStorageType as G, TDbInsertResult as H, TDbFieldMeta as I, TExistingTableOption as J, TDbUpdateResult as K, TDbForeignKey as L, TDbCollation as M, TDbDefaultFn as N, TDbActionInfo as O, TDbDefaultValue as P, TIdDescriptor as Q, TDbIndex as R, PrimaryKeyOf$1 as S, TColumnDiff as T, TDbReferentialAction as U, TDbInsertManyResult as V, TDbRelation as W, TFkLookupResolver as X, TFieldMeta as Y, TFkLookupTarget as Z, FieldOpsFor as _, TGenericLogger as _t, TDbEncryptionOptions as a, TTableOptionDiff as at, NavPropsOf$1 as b, BaseDbAdapter as c, TWriteTableResolver as ct, AggregateFn as d, UniqueryControls$1 as dt, TMetaResponse as et, AggregateQuery$1 as f, WithRelation$1 as ft, DbQuery as g, NoopLogger as gt, DbControls as h, isGeoPointType as ht, DbEncryption as i, TSyncColumnResult as it, TDbActionProcessor as j, TDbActionIntent as k, AggregateControls as l, TypedWithRelation as lt, AtscriptDbWritable as m, isGeoIndexableType as mt, DbResponse as n, TRelationInfo as nt, DocumentFieldMapper as o, TTableResolver as ot, AggregateResult as p, TableMetadata as pt, TExistingColumn as q, resolveDesignType as r, TSearchIndexInfo as rt, FieldMappingStrategy as s, TValueFormatterPair as st, AtscriptDbReadable as t, TMetadataOverrides as tt, AggregateExpr$1 as u, Uniquery$1 as ut, FilterExpr$1 as v, UniquSelect as vt, TCascadeTarget as w, OwnPropsOf$1 as x, FlatOf$1 as y, TDbIndexField as z };