@atscript/db 0.1.133 → 0.1.135

package/dist/{buckets-BENuu_tK.d.mts → buckets-GruoVxH5.d.mts}

@@ -1,6 +1,6 @@
 import { f as TFieldOps } from "./ops-AqhV7s9o.mjs";
 import { FlatOf, FlatOf as FlatOf$1, NavPropsOf, NavPropsOf as NavPropsOf$1, OwnPropsOf, OwnPropsOf as OwnPropsOf$1, PrimaryKeyOf, PrimaryKeyOf as PrimaryKeyOf$1, TAtscriptAnnotatedType, TAtscriptDataType, TAtscriptTypeObject, TMetadataMap, TSerializedAnnotatedType, TValidatorOptions, TValidatorPlugin, Validator } from "@atscript/typescript/utils";
-import { AggregateControls, AggregateExpr, AggregateExpr as AggregateExpr$1, AggregateFn, AggregateQuery, AggregateQuery as AggregateQuery$1, AggregateResult, BucketUnit, FieldOpsFor, FilterExpr, FilterExpr as FilterExpr$1, ResolvedBucket, TypedWithRelation, Uniquery, Uniquery as Uniquery$1, UniqueryControls, UniqueryControls as UniqueryControls$1, UniqueryInsights, WithRelation, WithRelation as WithRelation$1 } from "@uniqu/core";
+import { AggregateControls, AggregateExpr, AggregateExpr as AggregateExpr$1, AggregateFn as AggregateFn$1, AggregateQuery, AggregateQuery as AggregateQuery$1, AggregateResult, BucketUnit, FieldOpsFor, FilterExpr, FilterExpr as FilterExpr$1, ResolvedBucket, TypedWithRelation, Uniquery, Uniquery as Uniquery$1, UniqueryControls, UniqueryControls as UniqueryControls$1, UniqueryInsights, WithRelation, WithRelation as WithRelation$1 } from "@uniqu/core";
 
 //#region src/query/uniqu-select.d.ts
 /**
@@ -361,6 +361,14 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   get preferredId(): readonly string[];
   /** Legitimate row-identifier shapes (primary key + every unique index). */
   get identifications(): readonly TIdentification[];
+  /**
+   * The {@link identifications} an id may resolve through when fields are
+   * hidden per request (since 0.1.134): a unique index with a field that
+   * fails `isFieldVisible` is dropped, as if it did not exist. Primary-key,
+   * `preferredId` and `@meta.id` fields always count as visible. Without a
+   * predicate, every identification.
+   */
+  identificationsVisibleTo(isFieldVisible?: TIdResolveOptions["isFieldVisible"]): readonly TIdentification[];
   /**
    * Physical column name of the single `@meta.id` field, or `null` when the
    * schema has zero or multiple `@meta.id` fields. Used by adapters to return
@@ -414,6 +422,19 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
    * Pre-computed field metadata for adapter use.
    */
   get fieldDescriptors(): readonly TDbFieldMeta[];
+  /**
+   * The target table of the navigation relation `navField` (since 0.1.134),
+   * resolved through the table resolver this readable was built with (the
+   * `DbSpace`'s). `undefined` when `navField` is not a relation of this table
+   * or no resolver is available (a table constructed without a `DbSpace`).
+   * Top-level relation names only — no dotted paths.
+   *
+   * ```typescript
+   * const users = posts.relatedTable('author')
+   * users?.primaryKeys // ['id']
+   * ```
+   */
+  relatedTable(navField: string): ReturnType<TTableResolver>;
   /**
    * Resolves whether `path` references a real field — directly via `flatMap`
    * or transitively through a nav relation by recursing into the target
@@ -567,17 +588,20 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
    * same identification resolution as {@link findById}. Public so callers can
    * AND-combine the id-filter with a row-level read overlay before issuing
    * `findOne` (avoiding the existence leak that `findById` would cause).
+   * `opts.isFieldVisible` (since 0.1.134) drops unique indexes over hidden
+   * fields — see {@link identificationsVisibleTo}.
    */
-  resolveIdFilter(id: unknown): FilterExpr | null;
+  resolveIdFilter(id: unknown, opts?: TIdResolveOptions): FilterExpr | null;
   /**
    * Resolve an id value into a filter expression.
    *
    * When `preferredId` differs from the PK, scalar ids resolve only against
    * the preferred field (deterministic addressing). Otherwise scalars try PK
    * + every single-field unique index; objects try PK + compound unique
-   * indexes.
+   * indexes. With `opts.isFieldVisible`, only the identifications
+   * {@link identificationsVisibleTo} keeps are tried.
    */
-  protected _resolveIdFilter(id: unknown): FilterExpr | null;
+  protected _resolveIdFilter(id: unknown, opts?: TIdResolveOptions): FilterExpr | null;
   /** Build a single-key filter from `idObj` over `fields`, or null if any field is missing/incompatible. */
   private _tryCompoundFilter;
   /**
@@ -1391,6 +1415,7 @@ declare class TableMetadata {
   physicalNames: ReadonlySet<string>;
   private _built;
   private _identifications?;
+  private _alwaysAddressable?;
   private _collateMap;
   private _columnFromMap;
   constructor(nestedObjects: boolean);
@@ -1487,6 +1512,12 @@ declare class TableMetadata {
   private _buildIdentifications;
   /** Legitimate row-identifier shapes — primary key first, then each unique index. */
   getIdentifications(): readonly TIdentification[];
+  /**
+   * Fields that always count as visible for row identification (since
+   * 0.1.134): primary key, `preferredId` and `@meta.id` fields — see
+   * `AtscriptDbReadable.identificationsVisibleTo`.
+   */
+  getAlwaysAddressable(): ReadonlySet<string>;
   private _resolvePreferredId;
 }
 //#endregion
@@ -2114,8 +2145,13 @@ interface TTouchManyOptions {
    */
   require?: "all" | "any";
 }
-/** Options of `insertOne/Many`, `replaceOne` / `bulkReplace`, `updateOne` / `bulkUpdate`. */
-interface TWriteOptions<Row = Record<string, unknown>> {
+/**
+ * Options of `insertOne/Many`, `replaceOne` / `bulkReplace`, `updateOne` / `bulkUpdate`.
+ * `isFieldVisible` (since 0.1.134, see {@link TIdResolveOptions}) applies to the
+ * top-level rows only — a payload without its primary key identifies through
+ * a unique index; nested-relation writes ignore it.
+ */
+interface TWriteOptions<Row = Record<string, unknown>> extends TIdResolveOptions {
   /** Nested-relation write recursion limit (default 3). */
   maxDepth?: number;
   /**
@@ -2128,8 +2164,8 @@ interface TWriteOptions<Row = Record<string, unknown>> {
    */
   guard?: TDbWriteGuard<Row>;
 }
-/** Options of `deleteOne`. */
-interface TDeleteOptions<Row = Record<string, unknown>> {
+/** Options of `deleteOne`. `isFieldVisible` since 0.1.134 — see {@link TIdResolveOptions}. */
+interface TDeleteOptions<Row = Record<string, unknown>> extends TIdResolveOptions {
   /**
    * Validated-stage guard (since 0.1.128): invoked inside the table's
    * transaction after the id resolved to a filter and before cascade /
@@ -2137,6 +2173,17 @@ interface TDeleteOptions<Row = Record<string, unknown>> {
    */
   guard?: TDbRemoveGuard<Row>;
 }
+/** Options of `resolveIdFilter` / `identificationsVisibleTo` (since 0.1.134). */
+interface TIdResolveOptions {
+  /**
+   * Field-visibility predicate (e.g. a per-request read scope). A unique-index
+   * identification with a field that fails it is ignored — the id resolves
+   * exactly as if that index did not exist, so a hidden unique key can never
+   * answer "a row with this value exists". Primary-key, `preferredId` and
+   * `@meta.id` fields always count as visible.
+   */
+  isFieldVisible?: (path: string) => boolean;
+}
 /**
  * Adds `null` to every optional property of `O`. Optional columns store SQL
  * NULL / Mongo null, and the runtime validator accepts `null` for optional
@@ -2176,7 +2223,8 @@ interface TBucketFieldSource {
  * appear in $groupBy", string `$groupBy` entries) with the table's names as
  * the collision set: a bucket alias may not equal a logical path, a physical
  * column or a navigation field, so a label is never reverse-mapped as a
- * column.
+ * column. Aggregate entries are checked against `SUPPORTED_AGGREGATE_FNS`
+ * (and `'*'` is `count`'s only).
  *
  * Which layer validates what:
  * - **Shapes** (this normalizer) run FIRST at every entry point — the core's
@@ -2227,4 +2275,4 @@ declare function isJsonValueField(fd: TDbFieldMeta): boolean;
  */
 declare function jsonValueAncestor(path: string, jsonValueParents: ReadonlySet<string>): string | undefined;
 //#endregion
-export { TDbWriteGuardContext as $, TDbActionIntent as A, isGeoPointType as At, TDbIndexField as B, NoopLogger as Bt, PrimaryKeyOf$1 as C, TypedWithRelation as Ct, TCrudOp as D, TableMetadata as Dt, TColumnDiff as E, WithRelation$1 as Et, TDbDefaultValue as F, resolveDesignType as Ft, TDbReferentialAction as G, TDbInsertManyResult as H, UniquSelect as Ht, TDbDeleteResult as I, DbEncryption as It, TDbRemoveGuardContext as J, TDbRelation as K, TDbFieldMeta as L, TDbEncryptionOptions as Lt, TDbActionProcessor as M, BaseDbAdapter as Mt, TDbCollation as N, AtscriptDbReadable as Nt, TCrudPermissions as O, findAncestorInSet as Ot, TDbDefaultFn as P, DbResponse as Pt, TDbWriteGuard as Q, TDbForeignKey as R, DocumentFieldMapper as Rt, OwnPropsOf$1 as S, TWriteTableResolver as St, TCascadeTarget as T, UniqueryControls$1 as Tt, TDbInsertResult as U, TDbIndexType as V, TGenericLogger as Vt, TDbObjectKind as W, TDbUpdateResult as X, TDbStorageType as Y, TDbWriteAction as Z, FieldOpsFor as _, TTableOptionDiff as _t, jsonValueAncestor as a, TFieldMeta as at, NavPropsOf$1 as b, TValueFormatterPair as bt, AggregateExpr$1 as c, TIdDescriptor as ct, AggregateResult as d, TMetadataOverrides as dt, TDeleteOptions as et, AtscriptDbWritable as f, TPrimaryKeyChange as ft, DbRow as g, TSyncColumnResult as gt, DbQuery as h, TSearchIndexInfo as ht, isJsonValueField as i, TExistingTableOption as it, TDbActionLevel as j, ALL_BUCKET_UNITS as jt, TDbActionInfo as k, isGeoIndexableType as kt, AggregateFn as l, TIdentification as lt, DbPatch as m, TRelationInfo as mt, TResolvedBucket as n, TExistingColumn as nt, resolveCalendarBuckets as o, TFkLookupResolver as ot, DbControls as p, TReferencingForeignKey as pt, TDbRemoveGuard as q, isBucketableField as r, TExistingForeignKey as rt, AggregateControls as s, TFkLookupTarget as st, TBucketFieldSource as t, TEnsureTableOptions as tt, AggregateQuery$1 as u, TMetaResponse as ut, FilterExpr$1 as v, TTableResolver as vt, TCascadeResolver as w, Uniquery$1 as wt, NullableOptional as x, TWriteOptions as xt, FlatOf$1 as y, TTouchManyOptions as yt, TDbIndex as z, FieldMappingStrategy as zt };
+export { TDbWriteGuardContext as $, TDbActionIntent as A, isGeoIndexableType as At, TDbIndexField as B, FieldMappingStrategy as Bt, PrimaryKeyOf$1 as C, TWriteTableResolver as Ct, TCrudOp as D, WithRelation$1 as Dt, TColumnDiff as E, UniqueryControls$1 as Et, TDbDefaultValue as F, DbResponse as Ft, TDbReferentialAction as G, TDbInsertManyResult as H, TGenericLogger as Ht, TDbDeleteResult as I, resolveDesignType as It, TDbRemoveGuardContext as J, TDbRelation as K, TDbFieldMeta as L, DbEncryption as Lt, TDbActionProcessor as M, ALL_BUCKET_UNITS as Mt, TDbCollation as N, BaseDbAdapter as Nt, TCrudPermissions as O, TableMetadata as Ot, TDbDefaultFn as P, AtscriptDbReadable as Pt, TDbWriteGuard as Q, TDbForeignKey as R, TDbEncryptionOptions as Rt, OwnPropsOf$1 as S, TWriteOptions as St, TCascadeTarget as T, Uniquery$1 as Tt, TDbInsertResult as U, UniquSelect as Ut, TDbIndexType as V, NoopLogger as Vt, TDbObjectKind as W, TDbUpdateResult as X, TDbStorageType as Y, TDbWriteAction as Z, FieldOpsFor as _, TSyncColumnResult as _t, jsonValueAncestor as a, TFieldMeta as at, NavPropsOf$1 as b, TTouchManyOptions as bt, AggregateExpr$1 as c, TIdDescriptor as ct, AggregateResult as d, TMetaResponse as dt, TDeleteOptions as et, AtscriptDbWritable as f, TMetadataOverrides as ft, DbRow as g, TSearchIndexInfo as gt, DbQuery as h, TRelationInfo as ht, isJsonValueField as i, TExistingTableOption as it, TDbActionLevel as j, isGeoPointType as jt, TDbActionInfo as k, findAncestorInSet as kt, AggregateFn$1 as l, TIdResolveOptions as lt, DbPatch as m, TReferencingForeignKey as mt, TResolvedBucket as n, TExistingColumn as nt, resolveCalendarBuckets as o, TFkLookupResolver as ot, DbControls as p, TPrimaryKeyChange as pt, TDbRemoveGuard as q, isBucketableField as r, TExistingForeignKey as rt, AggregateControls as s, TFkLookupTarget as st, TBucketFieldSource as t, TEnsureTableOptions as tt, AggregateQuery$1 as u, TIdentification as ut, FilterExpr$1 as v, TTableOptionDiff as vt, TCascadeResolver as w, TypedWithRelation as wt, NullableOptional as x, TValueFormatterPair as xt, FlatOf$1 as y, TTableResolver as yt, TDbIndex as z, DocumentFieldMapper as zt };

package/dist/{db-space-Bv3Ar_Xd.d.mts → db-space-9CH5neN7.d.mts}

@@ -1,4 +1,4 @@
-import { Dt as TableMetadata, H as TDbInsertManyResult, I as TDbDeleteResult, It as DbEncryption, Lt as TDbEncryptionOptions, Mt as BaseDbAdapter, Nt as AtscriptDbReadable, St as TWriteTableResolver, U as TDbInsertResult, Vt as TGenericLogger, X as TDbUpdateResult, et as TDeleteOptions, g as DbRow, m as DbPatch, ot as TFkLookupResolver, pt as TReferencingForeignKey, vt as TTableResolver, w as TCascadeResolver, x as NullableOptional, xt as TWriteOptions, yt as TTouchManyOptions } from "./buckets-BENuu_tK.mjs";
+import { Ct as TWriteTableResolver, H as TDbInsertManyResult, Ht as TGenericLogger, I as TDbDeleteResult, Lt as DbEncryption, Nt as BaseDbAdapter, Ot as TableMetadata, Pt as AtscriptDbReadable, Rt as TDbEncryptionOptions, St as TWriteOptions, U as TDbInsertResult, X as TDbUpdateResult, bt as TTouchManyOptions, et as TDeleteOptions, g as DbRow, lt as TIdResolveOptions, m as DbPatch, mt as TReferencingForeignKey, ot as TFkLookupResolver, w as TCascadeResolver, x as NullableOptional, yt as TTableResolver } from "./buckets-GruoVxH5.mjs";
 import { AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryFieldRef as AtscriptQueryFieldRef$1, AtscriptQueryNode, AtscriptQueryNode as AtscriptQueryNode$1, AtscriptRef, FlatOf, NavPropsOf, OwnPropsOf, PrimaryKeyOf, TAtscriptAnnotatedType, TAtscriptDataType, Validator } from "@atscript/typescript/utils";
 import { FilterExpr } from "@uniqu/core";
 
@@ -202,9 +202,11 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * 2. Single-field unique index — first `@db.index.unique` field found.
    * 3. Compound unique index — first compound unique index whose fields are all present.
    *
-   * Throws when no identifying fields can be found.
+   * Throws when no identifying fields can be found. With `isFieldVisible`
+   * (since 0.1.134), a unique index over a hidden field is skipped, as if it
+   * did not exist — see {@link identificationsVisibleTo}.
    */
-  protected _extractRecordFilter(payload: Record<string, unknown>): FilterExpr;
+  protected _extractRecordFilter(payload: Record<string, unknown>, opts?: TIdResolveOptions): FilterExpr;
   private _prepareFilterValue;
   /**
    * Lazy — builds a `normalized-path → from-depth` map from `this._meta.flatMap`

package/dist/{db-space-DROLifb-.d.cts → db-space-BdtBNTeH.d.cts}

@@ -1,4 +1,4 @@
-import { Dt as TableMetadata, H as TDbInsertManyResult, I as TDbDeleteResult, It as DbEncryption, Lt as TDbEncryptionOptions, Mt as BaseDbAdapter, Nt as AtscriptDbReadable, St as TWriteTableResolver, U as TDbInsertResult, Vt as TGenericLogger, X as TDbUpdateResult, et as TDeleteOptions, g as DbRow, m as DbPatch, ot as TFkLookupResolver, pt as TReferencingForeignKey, vt as TTableResolver, w as TCascadeResolver, x as NullableOptional, xt as TWriteOptions, yt as TTouchManyOptions } from "./buckets-CTWy7Y1k.cjs";
+import { Ct as TWriteTableResolver, H as TDbInsertManyResult, Ht as TGenericLogger, I as TDbDeleteResult, Lt as DbEncryption, Nt as BaseDbAdapter, Ot as TableMetadata, Pt as AtscriptDbReadable, Rt as TDbEncryptionOptions, St as TWriteOptions, U as TDbInsertResult, X as TDbUpdateResult, bt as TTouchManyOptions, et as TDeleteOptions, g as DbRow, lt as TIdResolveOptions, m as DbPatch, mt as TReferencingForeignKey, ot as TFkLookupResolver, w as TCascadeResolver, x as NullableOptional, yt as TTableResolver } from "./buckets-D6PBXKRJ.cjs";
 import { FilterExpr } from "@uniqu/core";
 import { AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryFieldRef as AtscriptQueryFieldRef$1, AtscriptQueryNode, AtscriptQueryNode as AtscriptQueryNode$1, AtscriptRef, FlatOf, NavPropsOf, OwnPropsOf, PrimaryKeyOf, TAtscriptAnnotatedType, TAtscriptDataType, Validator } from "@atscript/typescript/utils";
 
@@ -202,9 +202,11 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * 2. Single-field unique index — first `@db.index.unique` field found.
    * 3. Compound unique index — first compound unique index whose fields are all present.
    *
-   * Throws when no identifying fields can be found.
+   * Throws when no identifying fields can be found. With `isFieldVisible`
+   * (since 0.1.134), a unique index over a hidden field is skipped, as if it
+   * did not exist — see {@link identificationsVisibleTo}.
    */
-  protected _extractRecordFilter(payload: Record<string, unknown>): FilterExpr;
+  protected _extractRecordFilter(payload: Record<string, unknown>, opts?: TIdResolveOptions): FilterExpr;
   private _prepareFilterValue;
   /**
    * Lazy — builds a `normalized-path → from-depth` map from `this._meta.flatMap`

package/dist/{db-view-B5-bQ5AV.cjs → db-view-Dm7MpUGB.cjs}

@@ -1,5 +1,5 @@
 const require_db_error = require("./db-error-DTkkeu5b.cjs");
-require("./agg.cjs");
+const require_agg = require("./agg-EcIbAFnJ.cjs");
 const require_validator = require("./validator-BtZbcLN2.cjs");
 const require_nested_writer = require("./nested-writer-wk1EFUNY.cjs");
 const require_ops = require("./ops.cjs");
@@ -23,7 +23,8 @@ const NoopLogger = {
 * appear in $groupBy", string `$groupBy` entries) with the table's names as
 * the collision set: a bucket alias may not equal a logical path, a physical
 * column or a navigation field, so a label is never reverse-mapped as a
-* column.
+* column. Aggregate entries are checked against `SUPPORTED_AGGREGATE_FNS`
+* (and `'*'` is `count`'s only).
 *
 * Which layer validates what:
 * - **Shapes** (this normalizer) run FIRST at every entry point — the core's
@@ -48,6 +49,7 @@ const NoopLogger = {
 function resolveCalendarBuckets(controls, fields, aggregate) {
 	const res = (0, _uniqu_core.resolveBuckets)(controls, {
 		aggregate,
+		fns: require_agg.SUPPORTED_AGGREGATE_FNS,
 		isField: (name) => fields.flatMap.has(name) || fields.navFields.has(name) || fields.physicalNames.has(name)
 	});
 	if (!res.ok) throw new require_db_error.DbError("INVALID_QUERY", res.issues);
@@ -212,6 +214,7 @@ var TableMetadata = class {
 	physicalNames = /* @__PURE__ */ new Set();
 	_built = false;
 	_identifications;
+	_alwaysAddressable;
 	_collateMap = /* @__PURE__ */ new Map();
 	_columnFromMap = /* @__PURE__ */ new Map();
 	constructor(nestedObjects) {
@@ -281,6 +284,11 @@ var TableMetadata = class {
 		if (!this.nestedObjects) this._buildLeafIndexes();
 		this._buildIdentifications();
 		this._resolvePreferredId(type);
+		this._alwaysAddressable = new Set([
+			...this.primaryKeys,
+			...this.preferredId,
+			...this.originalMetaIdFields
+		]);
 		this._finalizeIndexes();
 		this._collateMap.clear();
 		this._columnFromMap.clear();
@@ -739,6 +747,14 @@ var TableMetadata = class {
 	getIdentifications() {
 		return this._identifications ?? [];
 	}
+	/**
+	* Fields that always count as visible for row identification (since
+	* 0.1.134): primary key, `preferredId` and `@meta.id` fields — see
+	* `AtscriptDbReadable.identificationsVisibleTo`.
+	*/
+	getAlwaysAddressable() {
+		return this._alwaysAddressable ?? /* @__PURE__ */ new Set();
+	}
 	_resolvePreferredId(type) {
 		const preferred = type.metadata.get("db.table.preferredId.uniqueIndex");
 		if (preferred === void 0) {
@@ -2116,6 +2132,19 @@ var AtscriptDbReadable = class {
 		return this._meta.getIdentifications();
 	}
 	/**
+	* The {@link identifications} an id may resolve through when fields are
+	* hidden per request (since 0.1.134): a unique index with a field that
+	* fails `isFieldVisible` is dropped, as if it did not exist. Primary-key,
+	* `preferredId` and `@meta.id` fields always count as visible. Without a
+	* predicate, every identification.
+	*/
+	identificationsVisibleTo(isFieldVisible) {
+		const all = this.identifications;
+		if (!isFieldVisible) return all;
+		const always = this._meta.getAlwaysAddressable();
+		return all.filter((ident) => ident.fields.every((f) => always.has(f) || isFieldVisible(f)));
+	}
+	/**
 	* Physical column name of the single `@meta.id` field, or `null` when the
 	* schema has zero or multiple `@meta.id` fields. Used by adapters to return
 	* the user's logical ID instead of the DB-generated one on insert.
@@ -2235,6 +2264,24 @@ var AtscriptDbReadable = class {
 		return this._meta.fieldDescriptors;
 	}
 	/**
+	* The target table of the navigation relation `navField` (since 0.1.134),
+	* resolved through the table resolver this readable was built with (the
+	* `DbSpace`'s). `undefined` when `navField` is not a relation of this table
+	* or no resolver is available (a table constructed without a `DbSpace`).
+	* Top-level relation names only — no dotted paths.
+	*
+	* ```typescript
+	* const users = posts.relatedTable('author')
+	* users?.primaryKeys // ['id']
+	* ```
+	*/
+	relatedTable(navField) {
+		this._ensureBuilt();
+		const targetType = this._meta.relations.get(navField)?.targetType();
+		if (!targetType || !this._tableResolver) return;
+		return this._tableResolver(targetType);
+	}
+	/**
 	* Resolves whether `path` references a real field — directly via `flatMap`
 	* or transitively through a nav relation by recursing into the target
 	* table. Defense-in-depth for query-path validation: `flattenAnnotatedType`
@@ -2250,12 +2297,7 @@ var AtscriptDbReadable = class {
 		if (dotIdx === -1) return false;
 		const head = path.slice(0, dotIdx);
 		const tail = path.slice(dotIdx + 1);
-		if (!this.navFields.has(head)) return false;
-		const relation = this._meta.relations.get(head);
-		if (!relation) return false;
-		const targetType = relation.targetType();
-		if (!targetType || !this._tableResolver) return false;
-		const targetTable = this._tableResolver(targetType);
+		const targetTable = this.relatedTable(head);
 		if (!targetTable || typeof targetTable.isValidFieldPath !== "function") return false;
 		const visited = _visited ?? /* @__PURE__ */ new Set();
 		const cycleKey = `${this.tableName}:${head}`;
@@ -2621,9 +2663,11 @@ var AtscriptDbReadable = class {
 	* same identification resolution as {@link findById}. Public so callers can
 	* AND-combine the id-filter with a row-level read overlay before issuing
 	* `findOne` (avoiding the existence leak that `findById` would cause).
+	* `opts.isFieldVisible` (since 0.1.134) drops unique indexes over hidden
+	* fields — see {@link identificationsVisibleTo}.
 	*/
-	resolveIdFilter(id) {
-		return this._resolveIdFilter(id);
+	resolveIdFilter(id, opts) {
+		return this._resolveIdFilter(id, opts);
 	}
 	/**
 	* Resolve an id value into a filter expression.
@@ -2631,9 +2675,10 @@ var AtscriptDbReadable = class {
 	* When `preferredId` differs from the PK, scalar ids resolve only against
 	* the preferred field (deterministic addressing). Otherwise scalars try PK
 	* + every single-field unique index; objects try PK + compound unique
-	* indexes.
+	* indexes. With `opts.isFieldVisible`, only the identifications
+	* {@link identificationsVisibleTo} keeps are tried.
 	*/
-	_resolveIdFilter(id) {
+	_resolveIdFilter(id, opts) {
 		const pkFields = this.primaryKeys;
 		const preferredFields = this.preferredId;
 		const isExplicitPreferred = preferredFields.length !== pkFields.length || preferredFields.some((f, i) => f !== pkFields[i]);
@@ -2645,12 +2690,13 @@ var AtscriptDbReadable = class {
 		};
 		const orFilters = [];
 		const idObj = isScalar ? null : id;
-		for (const ident of this.identifications) {
+		const identifications = this.identificationsVisibleTo(opts?.isFieldVisible);
+		for (const ident of identifications) {
 			if (ident.fields.length !== 1) continue;
 			const filter = tryScalarOrField(ident.fields[0]);
 			if (filter) orFilters.push(filter);
 		}
-		if (idObj) for (const ident of this.identifications) {
+		if (idObj) for (const ident of identifications) {
 			if (ident.fields.length < 2) continue;
 			if (ident.source !== "primaryKey" && orFilters.length > 0) break;
 			const filter = this._tryCompoundFilter(ident.fields, idObj);
@@ -4052,7 +4098,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 				const data = items[i];
 				for (const navField of this._meta.navFields) delete data[navField];
 				if (versionColumn !== void 0) assertNoVersionWrites(data, versionColumn);
-				const filter = this._extractRecordFilter(data);
+				const filter = this._extractRecordFilter(data, opts);
 				const prepared = this._fieldMapper.prepareForWrite(data, this._meta, this.adapter);
 				const result = await this.adapter.replaceOne(this._fieldMapper.translateFilter(filter, this._meta), prepared, expectedVersions[i]);
 				matchedCount += result.matchedCount;
@@ -4127,7 +4173,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 				const expectedVersion = expectedVersions[i];
 				const data = { ...payload };
 				for (const navField of this._meta.navFields) delete data[navField];
-				const filter = this._extractRecordFilter(data);
+				const filter = this._extractRecordFilter(data, opts);
 				for (const key of Object.keys(filter)) delete data[key];
 				if (versionColumn !== void 0) assertNoVersionWrites(data, versionColumn);
 				const translatedFilter = this._fieldMapper.translateFilter(filter, this._meta);
@@ -4261,7 +4307,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	*/
 	async deleteOne(id, opts) {
 		this._ensureBuilt();
-		const filter = this._resolveIdFilter(id);
+		const filter = this._resolveIdFilter(id, opts);
 		if (!filter) return { deletedCount: 0 };
 		const guard = opts?.guard;
 		const needsCascade = this._integrity.needsCascade(this._cascadeResolver);
@@ -4435,9 +4481,11 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	* 2. Single-field unique index — first `@db.index.unique` field found.
 	* 3. Compound unique index — first compound unique index whose fields are all present.
 	*
-	* Throws when no identifying fields can be found.
+	* Throws when no identifying fields can be found. With `isFieldVisible`
+	* (since 0.1.134), a unique index over a hidden field is skipped, as if it
+	* did not exist — see {@link identificationsVisibleTo}.
 	*/
-	_extractRecordFilter(payload) {
+	_extractRecordFilter(payload, opts) {
 		const pkFields = this.primaryKeys;
 		if (pkFields.length > 0) {
 			let allPresent = true;
@@ -4451,17 +4499,15 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 				return filter;
 			}
 		}
-		for (const prop of this.uniqueProps) if (payload[prop] !== void 0) return { [prop]: this._prepareFilterValue(prop, payload[prop]) };
-		for (const index of this._meta.indexes.values()) {
-			if (index.type !== "unique" || index.fields.length < 2) continue;
-			let allPresent = true;
-			for (const indexField of index.fields) if (payload[indexField.name] === void 0) {
-				allPresent = false;
-				break;
-			}
-			if (allPresent) {
+		const identifications = this.identificationsVisibleTo(opts?.isFieldVisible);
+		const singleFields = /* @__PURE__ */ new Set();
+		for (const ident of identifications) if (ident.source !== "primaryKey" && ident.fields.length === 1) singleFields.add(ident.fields[0]);
+		for (const prop of this.uniqueProps) if (singleFields.has(prop) && payload[prop] !== void 0) return { [prop]: this._prepareFilterValue(prop, payload[prop]) };
+		for (const ident of identifications) {
+			if (ident.source === "primaryKey" || ident.fields.length < 2) continue;
+			if (ident.fields.every((field) => payload[field] !== void 0)) {
 				const filter = {};
-				for (const indexField of index.fields) filter[indexField.name] = this._prepareFilterValue(indexField.name, payload[indexField.name]);
+				for (const field of ident.fields) filter[field] = this._prepareFilterValue(field, payload[field]);
 				return filter;
 			}
 		}

package/dist/{db-view-caPATLmX.mjs → db-view-Doh8vPg3.mjs}

@@ -1,5 +1,5 @@
 import { n as CasMismatchError, r as DbError } from "./db-error-D5uilS_A.mjs";
-import { resolveAlias } from "./agg.mjs";
+import { a as SUPPORTED_AGGREGATE_FNS, i as resolveAlias } from "./agg-CvXDGnKi.mjs";
 import { a as forceNavNonOptional, c as getKeyProps, i as dbPlugin, l as isEmptyObject, n as buildPatchPartial, t as buildDbValidator, u as isPlainObject } from "./validator-Ch7UIQl9.mjs";
 import { a as batchPatchNestedTo, c as batchReplaceNestedTo, d as preValidateNestedFrom, f as validateBatch, g as findRemoteFK, h as findFKForRelation, i as batchPatchNestedFrom, l as batchReplaceNestedVia, m as remapDeleteFkViolation, n as batchInsertNestedTo, o as batchPatchNestedVia, p as enrichFkViolation, r as batchInsertNestedVia, s as batchReplaceNestedFrom, t as batchInsertNestedFrom, u as checkDepthOverflow } from "./nested-writer-CqL24ojl.mjs";
 import { separateCas, separateFieldOps } from "./ops.mjs";
@@ -23,7 +23,8 @@ const NoopLogger = {
 * appear in $groupBy", string `$groupBy` entries) with the table's names as
 * the collision set: a bucket alias may not equal a logical path, a physical
 * column or a navigation field, so a label is never reverse-mapped as a
-* column.
+* column. Aggregate entries are checked against `SUPPORTED_AGGREGATE_FNS`
+* (and `'*'` is `count`'s only).
 *
 * Which layer validates what:
 * - **Shapes** (this normalizer) run FIRST at every entry point — the core's
@@ -48,6 +49,7 @@ const NoopLogger = {
 function resolveCalendarBuckets(controls, fields, aggregate) {
 	const res = resolveBuckets(controls, {
 		aggregate,
+		fns: SUPPORTED_AGGREGATE_FNS,
 		isField: (name) => fields.flatMap.has(name) || fields.navFields.has(name) || fields.physicalNames.has(name)
 	});
 	if (!res.ok) throw new DbError("INVALID_QUERY", res.issues);
@@ -212,6 +214,7 @@ var TableMetadata = class {
 	physicalNames = /* @__PURE__ */ new Set();
 	_built = false;
 	_identifications;
+	_alwaysAddressable;
 	_collateMap = /* @__PURE__ */ new Map();
 	_columnFromMap = /* @__PURE__ */ new Map();
 	constructor(nestedObjects) {
@@ -281,6 +284,11 @@ var TableMetadata = class {
 		if (!this.nestedObjects) this._buildLeafIndexes();
 		this._buildIdentifications();
 		this._resolvePreferredId(type);
+		this._alwaysAddressable = new Set([
+			...this.primaryKeys,
+			...this.preferredId,
+			...this.originalMetaIdFields
+		]);
 		this._finalizeIndexes();
 		this._collateMap.clear();
 		this._columnFromMap.clear();
@@ -739,6 +747,14 @@ var TableMetadata = class {
 	getIdentifications() {
 		return this._identifications ?? [];
 	}
+	/**
+	* Fields that always count as visible for row identification (since
+	* 0.1.134): primary key, `preferredId` and `@meta.id` fields — see
+	* `AtscriptDbReadable.identificationsVisibleTo`.
+	*/
+	getAlwaysAddressable() {
+		return this._alwaysAddressable ?? /* @__PURE__ */ new Set();
+	}
 	_resolvePreferredId(type) {
 		const preferred = type.metadata.get("db.table.preferredId.uniqueIndex");
 		if (preferred === void 0) {
@@ -2116,6 +2132,19 @@ var AtscriptDbReadable = class {
 		return this._meta.getIdentifications();
 	}
 	/**
+	* The {@link identifications} an id may resolve through when fields are
+	* hidden per request (since 0.1.134): a unique index with a field that
+	* fails `isFieldVisible` is dropped, as if it did not exist. Primary-key,
+	* `preferredId` and `@meta.id` fields always count as visible. Without a
+	* predicate, every identification.
+	*/
+	identificationsVisibleTo(isFieldVisible) {
+		const all = this.identifications;
+		if (!isFieldVisible) return all;
+		const always = this._meta.getAlwaysAddressable();
+		return all.filter((ident) => ident.fields.every((f) => always.has(f) || isFieldVisible(f)));
+	}
+	/**
 	* Physical column name of the single `@meta.id` field, or `null` when the
 	* schema has zero or multiple `@meta.id` fields. Used by adapters to return
 	* the user's logical ID instead of the DB-generated one on insert.
@@ -2235,6 +2264,24 @@ var AtscriptDbReadable = class {
 		return this._meta.fieldDescriptors;
 	}
 	/**
+	* The target table of the navigation relation `navField` (since 0.1.134),
+	* resolved through the table resolver this readable was built with (the
+	* `DbSpace`'s). `undefined` when `navField` is not a relation of this table
+	* or no resolver is available (a table constructed without a `DbSpace`).
+	* Top-level relation names only — no dotted paths.
+	*
+	* ```typescript
+	* const users = posts.relatedTable('author')
+	* users?.primaryKeys // ['id']
+	* ```
+	*/
+	relatedTable(navField) {
+		this._ensureBuilt();
+		const targetType = this._meta.relations.get(navField)?.targetType();
+		if (!targetType || !this._tableResolver) return;
+		return this._tableResolver(targetType);
+	}
+	/**
 	* Resolves whether `path` references a real field — directly via `flatMap`
 	* or transitively through a nav relation by recursing into the target
 	* table. Defense-in-depth for query-path validation: `flattenAnnotatedType`
@@ -2250,12 +2297,7 @@ var AtscriptDbReadable = class {
 		if (dotIdx === -1) return false;
 		const head = path.slice(0, dotIdx);
 		const tail = path.slice(dotIdx + 1);
-		if (!this.navFields.has(head)) return false;
-		const relation = this._meta.relations.get(head);
-		if (!relation) return false;
-		const targetType = relation.targetType();
-		if (!targetType || !this._tableResolver) return false;
-		const targetTable = this._tableResolver(targetType);
+		const targetTable = this.relatedTable(head);
 		if (!targetTable || typeof targetTable.isValidFieldPath !== "function") return false;
 		const visited = _visited ?? /* @__PURE__ */ new Set();
 		const cycleKey = `${this.tableName}:${head}`;
@@ -2621,9 +2663,11 @@ var AtscriptDbReadable = class {
 	* same identification resolution as {@link findById}. Public so callers can
 	* AND-combine the id-filter with a row-level read overlay before issuing
 	* `findOne` (avoiding the existence leak that `findById` would cause).
+	* `opts.isFieldVisible` (since 0.1.134) drops unique indexes over hidden
+	* fields — see {@link identificationsVisibleTo}.
 	*/
-	resolveIdFilter(id) {
-		return this._resolveIdFilter(id);
+	resolveIdFilter(id, opts) {
+		return this._resolveIdFilter(id, opts);
 	}
 	/**
 	* Resolve an id value into a filter expression.
@@ -2631,9 +2675,10 @@ var AtscriptDbReadable = class {
 	* When `preferredId` differs from the PK, scalar ids resolve only against
 	* the preferred field (deterministic addressing). Otherwise scalars try PK
 	* + every single-field unique index; objects try PK + compound unique
-	* indexes.
+	* indexes. With `opts.isFieldVisible`, only the identifications
+	* {@link identificationsVisibleTo} keeps are tried.
 	*/
-	_resolveIdFilter(id) {
+	_resolveIdFilter(id, opts) {
 		const pkFields = this.primaryKeys;
 		const preferredFields = this.preferredId;
 		const isExplicitPreferred = preferredFields.length !== pkFields.length || preferredFields.some((f, i) => f !== pkFields[i]);
@@ -2645,12 +2690,13 @@ var AtscriptDbReadable = class {
 		};
 		const orFilters = [];
 		const idObj = isScalar ? null : id;
-		for (const ident of this.identifications) {
+		const identifications = this.identificationsVisibleTo(opts?.isFieldVisible);
+		for (const ident of identifications) {
 			if (ident.fields.length !== 1) continue;
 			const filter = tryScalarOrField(ident.fields[0]);
 			if (filter) orFilters.push(filter);
 		}
-		if (idObj) for (const ident of this.identifications) {
+		if (idObj) for (const ident of identifications) {
 			if (ident.fields.length < 2) continue;
 			if (ident.source !== "primaryKey" && orFilters.length > 0) break;
 			const filter = this._tryCompoundFilter(ident.fields, idObj);
@@ -4052,7 +4098,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 				const data = items[i];
 				for (const navField of this._meta.navFields) delete data[navField];
 				if (versionColumn !== void 0) assertNoVersionWrites(data, versionColumn);
-				const filter = this._extractRecordFilter(data);
+				const filter = this._extractRecordFilter(data, opts);
 				const prepared = this._fieldMapper.prepareForWrite(data, this._meta, this.adapter);
 				const result = await this.adapter.replaceOne(this._fieldMapper.translateFilter(filter, this._meta), prepared, expectedVersions[i]);
 				matchedCount += result.matchedCount;
@@ -4127,7 +4173,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 				const expectedVersion = expectedVersions[i];
 				const data = { ...payload };
 				for (const navField of this._meta.navFields) delete data[navField];
-				const filter = this._extractRecordFilter(data);
+				const filter = this._extractRecordFilter(data, opts);
 				for (const key of Object.keys(filter)) delete data[key];
 				if (versionColumn !== void 0) assertNoVersionWrites(data, versionColumn);
 				const translatedFilter = this._fieldMapper.translateFilter(filter, this._meta);
@@ -4261,7 +4307,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	*/
 	async deleteOne(id, opts) {
 		this._ensureBuilt();
-		const filter = this._resolveIdFilter(id);
+		const filter = this._resolveIdFilter(id, opts);
 		if (!filter) return { deletedCount: 0 };
 		const guard = opts?.guard;
 		const needsCascade = this._integrity.needsCascade(this._cascadeResolver);
@@ -4435,9 +4481,11 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	* 2. Single-field unique index — first `@db.index.unique` field found.
 	* 3. Compound unique index — first compound unique index whose fields are all present.
 	*
-	* Throws when no identifying fields can be found.
+	* Throws when no identifying fields can be found. With `isFieldVisible`
+	* (since 0.1.134), a unique index over a hidden field is skipped, as if it
+	* did not exist — see {@link identificationsVisibleTo}.
 	*/
-	_extractRecordFilter(payload) {
+	_extractRecordFilter(payload, opts) {
 		const pkFields = this.primaryKeys;
 		if (pkFields.length > 0) {
 			let allPresent = true;
@@ -4451,17 +4499,15 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 				return filter;
 			}
 		}
-		for (const prop of this.uniqueProps) if (payload[prop] !== void 0) return { [prop]: this._prepareFilterValue(prop, payload[prop]) };
-		for (const index of this._meta.indexes.values()) {
-			if (index.type !== "unique" || index.fields.length < 2) continue;
-			let allPresent = true;
-			for (const indexField of index.fields) if (payload[indexField.name] === void 0) {
-				allPresent = false;
-				break;
-			}
-			if (allPresent) {
+		const identifications = this.identificationsVisibleTo(opts?.isFieldVisible);
+		const singleFields = /* @__PURE__ */ new Set();
+		for (const ident of identifications) if (ident.source !== "primaryKey" && ident.fields.length === 1) singleFields.add(ident.fields[0]);
+		for (const prop of this.uniqueProps) if (singleFields.has(prop) && payload[prop] !== void 0) return { [prop]: this._prepareFilterValue(prop, payload[prop]) };
+		for (const ident of identifications) {
+			if (ident.source === "primaryKey" || ident.fields.length < 2) continue;
+			if (ident.fields.every((field) => payload[field] !== void 0)) {
 				const filter = {};
-				for (const indexField of index.fields) filter[indexField.name] = this._prepareFilterValue(indexField.name, payload[indexField.name]);
+				for (const field of ident.fields) filter[field] = this._prepareFilterValue(field, payload[field]);
 				return filter;
 			}
 		}