@atscript/moost-db 0.1.122 → 0.1.123

package/dist/index.cjs

@@ -625,7 +625,7 @@ let AsReadableController = class AsReadableController {
 					key,
 					value
 				};
-				if (key === "db.json" || key === "db.patch.strategy" || key.startsWith("db.default") || key === "db.http.path") return {
+				if (key === "db.json" || key === "db.patch.strategy" || key.startsWith("db.default") || key === "db.http.path" || key === "db.writeOnly") return {
 					key,
 					value
 				};
@@ -1089,6 +1089,18 @@ const GEO_CONTROLS = [
 let AsDbReadableController = class AsDbReadableController extends AsReadableController {
 	/** Reference to the underlying readable (table or view). */
 	readable;
+	/**
+	* The bound readable as a writable table. The canonical readable-controller
+	* posture is "generic reads + named `@DbAction` mutations" — action handlers
+	* write through this instead of re-importing the DbSpace module for a
+	* module-scope `getTable`. Throws when the controller is bound to a view
+	* (or any non-table readable).
+	*/
+	get table() {
+		const readable = this.readable;
+		if (readable && (readable.isView || typeof readable.insertOne !== "function")) throw new Error(`${this.constructor.name} is bound to a ${readable.isView ? "view" : "non-table readable"} ("${readable.tableName}") — .table is only available for table-bound controllers.`);
+		return readable;
+	}
 	_gates;
 	_preferredIdSet;
 	_overlayIsNoOp;
@@ -1096,11 +1108,17 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	_quantityRefByPath;
 	/** Paths the adapter vetoes for filtering (e.g. JSON storage on SQL). Symmetric with `/meta` `filterable: false`. */
 	_adapterNonFilterable;
+	/** `@db.column.searchable` paths — the `$search` fallback when the adapter has no native search. */
+	_searchFallbackFields;
+	/** `@db.writeOnly` paths — settable in writes, sealed out of every read surface. */
+	_writeOnlySet;
 	constructor(app, readable) {
 		const resolved = readable ?? resolveBoundReadable(new.target);
 		super(resolved.type, resolved.tableName, app, resolved.isView ? "view" : "table");
 		this.readable = resolved;
 		this._adapterNonFilterable = this._collectAdapterNonFilterable();
+		this._writeOnlySet = this._collectAnnotated("db.writeOnly");
+		this._searchFallbackFields = this._collectSearchFallbackFields();
 		this._gates = this._buildGates();
 		this._preferredIdSet = new Set(resolved.preferredId ?? []);
 		this._quantityRefByPath = this._collectQuantityRefs();
@@ -1140,11 +1158,25 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 				annotation: "@db.column.sortable"
 			};
 		}
+		const writeOnly = this._writeOnlySet;
+		if (writeOnly.size > 0) {
+			const prevFilter = gates.filter;
+			gates.filter = {
+				predicate: (f) => !writeOnly.has(f) && (prevFilter ? prevFilter.predicate(f) : true),
+				annotation: prevFilter?.annotation ?? "@db.column.filterable (field is @db.writeOnly)"
+			};
+			const prevSort = gates.sort;
+			gates.sort = {
+				predicate: (f) => !writeOnly.has(f) && (prevSort ? prevSort.predicate(f) : true),
+				annotation: prevSort?.annotation ?? "@db.column.sortable (field is @db.writeOnly)"
+			};
+		}
 		return gates;
 	}
 	_collectAnnotated(annotation) {
 		const out = /* @__PURE__ */ new Set();
-		for (const [path, entry] of this.readable.flatMap) if (entry.metadata.has(annotation)) out.add(path);
+		if (!this.readable.flatMap) return out;
+		for (const [path, entry] of this.readable.flatMap) if (entry?.metadata?.has?.(annotation)) out.add(path);
 		return out;
 	}
 	hasField(path) {
@@ -1369,6 +1401,72 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 			widenedSelect: resolvedProjection === null ? null : this._widenSelectForActions(envelopes, resolvedProjection)
 		};
 	}
+	/** `@db.column.searchable` paths, minus anything the adapter can't filter (JSON storage, encrypted). */
+	_collectSearchFallbackFields() {
+		const out = [];
+		if (!this.readable.fieldDescriptors) return out;
+		for (const fd of this.readable.fieldDescriptors) {
+			if (fd.ignored) continue;
+			if (!fd.type?.metadata?.has?.("db.column.searchable")) continue;
+			if (this._adapterNonFilterable.has(fd.path)) continue;
+			if (this._writeOnlySet.has(fd.path)) continue;
+			out.push(fd.path);
+		}
+		return out;
+	}
+	/**
+	* Removes `@db.writeOnly` fields from any `$select` shape — and forces an
+	* exclusion when no projection was requested — so sealed values never leave
+	* the database on a read. Runs AFTER `transformProjection` so permission
+	* overlays compose (they see the wire `$select`; this guarantees the seal on
+	* whatever they return).
+	*/
+	_sealProjection(select) {
+		const writeOnly = this._writeOnlySet;
+		if (writeOnly.size === 0) return select;
+		const exclusion = () => {
+			const out = {};
+			for (const f of writeOnly) out[f] = 0;
+			return out;
+		};
+		if (select === void 0) return exclusion();
+		if (Array.isArray(select)) {
+			const kept = select.filter((item) => typeof item === "string" ? !writeOnly.has(item) : !writeOnly.has(item.$field ?? ""));
+			return kept.length > 0 ? kept : exclusion();
+		}
+		const entries = Object.entries(select);
+		if (entries.length > 0 && (entries[0][1] === 1 || entries[0][1] === true)) {
+			const out = {};
+			for (const [k, v] of entries) if (!writeOnly.has(k)) out[k] = v;
+			return Object.keys(out).length > 0 ? out : exclusion();
+		}
+		const out = { ...select };
+		for (const f of writeOnly) out[f] = 0;
+		return out;
+	}
+	/** 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;
+		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;
+		}
+	}
+	/**
+	* Merges the `$search` fallback into the filter: a case-insensitive literal
+	* substring match OR'd across the `@db.column.searchable` fields, `$and`-combined
+	* with the existing filter. Applies only when the adapter has no native search
+	* (native wins) and the request isn't a vector search (`$vector` consumes the term).
+	*/
+	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;
+		const rx = `/${term.replace(/[.*+?^${}()|[\]\\/]/g, String.raw`\$&`)}/i`;
+		const fragment = { $or: this._searchFallbackFields.map((f) => ({ [f]: { $regex: rx } })) };
+		return filter && Object.keys(filter).length > 0 ? { $and: [filter, fragment] } : fragment;
+	}
 	async _resolveReadStrategy(controls) {
 		const searchTerm = controls.$search;
 		const indexName = controls.$index;
@@ -1439,14 +1537,18 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		const gateError = this.checkGates(parsed.filter, controls, this._gates);
 		if (gateError) return gateError;
 		if (groupBy?.length) {
-			const filter = await this.transformFilter(parsed.filter);
+			const sealed = this._findWriteOnlyInAggregate(groupBy, controls.$select);
+			if (sealed) return new _moostjs_event_http.HttpError(400, `Field "${sealed}" is @db.writeOnly and cannot be aggregated`);
+			const filter = this.applySearchFallback(await this.transformFilter(parsed.filter), controls);
 			return this.readable.aggregate({
 				filter,
 				controls,
 				insights: parsed.insights
 			});
 		}
-		const [filter, rawSelect] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
+		const [transformedFilter, transformedSelect] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
+		const filter = this.applySearchFallback(transformedFilter, controls);
+		const rawSelect = this._sealProjection(transformedSelect);
 		if (controls.$count) return this.readable.count({
 			filter,
 			controls: {
@@ -1488,7 +1590,9 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		const page = Math.max(Number(controls.$page || 1), 1);
 		const size = Math.max(Number(controls.$size || 10), 1);
 		const skip = (page - 1) * size;
-		const [filter, rawSelect] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
+		const [transformedFilter, transformedSelect] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
+		const filter = this.applySearchFallback(transformedFilter, controls);
+		const rawSelect = this._sealProjection(transformedSelect);
 		const select = this.widenPreferredIdProjection(rawSelect);
 		if (select instanceof _moostjs_event_http.HttpError) return select;
 		const threshold = controls.$threshold ? Number(controls.$threshold) : void 0;
@@ -1545,8 +1649,8 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		}
 		const gateError = this.checkGates(parsed.filter, controls, this._gates);
 		if (gateError) return gateError;
-		const [filter, rawSelect] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
-		const select = this.widenPreferredIdProjection(rawSelect);
+		const [filter, transformedSelect] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
+		const select = this.widenPreferredIdProjection(this._sealProjection(transformedSelect));
 		if (select instanceof _moostjs_event_http.HttpError) return select;
 		const paginated = controls.$page !== void 0 || controls.$size !== void 0;
 		const page = Math.max(Number(controls.$page || 1), 1);
@@ -1605,7 +1709,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		const error = this.validateParsed(parsed, "getOne");
 		if (error) return error;
 		const rawSelect = await this.transformProjection(parsed.controls.$select);
-		const select = this.widenPreferredIdProjection(rawSelect);
+		const select = this.widenPreferredIdProjection(this._sealProjection(rawSelect));
 		if (select instanceof _moostjs_event_http.HttpError) return select;
 		return this._findByIdAndAugment(id, parsed.controls, select);
 	}
@@ -1620,7 +1724,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		const { parsed } = this.parseControlsOnlyFromUrl(url);
 		this._coerceActionsControl(parsed.controls);
 		const rawSelect = await this.transformProjection(parsed.controls.$select);
-		const select = this.widenPreferredIdProjection(rawSelect);
+		const select = this.widenPreferredIdProjection(this._sealProjection(rawSelect));
 		if (select instanceof _moostjs_event_http.HttpError) return select;
 		return this._findByIdAndAugment(idObj, parsed.controls, select);
 	}
@@ -1686,9 +1790,14 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 			};
 			if (fd.encrypted) fields[fd.path].encrypted = true;
 			if (geoIndexedPhysical.has(fd.physicalName)) fields[fd.path].geo = true;
+			if (this._writeOnlySet.has(fd.path)) {
+				fields[fd.path].writeOnly = true;
+				fields[fd.path].filterable = false;
+				fields[fd.path].sortable = false;
+			}
 		}
 		return {
-			searchable: this.readable.isSearchable(),
+			searchable: this.readable.isSearchable() || this._searchFallbackFields.length > 0,
 			vectorSearchable: this.readable.isVectorSearchable(),
 			geoSearchable: this._isGeoSearchable(),
 			searchIndexes: this.readable.getSearchIndexes(),
@@ -1789,10 +1898,6 @@ function liftVersionToCas(payload, versionColumn) {
 	return true;
 }
 let AsDbController = class AsDbController extends AsDbReadableController {
-	/** Reference to the underlying table (typed for write access). */
-	get table() {
-		return this.readable;
-	}
 	constructor(app, table) {
 		super(app, table);
 	}
@@ -2228,26 +2333,37 @@ AsJsonValueHelpController = __decorate([(0, moost.Inherit)(), __decorateMetadata
 //#endregion
 //#region src/assert-exposed.ts
 /**
-* Dev-mode wiring assertion: warns for every model annotated with
-* `@db.http.path` that has no registered db controller.
+* Dev-mode wiring assertion: warns for every model that should have a
+* registered db controller but doesn't.
+*
+* Default mode audits models annotated with `@db.http.path`. With
+* `{ all: true }` every passed model is a candidate (minus `exclude`) — the
+* right mode for repos that mount everything through decorator prefixes
+* (`@TableController(Model, 'db/x')`) and keep a generated model manifest.
 *
 * Call AFTER `await app.init()` (controller bindings are collected during
 * init). Detection reads the binding metadata written by `@TableController` /
 * `@ReadableController` / `@ViewController`, so it covers the model-token and
-* instance forms; lazy-factory bindings can't name their model until resolved
-* and are ignored.
+* instance forms; **lazy-factory bindings can't name their model until
+* resolved and are invisible to the check** — with `all: true` such models
+* will warn even though they are exposed; list them in `exclude`.
 *
 * Returns the list of unexposed models so callers can escalate (e.g. throw in
 * CI):
 *
 * ```ts
 * await app.init()
-* const missing = assertExposed(app, atscriptModels)
+* const missing = assertExposed(app, atscriptModels, {
+*   all: true,
+*   exclude: [EmbeddingCache], // internal on purpose
+* })
 * if (missing.length && process.env.CI) throw new Error("unexposed models")
 * ```
 */
 function assertExposed(app, models, options) {
 	const logger = options?.logger ?? console;
+	const auditAll = options?.all === true;
+	const excluded = new Set(options?.exclude ?? []);
 	const exposed = /* @__PURE__ */ new Set();
 	for (const overview of app.getControllersOverview()) {
 		const model = findReadableBinding(overview.type)?.model;
@@ -2255,11 +2371,12 @@ function assertExposed(app, models, options) {
 	}
 	const missing = [];
 	for (const model of models) {
-		if (!model.metadata.has("db.http.path")) continue;
-		if (exposed.has(model)) continue;
+		const httpPath = model.metadata.get("db.http.path");
+		if (!auditAll && httpPath === void 0) continue;
+		if (excluded.has(model) || exposed.has(model)) continue;
 		missing.push(model);
-		const path = model.metadata.get("db.http.path");
-		logger.warn(`[moost-db] Model "${model.id ?? path}" declares @db.http.path "${path}" but no registered controller is bound to it. Did you forget to register its controller?`);
+		const name = model.id ?? httpPath ?? "(unnamed model)";
+		logger.warn(httpPath === void 0 ? `[moost-db] Model "${name}" has no registered controller bound to it. Register its controller, or list it in assertExposed's \`exclude\` if it is internal on purpose.` : `[moost-db] Model "${name}" declares @db.http.path "${httpPath}" but no registered controller is bound to it. Did you forget to register its controller?`);
 	}
 	return missing;
 }

package/dist/index.d.cts

@@ -174,6 +174,14 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
 declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> extends AsReadableController<T, DataType> {
   /** Reference to the underlying readable (table or view). */
   protected readable: AtscriptDbReadable<T>;
+  /**
+   * The bound readable as a writable table. The canonical readable-controller
+   * posture is "generic reads + named `@DbAction` mutations" — action handlers
+   * write through this instead of re-importing the DbSpace module for a
+   * module-scope `getTable`. Throws when the controller is bound to a view
+   * (or any non-table readable).
+   */
+  protected get table(): AtscriptDbTable<T>;
   private readonly _gates;
   private readonly _preferredIdSet;
   private readonly _overlayIsNoOp;
@@ -181,6 +189,10 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private readonly _quantityRefByPath;
   /** Paths the adapter vetoes for filtering (e.g. JSON storage on SQL). Symmetric with `/meta` `filterable: false`. */
   private readonly _adapterNonFilterable;
+  /** `@db.column.searchable` paths — the `$search` fallback when the adapter has no native search. */
+  private readonly _searchFallbackFields;
+  /** `@db.writeOnly` paths — settable in writes, sealed out of every read surface. */
+  private readonly _writeOnlySet;
   constructor(app: Moost, readable?: AtscriptDbReadable<T>);
   private _collectAdapterNonFilterable;
   private _collectQuantityRefs;
@@ -239,6 +251,25 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   /** Returns a widened `$select` only when at least one `requiredFields` entry is missing; `null` means "no widening needed". */
   private _widenSelectForActions;
   private _prepareAugmentation;
+  /** `@db.column.searchable` paths, minus anything the adapter can't filter (JSON storage, encrypted). */
+  private _collectSearchFallbackFields;
+  /**
+   * Removes `@db.writeOnly` fields from any `$select` shape — and forces an
+   * exclusion when no projection was requested — so sealed values never leave
+   * the database on a read. Runs AFTER `transformProjection` so permission
+   * overlays compose (they see the wire `$select`; this guarantees the seal on
+   * whatever they return).
+   */
+  private _sealProjection;
+  /** First `@db.writeOnly` field referenced by `$groupBy` / aggregate `$select`, or undefined. */
+  private _findWriteOnlyInAggregate;
+  /**
+   * Merges the `$search` fallback into the filter: a case-insensitive literal
+   * substring match OR'd across the `@db.column.searchable` fields, `$and`-combined
+   * with the existing filter. Applies only when the adapter has no native search
+   * (native wins) and the request isn't a vector search (`$vector` consumes the term).
+   */
+  protected applySearchFallback(filter: FilterExpr | undefined, controls: Record<string, unknown>): FilterExpr | undefined;
   private _resolveReadStrategy;
   /**
    * Shared `query` / `pages` pipeline: prepare actions augmentation + read
@@ -321,8 +352,6 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
  * ```
  */
 declare class AsDbController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> extends AsDbReadableController<T, DataType> {
-  /** Reference to the underlying table (typed for write access). */
-  protected get table(): AtscriptDbTable<T>;
   constructor(app: Moost, table?: AtscriptDbTable<T>);
   protected buildCrud(): TCrudPermissions$1;
   /**
@@ -908,28 +937,50 @@ declare function findReadableBinding(ctor: Function | undefined): TReadableBindi
 declare function resolveBoundReadable(ctor: Function | undefined): AtscriptDbReadable<any>;
 //#endregion
 //#region src/assert-exposed.d.ts
-/** Minimal logger surface for {@link assertExposed}. */
+/** Options for {@link assertExposed}. */
 interface TAssertExposedOptions {
   logger?: {
     warn: (...args: unknown[]) => void;
   };
+  /**
+   * Audit EVERY passed model, not only those annotated `@db.http.path`.
+   * Use with a generated model manifest so exposure completeness is guarded
+   * the same way sync completeness is. Deliberately-internal collections go
+   * in {@link exclude}.
+   */
+  all?: boolean;
+  /**
+   * Models exempt from the audit (internal-on-purpose collections). Only
+   * meaningful with {@link all} — the default `@db.http.path` mode is already
+   * opt-in per model.
+   */
+  exclude?: readonly TAtscriptAnnotatedType[];
 }
 /**
- * Dev-mode wiring assertion: warns for every model annotated with
- * `@db.http.path` that has no registered db controller.
+ * Dev-mode wiring assertion: warns for every model that should have a
+ * registered db controller but doesn't.
+ *
+ * Default mode audits models annotated with `@db.http.path`. With
+ * `{ all: true }` every passed model is a candidate (minus `exclude`) — the
+ * right mode for repos that mount everything through decorator prefixes
+ * (`@TableController(Model, 'db/x')`) and keep a generated model manifest.
  *
  * Call AFTER `await app.init()` (controller bindings are collected during
  * init). Detection reads the binding metadata written by `@TableController` /
  * `@ReadableController` / `@ViewController`, so it covers the model-token and
- * instance forms; lazy-factory bindings can't name their model until resolved
- * and are ignored.
+ * instance forms; **lazy-factory bindings can't name their model until
+ * resolved and are invisible to the check** — with `all: true` such models
+ * will warn even though they are exposed; list them in `exclude`.
  *
  * Returns the list of unexposed models so callers can escalate (e.g. throw in
  * CI):
  *
  * ```ts
  * await app.init()
- * const missing = assertExposed(app, atscriptModels)
+ * const missing = assertExposed(app, atscriptModels, {
+ *   all: true,
+ *   exclude: [EmbeddingCache], // internal on purpose
+ * })
  * if (missing.length && process.env.CI) throw new Error("unexposed models")
  * ```
  */

package/dist/index.d.mts

@@ -174,6 +174,14 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
 declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> extends AsReadableController<T, DataType> {
   /** Reference to the underlying readable (table or view). */
   protected readable: AtscriptDbReadable<T>;
+  /**
+   * The bound readable as a writable table. The canonical readable-controller
+   * posture is "generic reads + named `@DbAction` mutations" — action handlers
+   * write through this instead of re-importing the DbSpace module for a
+   * module-scope `getTable`. Throws when the controller is bound to a view
+   * (or any non-table readable).
+   */
+  protected get table(): AtscriptDbTable<T>;
   private readonly _gates;
   private readonly _preferredIdSet;
   private readonly _overlayIsNoOp;
@@ -181,6 +189,10 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private readonly _quantityRefByPath;
   /** Paths the adapter vetoes for filtering (e.g. JSON storage on SQL). Symmetric with `/meta` `filterable: false`. */
   private readonly _adapterNonFilterable;
+  /** `@db.column.searchable` paths — the `$search` fallback when the adapter has no native search. */
+  private readonly _searchFallbackFields;
+  /** `@db.writeOnly` paths — settable in writes, sealed out of every read surface. */
+  private readonly _writeOnlySet;
   constructor(app: Moost, readable?: AtscriptDbReadable<T>);
   private _collectAdapterNonFilterable;
   private _collectQuantityRefs;
@@ -239,6 +251,25 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   /** Returns a widened `$select` only when at least one `requiredFields` entry is missing; `null` means "no widening needed". */
   private _widenSelectForActions;
   private _prepareAugmentation;
+  /** `@db.column.searchable` paths, minus anything the adapter can't filter (JSON storage, encrypted). */
+  private _collectSearchFallbackFields;
+  /**
+   * Removes `@db.writeOnly` fields from any `$select` shape — and forces an
+   * exclusion when no projection was requested — so sealed values never leave
+   * the database on a read. Runs AFTER `transformProjection` so permission
+   * overlays compose (they see the wire `$select`; this guarantees the seal on
+   * whatever they return).
+   */
+  private _sealProjection;
+  /** First `@db.writeOnly` field referenced by `$groupBy` / aggregate `$select`, or undefined. */
+  private _findWriteOnlyInAggregate;
+  /**
+   * Merges the `$search` fallback into the filter: a case-insensitive literal
+   * substring match OR'd across the `@db.column.searchable` fields, `$and`-combined
+   * with the existing filter. Applies only when the adapter has no native search
+   * (native wins) and the request isn't a vector search (`$vector` consumes the term).
+   */
+  protected applySearchFallback(filter: FilterExpr | undefined, controls: Record<string, unknown>): FilterExpr | undefined;
   private _resolveReadStrategy;
   /**
    * Shared `query` / `pages` pipeline: prepare actions augmentation + read
@@ -321,8 +352,6 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
  * ```
  */
 declare class AsDbController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> extends AsDbReadableController<T, DataType> {
-  /** Reference to the underlying table (typed for write access). */
-  protected get table(): AtscriptDbTable<T>;
   constructor(app: Moost, table?: AtscriptDbTable<T>);
   protected buildCrud(): TCrudPermissions$1;
   /**
@@ -908,28 +937,50 @@ declare function findReadableBinding(ctor: Function | undefined): TReadableBindi
 declare function resolveBoundReadable(ctor: Function | undefined): AtscriptDbReadable<any>;
 //#endregion
 //#region src/assert-exposed.d.ts
-/** Minimal logger surface for {@link assertExposed}. */
+/** Options for {@link assertExposed}. */
 interface TAssertExposedOptions {
   logger?: {
     warn: (...args: unknown[]) => void;
   };
+  /**
+   * Audit EVERY passed model, not only those annotated `@db.http.path`.
+   * Use with a generated model manifest so exposure completeness is guarded
+   * the same way sync completeness is. Deliberately-internal collections go
+   * in {@link exclude}.
+   */
+  all?: boolean;
+  /**
+   * Models exempt from the audit (internal-on-purpose collections). Only
+   * meaningful with {@link all} — the default `@db.http.path` mode is already
+   * opt-in per model.
+   */
+  exclude?: readonly TAtscriptAnnotatedType[];
 }
 /**
- * Dev-mode wiring assertion: warns for every model annotated with
- * `@db.http.path` that has no registered db controller.
+ * Dev-mode wiring assertion: warns for every model that should have a
+ * registered db controller but doesn't.
+ *
+ * Default mode audits models annotated with `@db.http.path`. With
+ * `{ all: true }` every passed model is a candidate (minus `exclude`) — the
+ * right mode for repos that mount everything through decorator prefixes
+ * (`@TableController(Model, 'db/x')`) and keep a generated model manifest.
  *
  * Call AFTER `await app.init()` (controller bindings are collected during
  * init). Detection reads the binding metadata written by `@TableController` /
  * `@ReadableController` / `@ViewController`, so it covers the model-token and
- * instance forms; lazy-factory bindings can't name their model until resolved
- * and are ignored.
+ * instance forms; **lazy-factory bindings can't name their model until
+ * resolved and are invisible to the check** — with `all: true` such models
+ * will warn even though they are exposed; list them in `exclude`.
  *
  * Returns the list of unexposed models so callers can escalate (e.g. throw in
  * CI):
  *
  * ```ts
  * await app.init()
- * const missing = assertExposed(app, atscriptModels)
+ * const missing = assertExposed(app, atscriptModels, {
+ *   all: true,
+ *   exclude: [EmbeddingCache], // internal on purpose
+ * })
  * if (missing.length && process.env.CI) throw new Error("unexposed models")
  * ```
  */

package/dist/index.mjs

@@ -624,7 +624,7 @@ let AsReadableController = class AsReadableController {
 					key,
 					value
 				};
-				if (key === "db.json" || key === "db.patch.strategy" || key.startsWith("db.default") || key === "db.http.path") return {
+				if (key === "db.json" || key === "db.patch.strategy" || key.startsWith("db.default") || key === "db.http.path" || key === "db.writeOnly") return {
 					key,
 					value
 				};
@@ -1088,6 +1088,18 @@ const GEO_CONTROLS = [
 let AsDbReadableController = class AsDbReadableController extends AsReadableController {
 	/** Reference to the underlying readable (table or view). */
 	readable;
+	/**
+	* The bound readable as a writable table. The canonical readable-controller
+	* posture is "generic reads + named `@DbAction` mutations" — action handlers
+	* write through this instead of re-importing the DbSpace module for a
+	* module-scope `getTable`. Throws when the controller is bound to a view
+	* (or any non-table readable).
+	*/
+	get table() {
+		const readable = this.readable;
+		if (readable && (readable.isView || typeof readable.insertOne !== "function")) throw new Error(`${this.constructor.name} is bound to a ${readable.isView ? "view" : "non-table readable"} ("${readable.tableName}") — .table is only available for table-bound controllers.`);
+		return readable;
+	}
 	_gates;
 	_preferredIdSet;
 	_overlayIsNoOp;
@@ -1095,11 +1107,17 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	_quantityRefByPath;
 	/** Paths the adapter vetoes for filtering (e.g. JSON storage on SQL). Symmetric with `/meta` `filterable: false`. */
 	_adapterNonFilterable;
+	/** `@db.column.searchable` paths — the `$search` fallback when the adapter has no native search. */
+	_searchFallbackFields;
+	/** `@db.writeOnly` paths — settable in writes, sealed out of every read surface. */
+	_writeOnlySet;
 	constructor(app, readable) {
 		const resolved = readable ?? resolveBoundReadable(new.target);
 		super(resolved.type, resolved.tableName, app, resolved.isView ? "view" : "table");
 		this.readable = resolved;
 		this._adapterNonFilterable = this._collectAdapterNonFilterable();
+		this._writeOnlySet = this._collectAnnotated("db.writeOnly");
+		this._searchFallbackFields = this._collectSearchFallbackFields();
 		this._gates = this._buildGates();
 		this._preferredIdSet = new Set(resolved.preferredId ?? []);
 		this._quantityRefByPath = this._collectQuantityRefs();
@@ -1139,11 +1157,25 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 				annotation: "@db.column.sortable"
 			};
 		}
+		const writeOnly = this._writeOnlySet;
+		if (writeOnly.size > 0) {
+			const prevFilter = gates.filter;
+			gates.filter = {
+				predicate: (f) => !writeOnly.has(f) && (prevFilter ? prevFilter.predicate(f) : true),
+				annotation: prevFilter?.annotation ?? "@db.column.filterable (field is @db.writeOnly)"
+			};
+			const prevSort = gates.sort;
+			gates.sort = {
+				predicate: (f) => !writeOnly.has(f) && (prevSort ? prevSort.predicate(f) : true),
+				annotation: prevSort?.annotation ?? "@db.column.sortable (field is @db.writeOnly)"
+			};
+		}
 		return gates;
 	}
 	_collectAnnotated(annotation) {
 		const out = /* @__PURE__ */ new Set();
-		for (const [path, entry] of this.readable.flatMap) if (entry.metadata.has(annotation)) out.add(path);
+		if (!this.readable.flatMap) return out;
+		for (const [path, entry] of this.readable.flatMap) if (entry?.metadata?.has?.(annotation)) out.add(path);
 		return out;
 	}
 	hasField(path) {
@@ -1368,6 +1400,72 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 			widenedSelect: resolvedProjection === null ? null : this._widenSelectForActions(envelopes, resolvedProjection)
 		};
 	}
+	/** `@db.column.searchable` paths, minus anything the adapter can't filter (JSON storage, encrypted). */
+	_collectSearchFallbackFields() {
+		const out = [];
+		if (!this.readable.fieldDescriptors) return out;
+		for (const fd of this.readable.fieldDescriptors) {
+			if (fd.ignored) continue;
+			if (!fd.type?.metadata?.has?.("db.column.searchable")) continue;
+			if (this._adapterNonFilterable.has(fd.path)) continue;
+			if (this._writeOnlySet.has(fd.path)) continue;
+			out.push(fd.path);
+		}
+		return out;
+	}
+	/**
+	* Removes `@db.writeOnly` fields from any `$select` shape — and forces an
+	* exclusion when no projection was requested — so sealed values never leave
+	* the database on a read. Runs AFTER `transformProjection` so permission
+	* overlays compose (they see the wire `$select`; this guarantees the seal on
+	* whatever they return).
+	*/
+	_sealProjection(select) {
+		const writeOnly = this._writeOnlySet;
+		if (writeOnly.size === 0) return select;
+		const exclusion = () => {
+			const out = {};
+			for (const f of writeOnly) out[f] = 0;
+			return out;
+		};
+		if (select === void 0) return exclusion();
+		if (Array.isArray(select)) {
+			const kept = select.filter((item) => typeof item === "string" ? !writeOnly.has(item) : !writeOnly.has(item.$field ?? ""));
+			return kept.length > 0 ? kept : exclusion();
+		}
+		const entries = Object.entries(select);
+		if (entries.length > 0 && (entries[0][1] === 1 || entries[0][1] === true)) {
+			const out = {};
+			for (const [k, v] of entries) if (!writeOnly.has(k)) out[k] = v;
+			return Object.keys(out).length > 0 ? out : exclusion();
+		}
+		const out = { ...select };
+		for (const f of writeOnly) out[f] = 0;
+		return out;
+	}
+	/** 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;
+		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;
+		}
+	}
+	/**
+	* Merges the `$search` fallback into the filter: a case-insensitive literal
+	* substring match OR'd across the `@db.column.searchable` fields, `$and`-combined
+	* with the existing filter. Applies only when the adapter has no native search
+	* (native wins) and the request isn't a vector search (`$vector` consumes the term).
+	*/
+	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;
+		const rx = `/${term.replace(/[.*+?^${}()|[\]\\/]/g, String.raw`\$&`)}/i`;
+		const fragment = { $or: this._searchFallbackFields.map((f) => ({ [f]: { $regex: rx } })) };
+		return filter && Object.keys(filter).length > 0 ? { $and: [filter, fragment] } : fragment;
+	}
 	async _resolveReadStrategy(controls) {
 		const searchTerm = controls.$search;
 		const indexName = controls.$index;
@@ -1438,14 +1536,18 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		const gateError = this.checkGates(parsed.filter, controls, this._gates);
 		if (gateError) return gateError;
 		if (groupBy?.length) {
-			const filter = await this.transformFilter(parsed.filter);
+			const sealed = this._findWriteOnlyInAggregate(groupBy, controls.$select);
+			if (sealed) return new HttpError(400, `Field "${sealed}" is @db.writeOnly and cannot be aggregated`);
+			const filter = this.applySearchFallback(await this.transformFilter(parsed.filter), controls);
 			return this.readable.aggregate({
 				filter,
 				controls,
 				insights: parsed.insights
 			});
 		}
-		const [filter, rawSelect] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
+		const [transformedFilter, transformedSelect] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
+		const filter = this.applySearchFallback(transformedFilter, controls);
+		const rawSelect = this._sealProjection(transformedSelect);
 		if (controls.$count) return this.readable.count({
 			filter,
 			controls: {
@@ -1487,7 +1589,9 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		const page = Math.max(Number(controls.$page || 1), 1);
 		const size = Math.max(Number(controls.$size || 10), 1);
 		const skip = (page - 1) * size;
-		const [filter, rawSelect] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
+		const [transformedFilter, transformedSelect] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
+		const filter = this.applySearchFallback(transformedFilter, controls);
+		const rawSelect = this._sealProjection(transformedSelect);
 		const select = this.widenPreferredIdProjection(rawSelect);
 		if (select instanceof HttpError) return select;
 		const threshold = controls.$threshold ? Number(controls.$threshold) : void 0;
@@ -1544,8 +1648,8 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		}
 		const gateError = this.checkGates(parsed.filter, controls, this._gates);
 		if (gateError) return gateError;
-		const [filter, rawSelect] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
-		const select = this.widenPreferredIdProjection(rawSelect);
+		const [filter, transformedSelect] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
+		const select = this.widenPreferredIdProjection(this._sealProjection(transformedSelect));
 		if (select instanceof HttpError) return select;
 		const paginated = controls.$page !== void 0 || controls.$size !== void 0;
 		const page = Math.max(Number(controls.$page || 1), 1);
@@ -1604,7 +1708,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		const error = this.validateParsed(parsed, "getOne");
 		if (error) return error;
 		const rawSelect = await this.transformProjection(parsed.controls.$select);
-		const select = this.widenPreferredIdProjection(rawSelect);
+		const select = this.widenPreferredIdProjection(this._sealProjection(rawSelect));
 		if (select instanceof HttpError) return select;
 		return this._findByIdAndAugment(id, parsed.controls, select);
 	}
@@ -1619,7 +1723,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		const { parsed } = this.parseControlsOnlyFromUrl(url);
 		this._coerceActionsControl(parsed.controls);
 		const rawSelect = await this.transformProjection(parsed.controls.$select);
-		const select = this.widenPreferredIdProjection(rawSelect);
+		const select = this.widenPreferredIdProjection(this._sealProjection(rawSelect));
 		if (select instanceof HttpError) return select;
 		return this._findByIdAndAugment(idObj, parsed.controls, select);
 	}
@@ -1685,9 +1789,14 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 			};
 			if (fd.encrypted) fields[fd.path].encrypted = true;
 			if (geoIndexedPhysical.has(fd.physicalName)) fields[fd.path].geo = true;
+			if (this._writeOnlySet.has(fd.path)) {
+				fields[fd.path].writeOnly = true;
+				fields[fd.path].filterable = false;
+				fields[fd.path].sortable = false;
+			}
 		}
 		return {
-			searchable: this.readable.isSearchable(),
+			searchable: this.readable.isSearchable() || this._searchFallbackFields.length > 0,
 			vectorSearchable: this.readable.isVectorSearchable(),
 			geoSearchable: this._isGeoSearchable(),
 			searchIndexes: this.readable.getSearchIndexes(),
@@ -1788,10 +1897,6 @@ function liftVersionToCas(payload, versionColumn) {
 	return true;
 }
 let AsDbController = class AsDbController extends AsDbReadableController {
-	/** Reference to the underlying table (typed for write access). */
-	get table() {
-		return this.readable;
-	}
 	constructor(app, table) {
 		super(app, table);
 	}
@@ -2227,26 +2332,37 @@ AsJsonValueHelpController = __decorate([Inherit(), __decorateMetadata("design:pa
 //#endregion
 //#region src/assert-exposed.ts
 /**
-* Dev-mode wiring assertion: warns for every model annotated with
-* `@db.http.path` that has no registered db controller.
+* Dev-mode wiring assertion: warns for every model that should have a
+* registered db controller but doesn't.
+*
+* Default mode audits models annotated with `@db.http.path`. With
+* `{ all: true }` every passed model is a candidate (minus `exclude`) — the
+* right mode for repos that mount everything through decorator prefixes
+* (`@TableController(Model, 'db/x')`) and keep a generated model manifest.
 *
 * Call AFTER `await app.init()` (controller bindings are collected during
 * init). Detection reads the binding metadata written by `@TableController` /
 * `@ReadableController` / `@ViewController`, so it covers the model-token and
-* instance forms; lazy-factory bindings can't name their model until resolved
-* and are ignored.
+* instance forms; **lazy-factory bindings can't name their model until
+* resolved and are invisible to the check** — with `all: true` such models
+* will warn even though they are exposed; list them in `exclude`.
 *
 * Returns the list of unexposed models so callers can escalate (e.g. throw in
 * CI):
 *
 * ```ts
 * await app.init()
-* const missing = assertExposed(app, atscriptModels)
+* const missing = assertExposed(app, atscriptModels, {
+*   all: true,
+*   exclude: [EmbeddingCache], // internal on purpose
+* })
 * if (missing.length && process.env.CI) throw new Error("unexposed models")
 * ```
 */
 function assertExposed(app, models, options) {
 	const logger = options?.logger ?? console;
+	const auditAll = options?.all === true;
+	const excluded = new Set(options?.exclude ?? []);
 	const exposed = /* @__PURE__ */ new Set();
 	for (const overview of app.getControllersOverview()) {
 		const model = findReadableBinding(overview.type)?.model;
@@ -2254,11 +2370,12 @@ function assertExposed(app, models, options) {
 	}
 	const missing = [];
 	for (const model of models) {
-		if (!model.metadata.has("db.http.path")) continue;
-		if (exposed.has(model)) continue;
+		const httpPath = model.metadata.get("db.http.path");
+		if (!auditAll && httpPath === void 0) continue;
+		if (excluded.has(model) || exposed.has(model)) continue;
 		missing.push(model);
-		const path = model.metadata.get("db.http.path");
-		logger.warn(`[moost-db] Model "${model.id ?? path}" declares @db.http.path "${path}" but no registered controller is bound to it. Did you forget to register its controller?`);
+		const name = model.id ?? httpPath ?? "(unnamed model)";
+		logger.warn(httpPath === void 0 ? `[moost-db] Model "${name}" has no registered controller bound to it. Register its controller, or list it in assertExposed's \`exclude\` if it is internal on purpose.` : `[moost-db] Model "${name}" declares @db.http.path "${httpPath}" but no registered controller is bound to it. Did you forget to register its controller?`);
 	}
 	return missing;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/moost-db",
-  "version": "0.1.122",
+  "version": "0.1.123",
   "description": "Generic database controller for Moost with Atscript.",
   "keywords": [
     "annotations",
@@ -44,7 +44,7 @@
   },
   "dependencies": {
     "@uniqu/url": "^0.1.7",
-    "@atscript/db-memory": "^0.1.122"
+    "@atscript/db-memory": "^0.1.123"
   },
   "devDependencies": {
     "@atscript/core": "^0.1.85",
@@ -64,7 +64,7 @@
     "@wooksjs/event-core": "^0.7.21",
     "@wooksjs/http-body": "^0.7.21",
     "moost": "^0.6.33",
-    "@atscript/db": "^0.1.122"
+    "@atscript/db": "^0.1.123"
   },
   "scripts": {
     "postinstall": "asc -f dts",