@atscript/moost-db 0.1.132 → 0.1.133

package/dist/index.cjs

@@ -1155,16 +1155,12 @@ function resolveBoundReadable(ctor) {
 }
 //#endregion
 //#region src/meta/field-capabilities.ts
-const ADAPTER_FILTER = "adapter cannot filter on this storage type";
-const REASON_ADAPTER_FILTER = `${ADAPTER_FILTER}.`;
+const REASON_ADAPTER_FILTER = `${_atscript_db.ADAPTER_FILTER_REASON}.`;
 const REASON_ADAPTER_SORT = "adapter cannot sort on this storage type.";
 const REASON_WRITE_ONLY = "field is @db.writeOnly.";
-const REASON_ENCRYPTED = "field is @db.encrypted (ciphertext cannot be compared or ordered).";
+const REASON_ENCRYPTED = `${_atscript_db.ENCRYPTED_REASON}.`;
 const REASON_ANNOTATION_FILTER = "add @db.column.filterable to enable.";
 const REASON_ANNOTATION_SORT = "add @db.column.sortable to enable.";
-const REASON_NOT_TIMESTAMP = "not a timestamp field (declare it number.timestamp).";
-const REASON_NOT_DIMENSION = "not a dimension.";
-const REASON_NO_BUCKETS = "adapter has no calendar buckets.";
 /** Sentence subject per op ("Filtering on field …"). */
 const OP_SUBJECT = {
 	filter: "Filtering on",
@@ -1235,14 +1231,8 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 	_entries = /* @__PURE__ */ new Map();
 	/** Nested-object parents (never listed, always selectable) → their listed leaves. */
 	_objectParents = /* @__PURE__ */ new Map();
-	/**
-	* Declared dimensions when the table is strict (declares dimensions or
-	* measures), else `undefined` — the core rule: a grouping source, a
-	* bucketed field included, must then be a dimension.
-	*/
-	_dimensions;
-	/** Paths of every JSON-value descriptor (`isJsonValueField`) — see `jsonValueAncestor`. */
-	_jsonValueParents;
+	/** What `bucketSourceVerdict` reads of the table (JSON-value parents, dimensions, measures). */
+	_bucketTable;
 	/** Listed leaves — the {@link TQueryPathSource} view for `classifyQueryPath`. */
 	get leaves() {
 		return this._entries;
@@ -1259,7 +1249,6 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 		this.signature = FieldCapabilityIndex.adapterSignature(source);
 		const units = source.calendarBucketUnits();
 		this.bucketUnits = _uniqu_core.BUCKET_UNITS.filter((unit) => units.has(unit));
-		this._dimensions = source.dimensions.length > 0 || source.measures.length > 0 ? new Set(source.dimensions) : void 0;
 		const physicalNames = /* @__PURE__ */ new Set();
 		const jsonValueParents = /* @__PURE__ */ new Set();
 		for (const fd of source.fieldDescriptors) {
@@ -1267,7 +1256,11 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 			if ((0, _atscript_db.isJsonValueField)(fd)) jsonValueParents.add(fd.path);
 		}
 		this.physicalNames = physicalNames;
-		this._jsonValueParents = jsonValueParents;
+		this._bucketTable = {
+			jsonValueParents,
+			dimensions: source.dimensions,
+			measures: source.measures
+		};
 		const nav = new Set(source.navFields);
 		if (nav.size === 0) for (const name of source.relations.keys()) nav.add(name);
 		this.navFields = nav;
@@ -1324,18 +1317,14 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 			geo: verdict("geo", true)
 		};
 		const filterOps = filterBy.compare === REASON_ADAPTER_FILTER && !filterPolicyBlocked ? (0, _atscript_db.narrowerFilterOps)(fd, source) : [];
-		if (filterOps.length > 0) filterBy.compare = `${ADAPTER_FILTER}${(0, _atscript_db.acceptedOperatorsHint)(filterOps)}.`;
+		if (filterOps.length > 0) filterBy.compare = `${_atscript_db.ADAPTER_FILTER_REASON}${(0, _atscript_db.acceptedOperatorsHint)(filterOps)}.`;
 		const physicalReason = verdict("compare", false);
 		let sortReason = source.canSortField(fd) ? void 0 : REASON_ADAPTER_SORT;
 		if (fd.encrypted) sortReason = REASON_ENCRYPTED;
 		if (isWriteOnly) sortReason = REASON_WRITE_ONLY;
 		if (!sortReason && this.sortableManual && !annotated(fd, "db.column.sortable")) sortReason = REASON_ANNOTATION_SORT;
-		let bucketReason = physicalReason;
-		const jsonAncestor = (0, _atscript_db.jsonValueAncestor)(fd.path, this._jsonValueParents);
-		if (!bucketReason && jsonAncestor !== void 0) bucketReason = `inside JSON-stored column "${jsonAncestor}".`;
-		if (!bucketReason && !(0, _atscript_db.isBucketableField)(fd)) bucketReason = REASON_NOT_TIMESTAMP;
-		if (!bucketReason && this._dimensions && !this._dimensions.has(fd.path)) bucketReason = REASON_NOT_DIMENSION;
-		if (!bucketReason && this.bucketUnits.length === 0) bucketReason = REASON_NO_BUCKETS;
+		const bucket = isWriteOnly ? void 0 : (0, _atscript_db.bucketSourceVerdict)(fd, this._bucketTable, source);
+		const bucketReason = !bucket ? REASON_WRITE_ONLY : bucket.ok ? void 0 : `${bucket.reason}.`;
 		const cap = {
 			filterable: filterBy.compare === void 0,
 			sortable: sortReason === void 0,
@@ -1369,21 +1358,32 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 	}
 	/**
 	* Gate check for one path in one position. Returns `undefined` when the
-	* path is accepted. Order: navigation paths first (a nav path "exists" on
-	* the target table but is never a column here), then a listed leaf's
-	* capability (no existence lookup needed — every listed leaf is a real
-	* field), then `exists` (the readable's `isValidFieldPath`) and, for paths
-	* that exist but are not leaves, the storage classification.
+	* path is accepted.
+	*
+	* `exists` runs FIRST, for every path (since 0.1.133): it is the
+	* controller's `hasField`, the visibility hook subclasses narrow per
+	* request (e.g. a projection-scoped viewer). A path it rejects answers
+	* `Unknown field "x"` exactly like a nonexistent one — never a capability
+	* or navigation hint, which would reveal the field and let a filter or
+	* sort on it act as a value oracle. Before 0.1.133 listed leaves and
+	* navigation paths skipped it.
 	*
-	* Existence deliberately runs BEFORE the JSON / encrypted classification:
-	* an untyped descendant of a JSON column (`address.nope`) is reported as
-	* `Unknown field`, not as "inside JSON-stored column" — clients pin that
-	* wording, so do not "align" it with the core backstop's text.
+	* Then: navigation paths (a nav path exists on the target table but is
+	* never a column here), a listed leaf's capability, and for other paths
+	* the storage classification. Existence also runs BEFORE the JSON /
+	* encrypted classification: an untyped descendant of a JSON column
+	* (`address.nope`) is reported as `Unknown field`, not as "inside
+	* JSON-stored column" — clients pin that wording, so do not "align" it
+	* with the core backstop's text.
 	*
 	* `predicate` is a filter entry's class (`collectQueryPaths` records it per
 	* occurrence); it only matters for `op === "filter"` on a listed leaf.
 	*/
 	check(path, op, exists, predicate = "compare") {
+		if (!exists(path)) return {
+			path,
+			message: `Unknown field "${path}"`
+		};
 		const { kind, parent } = (0, _atscript_db.classifyQueryPath)(this, path);
 		if (kind === "nav") {
 			if (parent === void 0) return {
@@ -1423,10 +1423,6 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 				};
 			}
 		}
-		if (!exists(path)) return {
-			path,
-			message: `Unknown field "${path}"`
-		};
 		switch (kind) {
 			case "objectParent":
 				if (op === "select") return void 0;
@@ -1537,7 +1533,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	metaCacheKey() {
 		return this.capabilities;
 	}
-	/** Bound once: the field-existence check the gate hands to `capabilities.check`. */
+	/** Bound once: the visibility check ({@link hasField}) the gate hands to `capabilities.check`. */
 	_exists = (path) => this.hasField(path);
 	_preferredIdSet;
 	_overlayIsNoOp;
@@ -1590,6 +1586,20 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		for (const [path, entry] of this.readable.flatMap) if (entry?.metadata?.has?.(annotation)) out.add(path);
 		return out;
 	}
+	/**
+	* THE field-visibility hook: every gated path consults it before any
+	* capability check (since 0.1.133) — filter keys (inside `$and` / `$or` /
+	* `$not`, existence predicates included), `$sort`, `$select`,
+	* `$groupBy`, `$having` keys, aggregate and calendar-bucket `$field`s,
+	* `$with` relation names and sub-query paths, and the `$search` fallback
+	* fields. A path it rejects is answered exactly like a nonexistent one
+	* (`Unknown field "x"` / `Unknown relation "x"`), so override it to hide
+	* fields per request (read scopes). The default accepts every real path
+	* (`isValidFieldPath`). `/meta` does NOT consult it — prune hidden fields
+	* there with `applyMetaOverlay`. Native text search and vector search
+	* (`$vector` names an index) run inside the engine over its indexes, out of
+	* this hook's reach — keep hidden fields out of those indexes.
+	*/
 	hasField(path) {
 		if (typeof this.readable.isValidFieldPath === "function") return this.readable.isValidFieldPath(path);
 		return this.readable.flatMap.has(path);
@@ -1677,7 +1687,13 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		const withRelations = parsed.controls.$with;
 		if (withRelations?.length) {
 			const relations = this.readable.relations;
-			for (const rel of withRelations) if (!rel.name.includes(".") && !relations.has(rel.name)) return badRequest("$with", `Unknown relation "${rel.name}"`, `Unknown relation "${rel.name}" in $with. Available relations: ${[...relations.keys()].join(", ") || "(none)"}`);
+			for (const rel of withRelations) {
+				const dot = rel.name.indexOf(".");
+				if (!(dot === -1 ? relations.has(rel.name) && this.hasField(rel.name) : this.hasField(rel.name.slice(0, dot)))) {
+					const visible = [...relations.keys()].filter((name) => this.hasField(name));
+					return badRequest("$with", `Unknown relation "${rel.name}"`, `Unknown relation "${rel.name}" in $with. Available relations: ${visible.join(", ") || "(none)"}`);
+				}
+			}
 		}
 	}
 	/**
@@ -1914,10 +1930,11 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	/** First `@db.writeOnly` field referenced by `$groupBy` / aggregate `$select`, or undefined. */
 	_findWriteOnlyInAggregate(groupBy, select) {
 		if (this._writeOnlySet.size === 0) return void 0;
-		for (const f of groupBy) if (this._writeOnlySet.has(f)) return f;
+		const sealed = (f) => this._writeOnlySet.has(f) && this.hasField(f);
+		for (const f of groupBy) if (sealed(f)) return f;
 		if (Array.isArray(select)) for (const item of select) {
 			const field = typeof item === "string" ? item : item.$field;
-			if (field && this._writeOnlySet.has(field)) return field;
+			if (field && sealed(field)) return field;
 		}
 	}
 	/**
@@ -1929,9 +1946,11 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	applySearchFallback(filter, controls) {
 		const term = controls.$search;
 		if (!term || controls.$vector !== void 0) return filter;
-		if (this.readable.isSearchable() || this._searchFallbackFields.length === 0) return filter;
+		if (this.readable.isSearchable()) return filter;
+		const fields = this._searchFallbackFields.filter((f) => this.hasField(f));
+		if (fields.length === 0) return filter;
 		const rx = `/${term.replace(/[.*+?^${}()|[\]\\/]/g, String.raw`\$&`)}/i`;
-		const fragment = { $or: this._searchFallbackFields.map((f) => ({ [f]: { $regex: rx } })) };
+		const fragment = { $or: fields.map((f) => ({ [f]: { $regex: rx } })) };
 		return filter && Object.keys(filter).length > 0 ? { $and: [filter, fragment] } : fragment;
 	}
 	/**

package/dist/index.d.cts

@@ -22,7 +22,9 @@ import { parseUrl } from "@uniqu/url";
  *
  * Subclass responsibilities:
  * - Pass the bound interface + logical name + (optional) kind tag through super().
- * - Implement {@link hasField} so insights validation can reject unknown keys.
+ * - Implement {@link hasField} — the field-visibility hook every validated
+ *   path consults; a path it rejects gets the same `Unknown field` 400 as a
+ *   nonexistent one, so overriding it hides fields per request.
  * - Register the `/query`, `/pages`, `/one(/:id)` routes with the concrete
  *   handlers that match the data source's contract (DB readables route into
  *   aggregate/vector/search; value-help controllers just filter/sort/paginate).
@@ -45,7 +47,11 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   /** Cached serialized form schemas keyed by `FormType.name` — populated lazily by {@link metaForm}. */
   private _formSchemas;
   constructor(boundType: T, controllerName: string, app: Moost, kindTag?: string);
-  /** Subclass contract: return `true` if `path` addresses a valid field on the bound source. */
+  /**
+   * Subclass contract: return `true` if `path` addresses a field that exists
+   * AND is visible to the current request — see the DB controller's override
+   * for the full list of positions that consult it.
+   */
   protected abstract hasField(path: string): boolean;
   /** Sets @db.http.path on the type metadata from the controller's computed prefix. */
   private _resolveHttpPath;
@@ -195,9 +201,9 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
  * `filterable` is the value-comparison verdict, `filterOps` the narrower
  * predicates that still pass where it is `false`.
  *
- * A calendar-bucket source (`bucketable`) needs the physical capability, a
- * `number.timestamp` type, dimension status on a strict (dimension / measure
- * declaring) table, and an adapter with calendar-bucket units.
+ * A calendar-bucket source (`bucketable`) is the core's `bucketSourceVerdict`
+ * (the same function the core path guard runs) under the HTTP-only
+ * `@db.writeOnly` veto.
  */
 interface TFieldCapability {
   /** A value-comparison filter on this path passes the gate (adapter ∧ ¬writeOnly ∧ ¬encrypted ∧ policy). */
@@ -215,8 +221,8 @@ interface TFieldCapability {
   /** Present when `sortable` is `false` — the reason clause appended to the HTTP 400 message. */
   sortReason?: string;
   /**
-   * A calendar bucket over this path passes the gate (physical ∧ timestamp ∧
-   * (¬strict ∨ dimension) ∧ adapter has calendar buckets). Since 0.1.132.
+   * A calendar bucket over this path passes the gate (¬writeOnly ∧ the core's
+   * `bucketSourceVerdict`). Since 0.1.132.
    */
   bucketable: boolean;
   /** Present when `bucketable` is `false` — the reason clause appended to the HTTP 400 message. */
@@ -272,14 +278,8 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
   private readonly _entries;
   /** Nested-object parents (never listed, always selectable) → their listed leaves. */
   private readonly _objectParents;
-  /**
-   * Declared dimensions when the table is strict (declares dimensions or
-   * measures), else `undefined` — the core rule: a grouping source, a
-   * bucketed field included, must then be a dimension.
-   */
-  private readonly _dimensions;
-  /** Paths of every JSON-value descriptor (`isJsonValueField`) — see `jsonValueAncestor`. */
-  private readonly _jsonValueParents;
+  /** What `bucketSourceVerdict` reads of the table (JSON-value parents, dimensions, measures). */
+  private readonly _bucketTable;
   /** Listed leaves — the {@link TQueryPathSource} view for `classifyQueryPath`. */
   get leaves(): ReadonlyMap<string, unknown>;
   /** Nested-object parents — the {@link TQueryPathSource} view for `classifyQueryPath`. */
@@ -292,16 +292,23 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
   isPhysicallyFilterable(path: string): boolean;
   /**
    * Gate check for one path in one position. Returns `undefined` when the
-   * path is accepted. Order: navigation paths first (a nav path "exists" on
-   * the target table but is never a column here), then a listed leaf's
-   * capability (no existence lookup needed — every listed leaf is a real
-   * field), then `exists` (the readable's `isValidFieldPath`) and, for paths
-   * that exist but are not leaves, the storage classification.
+   * path is accepted.
    *
-   * Existence deliberately runs BEFORE the JSON / encrypted classification:
-   * an untyped descendant of a JSON column (`address.nope`) is reported as
-   * `Unknown field`, not as "inside JSON-stored column" — clients pin that
-   * wording, so do not "align" it with the core backstop's text.
+   * `exists` runs FIRST, for every path (since 0.1.133): it is the
+   * controller's `hasField`, the visibility hook subclasses narrow per
+   * request (e.g. a projection-scoped viewer). A path it rejects answers
+   * `Unknown field "x"` exactly like a nonexistent one — never a capability
+   * or navigation hint, which would reveal the field and let a filter or
+   * sort on it act as a value oracle. Before 0.1.133 listed leaves and
+   * navigation paths skipped it.
+   *
+   * Then: navigation paths (a nav path exists on the target table but is
+   * never a column here), a listed leaf's capability, and for other paths
+   * the storage classification. Existence also runs BEFORE the JSON /
+   * encrypted classification: an untyped descendant of a JSON column
+   * (`address.nope`) is reported as `Unknown field`, not as "inside
+   * JSON-stored column" — clients pin that wording, so do not "align" it
+   * with the core backstop's text.
    *
    * `predicate` is a filter entry's class (`collectQueryPaths` records it per
    * occurrence); it only matters for `op === "filter"` on a listed leaf.
@@ -343,7 +350,7 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private _capabilities?;
   /** `/meta` is a projection of {@link capabilities}: a rebuilt index rebuilds the cached envelope. */
   protected metaCacheKey(): unknown;
-  /** Bound once: the field-existence check the gate hands to `capabilities.check`. */
+  /** Bound once: the visibility check ({@link hasField}) the gate hands to `capabilities.check`. */
   private readonly _exists;
   private readonly _preferredIdSet;
   private readonly _overlayIsNoOp;
@@ -363,6 +370,20 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private _collectInvertibleFields;
   private _collectQuantityRefs;
   private _collectAnnotated;
+  /**
+   * THE field-visibility hook: every gated path consults it before any
+   * capability check (since 0.1.133) — filter keys (inside `$and` / `$or` /
+   * `$not`, existence predicates included), `$sort`, `$select`,
+   * `$groupBy`, `$having` keys, aggregate and calendar-bucket `$field`s,
+   * `$with` relation names and sub-query paths, and the `$search` fallback
+   * fields. A path it rejects is answered exactly like a nonexistent one
+   * (`Unknown field "x"` / `Unknown relation "x"`), so override it to hide
+   * fields per request (read scopes). The default accepts every real path
+   * (`isValidFieldPath`). `/meta` does NOT consult it — prune hidden fields
+   * there with `applyMetaOverlay`. Native text search and vector search
+   * (`$vector` names an index) run inside the engine over its indexes, out of
+   * this hook's reach — keep hidden fields out of those indexes.
+   */
   protected hasField(path: string): boolean;
   /**
    * Structural capability gate (since 0.1.128): walks the PARSED query —

package/dist/index.d.mts

@@ -22,7 +22,9 @@ import { AtscriptDbReadable, AtscriptDbTable, BucketUnit, FilterExpr, FlatOf, TC
  *
  * Subclass responsibilities:
  * - Pass the bound interface + logical name + (optional) kind tag through super().
- * - Implement {@link hasField} so insights validation can reject unknown keys.
+ * - Implement {@link hasField} — the field-visibility hook every validated
+ *   path consults; a path it rejects gets the same `Unknown field` 400 as a
+ *   nonexistent one, so overriding it hides fields per request.
  * - Register the `/query`, `/pages`, `/one(/:id)` routes with the concrete
  *   handlers that match the data source's contract (DB readables route into
  *   aggregate/vector/search; value-help controllers just filter/sort/paginate).
@@ -45,7 +47,11 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   /** Cached serialized form schemas keyed by `FormType.name` — populated lazily by {@link metaForm}. */
   private _formSchemas;
   constructor(boundType: T, controllerName: string, app: Moost, kindTag?: string);
-  /** Subclass contract: return `true` if `path` addresses a valid field on the bound source. */
+  /**
+   * Subclass contract: return `true` if `path` addresses a field that exists
+   * AND is visible to the current request — see the DB controller's override
+   * for the full list of positions that consult it.
+   */
   protected abstract hasField(path: string): boolean;
   /** Sets @db.http.path on the type metadata from the controller's computed prefix. */
   private _resolveHttpPath;
@@ -195,9 +201,9 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
  * `filterable` is the value-comparison verdict, `filterOps` the narrower
  * predicates that still pass where it is `false`.
  *
- * A calendar-bucket source (`bucketable`) needs the physical capability, a
- * `number.timestamp` type, dimension status on a strict (dimension / measure
- * declaring) table, and an adapter with calendar-bucket units.
+ * A calendar-bucket source (`bucketable`) is the core's `bucketSourceVerdict`
+ * (the same function the core path guard runs) under the HTTP-only
+ * `@db.writeOnly` veto.
  */
 interface TFieldCapability {
   /** A value-comparison filter on this path passes the gate (adapter ∧ ¬writeOnly ∧ ¬encrypted ∧ policy). */
@@ -215,8 +221,8 @@ interface TFieldCapability {
   /** Present when `sortable` is `false` — the reason clause appended to the HTTP 400 message. */
   sortReason?: string;
   /**
-   * A calendar bucket over this path passes the gate (physical ∧ timestamp ∧
-   * (¬strict ∨ dimension) ∧ adapter has calendar buckets). Since 0.1.132.
+   * A calendar bucket over this path passes the gate (¬writeOnly ∧ the core's
+   * `bucketSourceVerdict`). Since 0.1.132.
    */
   bucketable: boolean;
   /** Present when `bucketable` is `false` — the reason clause appended to the HTTP 400 message. */
@@ -272,14 +278,8 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
   private readonly _entries;
   /** Nested-object parents (never listed, always selectable) → their listed leaves. */
   private readonly _objectParents;
-  /**
-   * Declared dimensions when the table is strict (declares dimensions or
-   * measures), else `undefined` — the core rule: a grouping source, a
-   * bucketed field included, must then be a dimension.
-   */
-  private readonly _dimensions;
-  /** Paths of every JSON-value descriptor (`isJsonValueField`) — see `jsonValueAncestor`. */
-  private readonly _jsonValueParents;
+  /** What `bucketSourceVerdict` reads of the table (JSON-value parents, dimensions, measures). */
+  private readonly _bucketTable;
   /** Listed leaves — the {@link TQueryPathSource} view for `classifyQueryPath`. */
   get leaves(): ReadonlyMap<string, unknown>;
   /** Nested-object parents — the {@link TQueryPathSource} view for `classifyQueryPath`. */
@@ -292,16 +292,23 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
   isPhysicallyFilterable(path: string): boolean;
   /**
    * Gate check for one path in one position. Returns `undefined` when the
-   * path is accepted. Order: navigation paths first (a nav path "exists" on
-   * the target table but is never a column here), then a listed leaf's
-   * capability (no existence lookup needed — every listed leaf is a real
-   * field), then `exists` (the readable's `isValidFieldPath`) and, for paths
-   * that exist but are not leaves, the storage classification.
+   * path is accepted.
    *
-   * Existence deliberately runs BEFORE the JSON / encrypted classification:
-   * an untyped descendant of a JSON column (`address.nope`) is reported as
-   * `Unknown field`, not as "inside JSON-stored column" — clients pin that
-   * wording, so do not "align" it with the core backstop's text.
+   * `exists` runs FIRST, for every path (since 0.1.133): it is the
+   * controller's `hasField`, the visibility hook subclasses narrow per
+   * request (e.g. a projection-scoped viewer). A path it rejects answers
+   * `Unknown field "x"` exactly like a nonexistent one — never a capability
+   * or navigation hint, which would reveal the field and let a filter or
+   * sort on it act as a value oracle. Before 0.1.133 listed leaves and
+   * navigation paths skipped it.
+   *
+   * Then: navigation paths (a nav path exists on the target table but is
+   * never a column here), a listed leaf's capability, and for other paths
+   * the storage classification. Existence also runs BEFORE the JSON /
+   * encrypted classification: an untyped descendant of a JSON column
+   * (`address.nope`) is reported as `Unknown field`, not as "inside
+   * JSON-stored column" — clients pin that wording, so do not "align" it
+   * with the core backstop's text.
    *
    * `predicate` is a filter entry's class (`collectQueryPaths` records it per
    * occurrence); it only matters for `op === "filter"` on a listed leaf.
@@ -343,7 +350,7 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private _capabilities?;
   /** `/meta` is a projection of {@link capabilities}: a rebuilt index rebuilds the cached envelope. */
   protected metaCacheKey(): unknown;
-  /** Bound once: the field-existence check the gate hands to `capabilities.check`. */
+  /** Bound once: the visibility check ({@link hasField}) the gate hands to `capabilities.check`. */
   private readonly _exists;
   private readonly _preferredIdSet;
   private readonly _overlayIsNoOp;
@@ -363,6 +370,20 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private _collectInvertibleFields;
   private _collectQuantityRefs;
   private _collectAnnotated;
+  /**
+   * THE field-visibility hook: every gated path consults it before any
+   * capability check (since 0.1.133) — filter keys (inside `$and` / `$or` /
+   * `$not`, existence predicates included), `$sort`, `$select`,
+   * `$groupBy`, `$having` keys, aggregate and calendar-bucket `$field`s,
+   * `$with` relation names and sub-query paths, and the `$search` fallback
+   * fields. A path it rejects is answered exactly like a nonexistent one
+   * (`Unknown field "x"` / `Unknown relation "x"`), so override it to hide
+   * fields per request (read scopes). The default accepts every real path
+   * (`isValidFieldPath`). `/meta` does NOT consult it — prune hidden fields
+   * there with `applyMetaOverlay`. Native text search and vector search
+   * (`$vector` names an index) run inside the engine over its indexes, out of
+   * this hook's reach — keep hidden fields out of those indexes.
+   */
   protected hasField(path: string): boolean;
   /**
    * Structural capability gate (since 0.1.128): walks the PARSED query —

package/dist/index.mjs

@@ -3,7 +3,7 @@ import { ValidatorError, defineAnnotatedType, isAnnotatedType, serializeAnnotate
 import { Body, Delete, Get, HttpError, Patch, Post, Put, Query, Url } from "@moostjs/event-http";
 import { ApplyDecorators, Controller, Inherit, Inject, Intercept, Moost, Optional, Param, Provide, Resolve, TInterceptorPriority, defineBeforeInterceptor, defineInterceptor, getMoostMate, useControllerContext } from "moost";
 import { parseUrl } from "@uniqu/url";
-import { DbError, acceptedOperatorsHint, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, collectQueryPaths as collectQueryPaths$1, findAncestorInSet, isBucketableField, isJsonValueField, isPlainObject, jsonValueAncestor, narrowerFilterOps, reconcileCas, resolveCalendarBuckets, unsupportedOperatorMessage } from "@atscript/db";
+import { ADAPTER_FILTER_REASON, DbError, ENCRYPTED_REASON, acceptedOperatorsHint, bucketSourceVerdict, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, collectQueryPaths as collectQueryPaths$1, findAncestorInSet, isJsonValueField, isPlainObject, narrowerFilterOps, reconcileCas, resolveCalendarBuckets, unsupportedOperatorMessage } from "@atscript/db";
 import { BUCKET_UNITS } from "@uniqu/core";
 import { buildMemoryPredicate, projectRow, sortRows } from "@atscript/db-memory";
 import { cached, current, defineWook, key } from "@wooksjs/event-core";
@@ -1154,16 +1154,12 @@ function resolveBoundReadable(ctor) {
 }
 //#endregion
 //#region src/meta/field-capabilities.ts
-const ADAPTER_FILTER = "adapter cannot filter on this storage type";
-const REASON_ADAPTER_FILTER = `${ADAPTER_FILTER}.`;
+const REASON_ADAPTER_FILTER = `${ADAPTER_FILTER_REASON}.`;
 const REASON_ADAPTER_SORT = "adapter cannot sort on this storage type.";
 const REASON_WRITE_ONLY = "field is @db.writeOnly.";
-const REASON_ENCRYPTED = "field is @db.encrypted (ciphertext cannot be compared or ordered).";
+const REASON_ENCRYPTED = `${ENCRYPTED_REASON}.`;
 const REASON_ANNOTATION_FILTER = "add @db.column.filterable to enable.";
 const REASON_ANNOTATION_SORT = "add @db.column.sortable to enable.";
-const REASON_NOT_TIMESTAMP = "not a timestamp field (declare it number.timestamp).";
-const REASON_NOT_DIMENSION = "not a dimension.";
-const REASON_NO_BUCKETS = "adapter has no calendar buckets.";
 /** Sentence subject per op ("Filtering on field …"). */
 const OP_SUBJECT = {
 	filter: "Filtering on",
@@ -1234,14 +1230,8 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 	_entries = /* @__PURE__ */ new Map();
 	/** Nested-object parents (never listed, always selectable) → their listed leaves. */
 	_objectParents = /* @__PURE__ */ new Map();
-	/**
-	* Declared dimensions when the table is strict (declares dimensions or
-	* measures), else `undefined` — the core rule: a grouping source, a
-	* bucketed field included, must then be a dimension.
-	*/
-	_dimensions;
-	/** Paths of every JSON-value descriptor (`isJsonValueField`) — see `jsonValueAncestor`. */
-	_jsonValueParents;
+	/** What `bucketSourceVerdict` reads of the table (JSON-value parents, dimensions, measures). */
+	_bucketTable;
 	/** Listed leaves — the {@link TQueryPathSource} view for `classifyQueryPath`. */
 	get leaves() {
 		return this._entries;
@@ -1258,7 +1248,6 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 		this.signature = FieldCapabilityIndex.adapterSignature(source);
 		const units = source.calendarBucketUnits();
 		this.bucketUnits = BUCKET_UNITS.filter((unit) => units.has(unit));
-		this._dimensions = source.dimensions.length > 0 || source.measures.length > 0 ? new Set(source.dimensions) : void 0;
 		const physicalNames = /* @__PURE__ */ new Set();
 		const jsonValueParents = /* @__PURE__ */ new Set();
 		for (const fd of source.fieldDescriptors) {
@@ -1266,7 +1255,11 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 			if (isJsonValueField(fd)) jsonValueParents.add(fd.path);
 		}
 		this.physicalNames = physicalNames;
-		this._jsonValueParents = jsonValueParents;
+		this._bucketTable = {
+			jsonValueParents,
+			dimensions: source.dimensions,
+			measures: source.measures
+		};
 		const nav = new Set(source.navFields);
 		if (nav.size === 0) for (const name of source.relations.keys()) nav.add(name);
 		this.navFields = nav;
@@ -1323,18 +1316,14 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 			geo: verdict("geo", true)
 		};
 		const filterOps = filterBy.compare === REASON_ADAPTER_FILTER && !filterPolicyBlocked ? narrowerFilterOps(fd, source) : [];
-		if (filterOps.length > 0) filterBy.compare = `${ADAPTER_FILTER}${acceptedOperatorsHint(filterOps)}.`;
+		if (filterOps.length > 0) filterBy.compare = `${ADAPTER_FILTER_REASON}${acceptedOperatorsHint(filterOps)}.`;
 		const physicalReason = verdict("compare", false);
 		let sortReason = source.canSortField(fd) ? void 0 : REASON_ADAPTER_SORT;
 		if (fd.encrypted) sortReason = REASON_ENCRYPTED;
 		if (isWriteOnly) sortReason = REASON_WRITE_ONLY;
 		if (!sortReason && this.sortableManual && !annotated(fd, "db.column.sortable")) sortReason = REASON_ANNOTATION_SORT;
-		let bucketReason = physicalReason;
-		const jsonAncestor = jsonValueAncestor(fd.path, this._jsonValueParents);
-		if (!bucketReason && jsonAncestor !== void 0) bucketReason = `inside JSON-stored column "${jsonAncestor}".`;
-		if (!bucketReason && !isBucketableField(fd)) bucketReason = REASON_NOT_TIMESTAMP;
-		if (!bucketReason && this._dimensions && !this._dimensions.has(fd.path)) bucketReason = REASON_NOT_DIMENSION;
-		if (!bucketReason && this.bucketUnits.length === 0) bucketReason = REASON_NO_BUCKETS;
+		const bucket = isWriteOnly ? void 0 : bucketSourceVerdict(fd, this._bucketTable, source);
+		const bucketReason = !bucket ? REASON_WRITE_ONLY : bucket.ok ? void 0 : `${bucket.reason}.`;
 		const cap = {
 			filterable: filterBy.compare === void 0,
 			sortable: sortReason === void 0,
@@ -1368,21 +1357,32 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 	}
 	/**
 	* Gate check for one path in one position. Returns `undefined` when the
-	* path is accepted. Order: navigation paths first (a nav path "exists" on
-	* the target table but is never a column here), then a listed leaf's
-	* capability (no existence lookup needed — every listed leaf is a real
-	* field), then `exists` (the readable's `isValidFieldPath`) and, for paths
-	* that exist but are not leaves, the storage classification.
+	* path is accepted.
+	*
+	* `exists` runs FIRST, for every path (since 0.1.133): it is the
+	* controller's `hasField`, the visibility hook subclasses narrow per
+	* request (e.g. a projection-scoped viewer). A path it rejects answers
+	* `Unknown field "x"` exactly like a nonexistent one — never a capability
+	* or navigation hint, which would reveal the field and let a filter or
+	* sort on it act as a value oracle. Before 0.1.133 listed leaves and
+	* navigation paths skipped it.
 	*
-	* Existence deliberately runs BEFORE the JSON / encrypted classification:
-	* an untyped descendant of a JSON column (`address.nope`) is reported as
-	* `Unknown field`, not as "inside JSON-stored column" — clients pin that
-	* wording, so do not "align" it with the core backstop's text.
+	* Then: navigation paths (a nav path exists on the target table but is
+	* never a column here), a listed leaf's capability, and for other paths
+	* the storage classification. Existence also runs BEFORE the JSON /
+	* encrypted classification: an untyped descendant of a JSON column
+	* (`address.nope`) is reported as `Unknown field`, not as "inside
+	* JSON-stored column" — clients pin that wording, so do not "align" it
+	* with the core backstop's text.
 	*
 	* `predicate` is a filter entry's class (`collectQueryPaths` records it per
 	* occurrence); it only matters for `op === "filter"` on a listed leaf.
 	*/
 	check(path, op, exists, predicate = "compare") {
+		if (!exists(path)) return {
+			path,
+			message: `Unknown field "${path}"`
+		};
 		const { kind, parent } = classifyQueryPath(this, path);
 		if (kind === "nav") {
 			if (parent === void 0) return {
@@ -1422,10 +1422,6 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 				};
 			}
 		}
-		if (!exists(path)) return {
-			path,
-			message: `Unknown field "${path}"`
-		};
 		switch (kind) {
 			case "objectParent":
 				if (op === "select") return void 0;
@@ -1536,7 +1532,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	metaCacheKey() {
 		return this.capabilities;
 	}
-	/** Bound once: the field-existence check the gate hands to `capabilities.check`. */
+	/** Bound once: the visibility check ({@link hasField}) the gate hands to `capabilities.check`. */
 	_exists = (path) => this.hasField(path);
 	_preferredIdSet;
 	_overlayIsNoOp;
@@ -1589,6 +1585,20 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		for (const [path, entry] of this.readable.flatMap) if (entry?.metadata?.has?.(annotation)) out.add(path);
 		return out;
 	}
+	/**
+	* THE field-visibility hook: every gated path consults it before any
+	* capability check (since 0.1.133) — filter keys (inside `$and` / `$or` /
+	* `$not`, existence predicates included), `$sort`, `$select`,
+	* `$groupBy`, `$having` keys, aggregate and calendar-bucket `$field`s,
+	* `$with` relation names and sub-query paths, and the `$search` fallback
+	* fields. A path it rejects is answered exactly like a nonexistent one
+	* (`Unknown field "x"` / `Unknown relation "x"`), so override it to hide
+	* fields per request (read scopes). The default accepts every real path
+	* (`isValidFieldPath`). `/meta` does NOT consult it — prune hidden fields
+	* there with `applyMetaOverlay`. Native text search and vector search
+	* (`$vector` names an index) run inside the engine over its indexes, out of
+	* this hook's reach — keep hidden fields out of those indexes.
+	*/
 	hasField(path) {
 		if (typeof this.readable.isValidFieldPath === "function") return this.readable.isValidFieldPath(path);
 		return this.readable.flatMap.has(path);
@@ -1676,7 +1686,13 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		const withRelations = parsed.controls.$with;
 		if (withRelations?.length) {
 			const relations = this.readable.relations;
-			for (const rel of withRelations) if (!rel.name.includes(".") && !relations.has(rel.name)) return badRequest("$with", `Unknown relation "${rel.name}"`, `Unknown relation "${rel.name}" in $with. Available relations: ${[...relations.keys()].join(", ") || "(none)"}`);
+			for (const rel of withRelations) {
+				const dot = rel.name.indexOf(".");
+				if (!(dot === -1 ? relations.has(rel.name) && this.hasField(rel.name) : this.hasField(rel.name.slice(0, dot)))) {
+					const visible = [...relations.keys()].filter((name) => this.hasField(name));
+					return badRequest("$with", `Unknown relation "${rel.name}"`, `Unknown relation "${rel.name}" in $with. Available relations: ${visible.join(", ") || "(none)"}`);
+				}
+			}
 		}
 	}
 	/**
@@ -1913,10 +1929,11 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	/** First `@db.writeOnly` field referenced by `$groupBy` / aggregate `$select`, or undefined. */
 	_findWriteOnlyInAggregate(groupBy, select) {
 		if (this._writeOnlySet.size === 0) return void 0;
-		for (const f of groupBy) if (this._writeOnlySet.has(f)) return f;
+		const sealed = (f) => this._writeOnlySet.has(f) && this.hasField(f);
+		for (const f of groupBy) if (sealed(f)) return f;
 		if (Array.isArray(select)) for (const item of select) {
 			const field = typeof item === "string" ? item : item.$field;
-			if (field && this._writeOnlySet.has(field)) return field;
+			if (field && sealed(field)) return field;
 		}
 	}
 	/**
@@ -1928,9 +1945,11 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	applySearchFallback(filter, controls) {
 		const term = controls.$search;
 		if (!term || controls.$vector !== void 0) return filter;
-		if (this.readable.isSearchable() || this._searchFallbackFields.length === 0) return filter;
+		if (this.readable.isSearchable()) return filter;
+		const fields = this._searchFallbackFields.filter((f) => this.hasField(f));
+		if (fields.length === 0) return filter;
 		const rx = `/${term.replace(/[.*+?^${}()|[\]\\/]/g, String.raw`\$&`)}/i`;
-		const fragment = { $or: this._searchFallbackFields.map((f) => ({ [f]: { $regex: rx } })) };
+		const fragment = { $or: fields.map((f) => ({ [f]: { $regex: rx } })) };
 		return filter && Object.keys(filter).length > 0 ? { $and: [filter, fragment] } : fragment;
 	}
 	/**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/moost-db",
-  "version": "0.1.132",
+  "version": "0.1.133",
   "description": "Generic database controller for Moost with Atscript.",
   "keywords": [
     "annotations",
@@ -43,14 +43,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@uniqu/url": "^0.1.9",
-    "@atscript/db-memory": "^0.1.132"
+    "@uniqu/url": "^0.1.10",
+    "@atscript/db-memory": "^0.1.133"
   },
   "devDependencies": {
     "@atscript/core": "^0.1.92",
     "@atscript/typescript": "^0.1.92",
     "@moostjs/event-http": "^0.6.37",
-    "@uniqu/core": "^0.1.9",
+    "@uniqu/core": "^0.1.10",
     "@wooksjs/event-core": "^0.7.23",
     "@wooksjs/event-http": "^0.7.23",
     "@wooksjs/http-body": "^0.7.23",
@@ -60,11 +60,11 @@
   "peerDependencies": {
     "@atscript/typescript": "^0.1.92",
     "@moostjs/event-http": "^0.6.37",
-    "@uniqu/core": "^0.1.9",
+    "@uniqu/core": "^0.1.10",
     "@wooksjs/event-core": "^0.7.23",
     "@wooksjs/http-body": "^0.7.23",
     "moost": "^0.6.37",
-    "@atscript/db": "^0.1.132"
+    "@atscript/db": "^0.1.133"
   },
   "scripts": {
     "postinstall": "asc -f dts",