@atscript/db-memory 0.1.145 → 0.1.147

package/dist/index.cjs

@@ -156,18 +156,156 @@ const memoryVisitor = {
 				message: `Unsupported filter operator: ${op}`
 			}]);
 		}
+	},
+	relation(field, op, operand) {
+		return relationPredicate(void 0, field, op, operand);
 	}
 };
 /**
+* Identity of the key tuple `fields` of `row` (dot-paths read nested), or
+* `undefined` when a component is `null` / missing — a NULL key component
+* never correlates (SQL `=` semantics: `$some` false, `$none` true).
+* Every component is type-tagged (see {@link keyPart}), matching the strict
+* equality the memory filter uses everywhere (`valuesEqual`): `1` ≠ `"1"`,
+* `5n` ≠ `"5n"`, a `Date` ≠ its ISO string; `Date`s compare by instant.
+*/
+function correlationKey(row, fields) {
+	const parts = [];
+	for (const field of fields) {
+		const part = keyPart((0, _atscript_db.getPath)(row, field));
+		if (part === void 0) return;
+		parts.push(part);
+	}
+	return JSON.stringify(parts);
+}
+/**
+* Type-tagged identity of one key component, or `undefined` when it never
+* equals anything (`null` / missing, `NaN`).
+*/
+function keyPart(value) {
+	switch (typeof value) {
+		case "string": return `s:${value}`;
+		case "number": return Number.isNaN(value) ? void 0 : `n:${value === 0 ? 0 : value}`;
+		case "bigint": return `b:${value}`;
+		case "boolean": return `t:${value}`;
+		case "undefined": return;
+		default:
+			if (value === null) return void 0;
+			if (value instanceof Date) {
+				const time = value.getTime();
+				return Number.isNaN(time) ? void 0 : `d:${time}`;
+			}
+			return `o:${JSON.stringify(value, (_k, v) => typeof v === "bigint" ? `${v}n` : v)}`;
+	}
+}
+/** Source-side correlation columns of a resolved predicate (physical names). */
+function sourceColumns(node) {
+	return node.junction ? node.junction.toSource.map((p) => p.source) : node.pairs.map((p) => p.source);
+}
+/**
+* The visitor's `relation` callback: a row satisfies `$some` when its source
+* correlation tuple is in the predicate's prepared set, `$none` otherwise.
+*/
+function relationPredicate(sets, field, op, operand) {
+	const node = operand;
+	const set = (0, _atscript_db.isResolvedRelationFilter)(node) ? sets?.get(node) : void 0;
+	if (!set) throw new _atscript_db.DbError("REL_FILTER_NOT_SUPPORTED", [{
+		path: field,
+		message: `Relational predicate "${op}" on "${field}" was not prepared — call prepareRelationSets() before buildMemoryPredicate()`
+	}]);
+	const columns = sourceColumns(node);
+	const some = op === "$some";
+	return (row) => {
+		const key = correlationKey(row, columns);
+		return (key !== void 0 && set.has(key)) === some;
+	};
+}
+/**
+* Resolves every relational predicate of a TRANSLATED filter (nested ones
+* included) into a correlation set, loading each related table through
+* `load`:
+*
+* - `to` / `from`: the related rows matching the inner filter contribute their
+*   `pairs[].target` tuples — equal to the source tuple (`pairs[].source`) of
+*   every row that has such a related row.
+* - `via`: the matching related rows' `junction.toTarget[].target` tuples
+*   select junction rows (also filtered by the junction part of
+*   `@db.rel.filter`), which contribute their `junction.toSource[].junction`
+*   tuples.
+*
+* Nested predicates are prepared against the related table's rows first
+* (their source is this predicate's target). Returns `undefined` when the
+* filter holds no predicate — callers then stay on the plain synchronous path.
+*
+* @since 0.1.147
+*/
+async function prepareRelationSets(filter, load) {
+	if (!(0, _atscript_db.containsRelationFilter)(filter)) return;
+	const sets = /* @__PURE__ */ new Map();
+	await prepareLevel(filter, load, sets);
+	return sets;
+}
+/** Prepares the predicates at one level of `filter` (and, recursively, their operands). */
+async function prepareLevel(filter, load, sets) {
+	const nodes = [];
+	(0, _atscript_db.forEachResolvedRelation)(filter, (node) => nodes.push(node), false);
+	for (const node of nodes) if (!sets.has(node)) sets.set(node, await correlationSet(node, load, sets));
+}
+/** Matching rows of `adapter`'s table for `filter` (its own predicates prepared first). */
+async function matchingRows(adapter, filter, load, sets) {
+	const rows = await load(adapter);
+	if (!filter || Object.keys(filter).length === 0) return rows;
+	await prepareLevel(filter, load, sets);
+	return rows.filter(buildMemoryPredicate(filter, sets));
+}
+/** The source correlation tuples that have a related row matching `node`. */
+async function correlationSet(node, load, sets) {
+	const targets = await matchingRows(node.target.adapter, node.filter, load, sets);
+	const result = /* @__PURE__ */ new Set();
+	if (!node.junction) {
+		const columns = node.pairs.map((p) => p.target);
+		for (const row of targets) {
+			const key = correlationKey(row, columns);
+			if (key !== void 0) result.add(key);
+		}
+		return result;
+	}
+	const { junction } = node;
+	const targetKeys = /* @__PURE__ */ new Set();
+	const targetColumns = junction.toTarget.map((p) => p.target);
+	for (const row of targets) {
+		const key = correlationKey(row, targetColumns);
+		if (key !== void 0) targetKeys.add(key);
+	}
+	if (targetKeys.size === 0) return result;
+	const toTarget = junction.toTarget.map((p) => p.junction);
+	const toSource = junction.toSource.map((p) => p.junction);
+	for (const row of await matchingRows(junction.adapter, junction.filter, load, sets)) {
+		const targetKey = correlationKey(row, toTarget);
+		if (targetKey === void 0 || !targetKeys.has(targetKey)) continue;
+		const sourceKey = correlationKey(row, toSource);
+		if (sourceKey !== void 0) result.add(sourceKey);
+	}
+	return result;
+}
+/**
 * Compiles a {@link FilterExpr} into an in-memory row predicate
 * `(row) => boolean`, reusing the shared {@link walkFilter} walker so filter
 * structure matches the SQL/Mongo adapters by construction.
 *
 * An empty/absent filter (for which `walkFilter` returns `undefined`) compiles
 * to a match-everything predicate.
+*
+* A filter holding relational predicates (`ResolvedRelationFilter` operands,
+* since 0.1.147) needs `relationSets` — prepared internally by
+* `MemoryAdapter` from the related tables; a standalone call on such a
+* filter throws `REL_FILTER_NOT_SUPPORTED`.
 */
-function buildMemoryPredicate(filter) {
-	return (0, _atscript_db.walkFilter)(filter, memoryVisitor) ?? (() => true);
+function buildMemoryPredicate(filter, relationSets) {
+	return (0, _atscript_db.walkFilter)(filter, relationSets ? {
+		...memoryVisitor,
+		relation: (field, op, operand) => relationPredicate(relationSets, field, op, operand)
+	} : memoryVisitor) ?? (() => true);
 }
 //#endregion
 //#region src/lib/memory-engine.ts
@@ -527,7 +665,7 @@ const databases = /* @__PURE__ */ new WeakMap();
 *   runtime-owned entity with NO database can be observed as a READ-ONLY
 *   atscript table; all writes are rejected (see {@link _assertWritable}).
 */
-var MemoryAdapter = class extends _atscript_db.BaseDbAdapter {
+var MemoryAdapter = class MemoryAdapter extends _atscript_db.BaseDbAdapter {
 	/**
 	* The in-memory database: the space's (see {@link databases}), resolved once
 	* in {@link registerSpace}; an adapter used without a space keeps this own one.
@@ -583,6 +721,19 @@ var MemoryAdapter = class extends _atscript_db.BaseDbAdapter {
 		return !fd.encrypted;
 	}
 	/**
+	* Relational predicates (`{ nav: { $some | $none: … } }`) are evaluated in
+	* reads AND mutation filters. Before a filter holding them is compiled, every
+	* related table (and junction) is loaded ONCE for that operation — through
+	* its own adapter's snapshot seam, so a provider-backed related table works
+	* too — and each predicate becomes a set of matching correlation keys
+	* (see {@link _relationSets}). Predicate-free filters take the plain path.
+	*
+	* @since 0.1.147
+	*/
+	supportsRelationFilters(_mode) {
+		return true;
+	}
+	/**
 	* Coerces a by-id value to the id field's declared leaf type. The framework
 	* calls `adapter.prepareId(value, fieldType)` when building by-id filters, so a
 	* URL id like `"21"` reaches this adapter as the STRING `"21"`. Memory does
@@ -643,14 +794,14 @@ var MemoryAdapter = class extends _atscript_db.BaseDbAdapter {
 	/**
 	* Physical names of the primary-key field(s). Single `@meta.id` resolves via
 	* {@link AtscriptDbReadable.metaIdPhysical}; a composite key maps each logical
-	* PK path through `pathToPhysical` (falling back to the name itself). Memoized
+	* PK path through `physicalPath` (`@db.column` renames included). Memoized
 	* because it is stable per adapter (1:1 with a fixed table) yet read on every
 	* `pkKey`/projection — recomputing would re-read `this._table.*` and re-allocate.
 	*/
 	_physicalPkFields() {
 		if (this._pkFieldsCache) return this._pkFieldsCache;
 		const metaIdPhysical = this._table.metaIdPhysical;
-		const fields = metaIdPhysical ? [metaIdPhysical] : this._table.primaryKeys.map((pk) => this._table.pathToPhysical.get(pk) ?? pk);
+		const fields = metaIdPhysical ? [metaIdPhysical] : this._table.primaryKeys.map((pk) => this._table.physicalPath(pk));
 		this._pkFieldsCache = fields;
 		return fields;
 	}
@@ -808,6 +959,39 @@ var MemoryAdapter = class extends _atscript_db.BaseDbAdapter {
 		return [...this._peekState()?.rows.values() ?? []];
 	}
 	/**
+	* A per-operation row loader for relational predicates: each related table
+	* is snapshotted at most once per operation (the first predicate that needs
+	* it loads it; later ones — and nested ones — reuse that snapshot), so a
+	* provider-backed related table is invoked once per read. `own` seeds this
+	* table's snapshot so a self relation reads the same rows as the outer scan.
+	*/
+	_snapshotLoader(own) {
+		const snapshots = /* @__PURE__ */ new Map();
+		if (own) snapshots.set(this, own);
+		return (adapter) => {
+			let rows = snapshots.get(adapter);
+			if (!rows) {
+				if (!(adapter instanceof MemoryAdapter)) throw new _atscript_db.DbError("REL_FILTER_NOT_SUPPORTED", [{
+					path: "",
+					message: "Relational predicate: the related table is not served by the memory adapter"
+				}]);
+				rows = Promise.resolve(adapter._loadRows());
+				snapshots.set(adapter, rows);
+			}
+			return rows;
+		};
+	}
+	/**
+	* The prepared correlation sets for `filter`'s relational predicates.
+	* Callers only await it when `containsRelationFilter(filter)` — a
+	* predicate-free filter keeps its fully synchronous path. Write methods call
+	* it BEFORE reading the table state, so the related tables (a self relation
+	* included) are snapshotted before any row changes, like SQL.
+	*/
+	async _relationSets(filter, own) {
+		return prepareRelationSets(filter, this._snapshotLoader(own));
+	}
+	/**
 	* Clones the payload in, applies the version default, generates any
 	* `@db.default.increment` values, enforces PK + unique constraints, stores
 	* the row, and returns the resolved inserted id. Clone-in (`structuredClone`)
@@ -891,11 +1075,14 @@ var MemoryAdapter = class extends _atscript_db.BaseDbAdapter {
 	*
 	* When `many` is `false` at most the first match is returned. A table that
 	* does not exist (`state` undefined) matches nothing and is not created.
+	*
+	* A filter with relational predicates needs `relationSets`, prepared by the
+	* caller BEFORE it reads `state` (see {@link _relationSets}).
 	*/
-	_selectForWrite(state, filter, expectedVersion, many) {
+	_selectForWrite(state, filter, expectedVersion, many, relationSets) {
 		const versionColumn = this._table.versionColumnPhysical;
 		if (expectedVersion !== void 0 && versionColumn === void 0) throw new Error("expectedVersion requires a versioned table");
-		const match = buildMemoryPredicate(filter);
+		const match = buildMemoryPredicate(filter, relationSets);
 		const matched = [];
 		for (const [key, row] of state?.rows ?? []) {
 			if (!match(row)) continue;
@@ -975,8 +1162,9 @@ var MemoryAdapter = class extends _atscript_db.BaseDbAdapter {
 	}
 	async replaceOne(filter, data, expectedVersion) {
 		this._assertWritable();
+		const sets = (0, _atscript_db.containsRelationFilter)(filter) ? await this._relationSets(filter) : void 0;
 		const state = this._peekState();
-		const matched = this._selectForWrite(state, filter, expectedVersion, false);
+		const matched = this._selectForWrite(state, filter, expectedVersion, false, sets);
 		if (!state || matched.length === 0) return {
 			matchedCount: 0,
 			modifiedCount: 0
@@ -993,8 +1181,9 @@ var MemoryAdapter = class extends _atscript_db.BaseDbAdapter {
 	}
 	async updateOne(filter, data, ops, expectedVersion) {
 		this._assertWritable();
+		const sets = (0, _atscript_db.containsRelationFilter)(filter) ? await this._relationSets(filter) : void 0;
 		const state = this._peekState();
-		const matched = this._selectForWrite(state, filter, expectedVersion, false);
+		const matched = this._selectForWrite(state, filter, expectedVersion, false, sets);
 		if (!state || matched.length === 0) return {
 			matchedCount: 0,
 			modifiedCount: 0
@@ -1008,8 +1197,9 @@ var MemoryAdapter = class extends _atscript_db.BaseDbAdapter {
 	}
 	async deleteOne(filter) {
 		this._assertWritable();
+		const sets = (0, _atscript_db.containsRelationFilter)(filter) ? await this._relationSets(filter) : void 0;
 		const state = this._peekState();
-		const matched = this._selectForWrite(state, filter, void 0, false);
+		const matched = this._selectForWrite(state, filter, void 0, false, sets);
 		if (!state || matched.length === 0) return { deletedCount: 0 };
 		state.rows.delete(matched[0].key);
 		return { deletedCount: 1 };
@@ -1061,8 +1251,14 @@ var MemoryAdapter = class extends _atscript_db.BaseDbAdapter {
 	* working set — one provider invocation per logical read.
 	*/
 	async _filteredRows(query) {
-		const match = buildMemoryPredicate(query.filter);
-		return (await this._loadRows()).filter(match);
+		if (!(0, _atscript_db.containsRelationFilter)(query.filter)) {
+			const match = buildMemoryPredicate(query.filter);
+			return (await this._loadRows()).filter(match);
+		}
+		const own = Promise.resolve(this._loadRows());
+		own.catch(() => {});
+		const sets = await this._relationSets(query.filter, own);
+		return (await own).filter(buildMemoryPredicate(query.filter, sets));
 	}
 	async findOne(query) {
 		const filtered = await this._filteredRows(query);
@@ -1117,14 +1313,19 @@ var MemoryAdapter = class extends _atscript_db.BaseDbAdapter {
 	aggregateFns() {
 		return _atscript_db.ALL_AGGREGATE_FNS;
 	}
+	/** Managed views render nothing (non-goal) — both are accepted like `aggregateFns()`. */
+	viewCapabilities() {
+		return _atscript_db.ALL_VIEW_CAPABILITIES;
+	}
 	async updateMany(filter, data, ops) {
 		this._assertWritable();
+		const sets = (0, _atscript_db.containsRelationFilter)(filter) ? await this._relationSets(filter) : void 0;
 		const state = this._peekState();
 		if (!state) return {
 			matchedCount: 0,
 			modifiedCount: 0
 		};
-		const matched = this._selectForWrite(state, filter, void 0, true);
+		const matched = this._selectForWrite(state, filter, void 0, true, sets);
 		for (const { key, row } of matched) this._commitUpdate(state, key, row, data, ops);
 		return {
 			matchedCount: matched.length,
@@ -1133,12 +1334,13 @@ var MemoryAdapter = class extends _atscript_db.BaseDbAdapter {
 	}
 	async replaceMany(filter, data) {
 		this._assertWritable();
+		const sets = (0, _atscript_db.containsRelationFilter)(filter) ? await this._relationSets(filter) : void 0;
 		const state = this._peekState();
 		if (!state) return {
 			matchedCount: 0,
 			modifiedCount: 0
 		};
-		const matched = this._selectForWrite(state, filter, void 0, true);
+		const matched = this._selectForWrite(state, filter, void 0, true, sets);
 		for (const { key, row } of matched) this._commitUpdate(state, key, row, data);
 		return {
 			matchedCount: matched.length,
@@ -1147,9 +1349,10 @@ var MemoryAdapter = class extends _atscript_db.BaseDbAdapter {
 	}
 	async deleteMany(filter) {
 		this._assertWritable();
+		const sets = (0, _atscript_db.containsRelationFilter)(filter) ? await this._relationSets(filter) : void 0;
 		const state = this._peekState();
 		if (!state) return { deletedCount: 0 };
-		const matched = this._selectForWrite(state, filter, void 0, true);
+		const matched = this._selectForWrite(state, filter, void 0, true, sets);
 		for (const { key } of matched) state.rows.delete(key);
 		return { deletedCount: matched.length };
 	}

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TFieldOps } from "@atscript/db";
+import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, ResolvedRelationFilter, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TFieldOps, TViewCapability } from "@atscript/db";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/lib/memory-adapter.d.ts
@@ -76,6 +76,17 @@ declare class MemoryAdapter extends BaseDbAdapter {
    *   decomposes patches into dot-path `$set`s and loads relations app-level.
    */
   canFilterField(fd: TDbFieldMeta): boolean;
+  /**
+   * Relational predicates (`{ nav: { $some | $none: … } }`) are evaluated in
+   * reads AND mutation filters. Before a filter holding them is compiled, every
+   * related table (and junction) is loaded ONCE for that operation — through
+   * its own adapter's snapshot seam, so a provider-backed related table works
+   * too — and each predicate becomes a set of matching correlation keys
+   * (see {@link _relationSets}). Predicate-free filters take the plain path.
+   *
+   * @since 0.1.147
+   */
+  supportsRelationFilters(_mode: "read" | "write"): boolean;
   /**
    * Coerces a by-id value to the id field's declared leaf type. The framework
    * calls `adapter.prepareId(value, fieldType)` when building by-id filters, so a
@@ -107,7 +118,7 @@ declare class MemoryAdapter extends BaseDbAdapter {
   /**
    * Physical names of the primary-key field(s). Single `@meta.id` resolves via
    * {@link AtscriptDbReadable.metaIdPhysical}; a composite key maps each logical
-   * PK path through `pathToPhysical` (falling back to the name itself). Memoized
+   * PK path through `physicalPath` (`@db.column` renames included). Memoized
    * because it is stable per adapter (1:1 with a fixed table) yet read on every
    * `pkKey`/projection — recomputing would re-read `this._table.*` and re-allocate.
    */
@@ -221,6 +232,22 @@ declare class MemoryAdapter extends BaseDbAdapter {
    * AND single-snapshot-per-`findManyWithCount` both fall out for free.
    */
   protected _loadRows(): Record<string, unknown>[] | Promise<Record<string, unknown>[]>;
+  /**
+   * A per-operation row loader for relational predicates: each related table
+   * is snapshotted at most once per operation (the first predicate that needs
+   * it loads it; later ones — and nested ones — reuse that snapshot), so a
+   * provider-backed related table is invoked once per read. `own` seeds this
+   * table's snapshot so a self relation reads the same rows as the outer scan.
+   */
+  private _snapshotLoader;
+  /**
+   * The prepared correlation sets for `filter`'s relational predicates.
+   * Callers only await it when `containsRelationFilter(filter)` — a
+   * predicate-free filter keeps its fully synchronous path. Write methods call
+   * it BEFORE reading the table state, so the related tables (a self relation
+   * included) are snapshotted before any row changes, like SQL.
+   */
+  private _relationSets;
   /**
    * Clones the payload in, applies the version default, generates any
    * `@db.default.increment` values, enforces PK + unique constraints, stores
@@ -257,6 +284,9 @@ declare class MemoryAdapter extends BaseDbAdapter {
    *
    * When `many` is `false` at most the first match is returned. A table that
    * does not exist (`state` undefined) matches nothing and is not created.
+   *
+   * A filter with relational predicates needs `relationSets`, prepared by the
+   * caller BEFORE it reads `state` (see {@link _relationSets}).
    */
   private _selectForWrite;
   /**
@@ -378,6 +408,8 @@ declare class MemoryAdapter extends BaseDbAdapter {
   calendarBucketUnits(): ReadonlySet<BucketUnit>;
   /** Every aggregate function, `countDistinct` included. */
   aggregateFns(): ReadonlySet<AggregateFn>;
+  /** Managed views render nothing (non-goal) — both are accepted like `aggregateFns()`. */
+  viewCapabilities(): ReadonlySet<TViewCapability>;
   updateMany(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps): Promise<TDbUpdateResult>;
   replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
   deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;
@@ -449,6 +481,14 @@ type Predicate = (row: Record<string, unknown>) => boolean;
  * later concern; the SQL/Mongo adapters flatten differently and we do not want
  * to fake a semantic the store can't back yet.
  */
+/**
+ * Per-predicate correlation sets: for every {@link ResolvedRelationFilter} of
+ * a filter, the SOURCE correlation tuples (see {@link correlationKey}) that
+ * have at least one related row matching the predicate's inner filter.
+ * Built asynchronously by {@link prepareRelationSets}; consumed synchronously
+ * by {@link buildMemoryPredicate}.
+ */
+type RelationSets = ReadonlyMap<ResolvedRelationFilter, ReadonlySet<string>>;
 /**
  * Compiles a {@link FilterExpr} into an in-memory row predicate
  * `(row) => boolean`, reusing the shared {@link walkFilter} walker so filter
@@ -456,8 +496,13 @@ type Predicate = (row: Record<string, unknown>) => boolean;
  *
  * An empty/absent filter (for which `walkFilter` returns `undefined`) compiles
  * to a match-everything predicate.
+ *
+ * A filter holding relational predicates (`ResolvedRelationFilter` operands,
+ * since 0.1.147) needs `relationSets` — prepared internally by
+ * `MemoryAdapter` from the related tables; a standalone call on such a
+ * filter throws `REL_FILTER_NOT_SUPPORTED`.
  */
-declare function buildMemoryPredicate(filter: FilterExpr): Predicate;
+declare function buildMemoryPredicate(filter: FilterExpr, relationSets?: RelationSets): Predicate;
 //#endregion
 //#region src/lib/memory-engine.d.ts
 /**

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TFieldOps } from "@atscript/db";
+import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, ResolvedRelationFilter, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TFieldOps, TViewCapability } from "@atscript/db";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/lib/memory-adapter.d.ts
@@ -76,6 +76,17 @@ declare class MemoryAdapter extends BaseDbAdapter {
    *   decomposes patches into dot-path `$set`s and loads relations app-level.
    */
   canFilterField(fd: TDbFieldMeta): boolean;
+  /**
+   * Relational predicates (`{ nav: { $some | $none: … } }`) are evaluated in
+   * reads AND mutation filters. Before a filter holding them is compiled, every
+   * related table (and junction) is loaded ONCE for that operation — through
+   * its own adapter's snapshot seam, so a provider-backed related table works
+   * too — and each predicate becomes a set of matching correlation keys
+   * (see {@link _relationSets}). Predicate-free filters take the plain path.
+   *
+   * @since 0.1.147
+   */
+  supportsRelationFilters(_mode: "read" | "write"): boolean;
   /**
    * Coerces a by-id value to the id field's declared leaf type. The framework
    * calls `adapter.prepareId(value, fieldType)` when building by-id filters, so a
@@ -107,7 +118,7 @@ declare class MemoryAdapter extends BaseDbAdapter {
   /**
    * Physical names of the primary-key field(s). Single `@meta.id` resolves via
    * {@link AtscriptDbReadable.metaIdPhysical}; a composite key maps each logical
-   * PK path through `pathToPhysical` (falling back to the name itself). Memoized
+   * PK path through `physicalPath` (`@db.column` renames included). Memoized
    * because it is stable per adapter (1:1 with a fixed table) yet read on every
    * `pkKey`/projection — recomputing would re-read `this._table.*` and re-allocate.
    */
@@ -221,6 +232,22 @@ declare class MemoryAdapter extends BaseDbAdapter {
    * AND single-snapshot-per-`findManyWithCount` both fall out for free.
    */
   protected _loadRows(): Record<string, unknown>[] | Promise<Record<string, unknown>[]>;
+  /**
+   * A per-operation row loader for relational predicates: each related table
+   * is snapshotted at most once per operation (the first predicate that needs
+   * it loads it; later ones — and nested ones — reuse that snapshot), so a
+   * provider-backed related table is invoked once per read. `own` seeds this
+   * table's snapshot so a self relation reads the same rows as the outer scan.
+   */
+  private _snapshotLoader;
+  /**
+   * The prepared correlation sets for `filter`'s relational predicates.
+   * Callers only await it when `containsRelationFilter(filter)` — a
+   * predicate-free filter keeps its fully synchronous path. Write methods call
+   * it BEFORE reading the table state, so the related tables (a self relation
+   * included) are snapshotted before any row changes, like SQL.
+   */
+  private _relationSets;
   /**
    * Clones the payload in, applies the version default, generates any
    * `@db.default.increment` values, enforces PK + unique constraints, stores
@@ -257,6 +284,9 @@ declare class MemoryAdapter extends BaseDbAdapter {
    *
    * When `many` is `false` at most the first match is returned. A table that
    * does not exist (`state` undefined) matches nothing and is not created.
+   *
+   * A filter with relational predicates needs `relationSets`, prepared by the
+   * caller BEFORE it reads `state` (see {@link _relationSets}).
    */
   private _selectForWrite;
   /**
@@ -378,6 +408,8 @@ declare class MemoryAdapter extends BaseDbAdapter {
   calendarBucketUnits(): ReadonlySet<BucketUnit>;
   /** Every aggregate function, `countDistinct` included. */
   aggregateFns(): ReadonlySet<AggregateFn>;
+  /** Managed views render nothing (non-goal) — both are accepted like `aggregateFns()`. */
+  viewCapabilities(): ReadonlySet<TViewCapability>;
   updateMany(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps): Promise<TDbUpdateResult>;
   replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
   deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;
@@ -449,6 +481,14 @@ type Predicate = (row: Record<string, unknown>) => boolean;
  * later concern; the SQL/Mongo adapters flatten differently and we do not want
  * to fake a semantic the store can't back yet.
  */
+/**
+ * Per-predicate correlation sets: for every {@link ResolvedRelationFilter} of
+ * a filter, the SOURCE correlation tuples (see {@link correlationKey}) that
+ * have at least one related row matching the predicate's inner filter.
+ * Built asynchronously by {@link prepareRelationSets}; consumed synchronously
+ * by {@link buildMemoryPredicate}.
+ */
+type RelationSets = ReadonlyMap<ResolvedRelationFilter, ReadonlySet<string>>;
 /**
  * Compiles a {@link FilterExpr} into an in-memory row predicate
  * `(row) => boolean`, reusing the shared {@link walkFilter} walker so filter
@@ -456,8 +496,13 @@ type Predicate = (row: Record<string, unknown>) => boolean;
  *
  * An empty/absent filter (for which `walkFilter` returns `undefined`) compiles
  * to a match-everything predicate.
+ *
+ * A filter holding relational predicates (`ResolvedRelationFilter` operands,
+ * since 0.1.147) needs `relationSets` — prepared internally by
+ * `MemoryAdapter` from the related tables; a standalone call on such a
+ * filter throws `REL_FILTER_NOT_SUPPORTED`.
  */
-declare function buildMemoryPredicate(filter: FilterExpr): Predicate;
+declare function buildMemoryPredicate(filter: FilterExpr, relationSets?: RelationSets): Predicate;
 //#endregion
 //#region src/lib/memory-engine.d.ts
 /**

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, BaseDbAdapter, DbError, DbSpace, deletePath, getPath, getPath as getPath$1, isAtscriptDbView, walkFilter } from "@atscript/db";
+import { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, BaseDbAdapter, DbError, DbSpace, containsRelationFilter, deletePath, forEachResolvedRelation, getPath, getPath as getPath$1, isAtscriptDbView, isResolvedRelationFilter, walkFilter } from "@atscript/db";
 import { assertAggregateFn, resolveAlias } from "@atscript/db/agg";
 import { bucketer } from "@uniqu/core";
 //#region src/lib/memory-filter.ts
@@ -155,18 +155,156 @@ const memoryVisitor = {
 				message: `Unsupported filter operator: ${op}`
 			}]);
 		}
+	},
+	relation(field, op, operand) {
+		return relationPredicate(void 0, field, op, operand);
 	}
 };
 /**
+* Identity of the key tuple `fields` of `row` (dot-paths read nested), or
+* `undefined` when a component is `null` / missing — a NULL key component
+* never correlates (SQL `=` semantics: `$some` false, `$none` true).
+* Every component is type-tagged (see {@link keyPart}), matching the strict
+* equality the memory filter uses everywhere (`valuesEqual`): `1` ≠ `"1"`,
+* `5n` ≠ `"5n"`, a `Date` ≠ its ISO string; `Date`s compare by instant.
+*/
+function correlationKey(row, fields) {
+	const parts = [];
+	for (const field of fields) {
+		const part = keyPart(getPath$1(row, field));
+		if (part === void 0) return;
+		parts.push(part);
+	}
+	return JSON.stringify(parts);
+}
+/**
+* Type-tagged identity of one key component, or `undefined` when it never
+* equals anything (`null` / missing, `NaN`).
+*/
+function keyPart(value) {
+	switch (typeof value) {
+		case "string": return `s:${value}`;
+		case "number": return Number.isNaN(value) ? void 0 : `n:${value === 0 ? 0 : value}`;
+		case "bigint": return `b:${value}`;
+		case "boolean": return `t:${value}`;
+		case "undefined": return;
+		default:
+			if (value === null) return void 0;
+			if (value instanceof Date) {
+				const time = value.getTime();
+				return Number.isNaN(time) ? void 0 : `d:${time}`;
+			}
+			return `o:${JSON.stringify(value, (_k, v) => typeof v === "bigint" ? `${v}n` : v)}`;
+	}
+}
+/** Source-side correlation columns of a resolved predicate (physical names). */
+function sourceColumns(node) {
+	return node.junction ? node.junction.toSource.map((p) => p.source) : node.pairs.map((p) => p.source);
+}
+/**
+* The visitor's `relation` callback: a row satisfies `$some` when its source
+* correlation tuple is in the predicate's prepared set, `$none` otherwise.
+*/
+function relationPredicate(sets, field, op, operand) {
+	const node = operand;
+	const set = isResolvedRelationFilter(node) ? sets?.get(node) : void 0;
+	if (!set) throw new DbError("REL_FILTER_NOT_SUPPORTED", [{
+		path: field,
+		message: `Relational predicate "${op}" on "${field}" was not prepared — call prepareRelationSets() before buildMemoryPredicate()`
+	}]);
+	const columns = sourceColumns(node);
+	const some = op === "$some";
+	return (row) => {
+		const key = correlationKey(row, columns);
+		return (key !== void 0 && set.has(key)) === some;
+	};
+}
+/**
+* Resolves every relational predicate of a TRANSLATED filter (nested ones
+* included) into a correlation set, loading each related table through
+* `load`:
+*
+* - `to` / `from`: the related rows matching the inner filter contribute their
+*   `pairs[].target` tuples — equal to the source tuple (`pairs[].source`) of
+*   every row that has such a related row.
+* - `via`: the matching related rows' `junction.toTarget[].target` tuples
+*   select junction rows (also filtered by the junction part of
+*   `@db.rel.filter`), which contribute their `junction.toSource[].junction`
+*   tuples.
+*
+* Nested predicates are prepared against the related table's rows first
+* (their source is this predicate's target). Returns `undefined` when the
+* filter holds no predicate — callers then stay on the plain synchronous path.
+*
+* @since 0.1.147
+*/
+async function prepareRelationSets(filter, load) {
+	if (!containsRelationFilter(filter)) return;
+	const sets = /* @__PURE__ */ new Map();
+	await prepareLevel(filter, load, sets);
+	return sets;
+}
+/** Prepares the predicates at one level of `filter` (and, recursively, their operands). */
+async function prepareLevel(filter, load, sets) {
+	const nodes = [];
+	forEachResolvedRelation(filter, (node) => nodes.push(node), false);
+	for (const node of nodes) if (!sets.has(node)) sets.set(node, await correlationSet(node, load, sets));
+}
+/** Matching rows of `adapter`'s table for `filter` (its own predicates prepared first). */
+async function matchingRows(adapter, filter, load, sets) {
+	const rows = await load(adapter);
+	if (!filter || Object.keys(filter).length === 0) return rows;
+	await prepareLevel(filter, load, sets);
+	return rows.filter(buildMemoryPredicate(filter, sets));
+}
+/** The source correlation tuples that have a related row matching `node`. */
+async function correlationSet(node, load, sets) {
+	const targets = await matchingRows(node.target.adapter, node.filter, load, sets);
+	const result = /* @__PURE__ */ new Set();
+	if (!node.junction) {
+		const columns = node.pairs.map((p) => p.target);
+		for (const row of targets) {
+			const key = correlationKey(row, columns);
+			if (key !== void 0) result.add(key);
+		}
+		return result;
+	}
+	const { junction } = node;
+	const targetKeys = /* @__PURE__ */ new Set();
+	const targetColumns = junction.toTarget.map((p) => p.target);
+	for (const row of targets) {
+		const key = correlationKey(row, targetColumns);
+		if (key !== void 0) targetKeys.add(key);
+	}
+	if (targetKeys.size === 0) return result;
+	const toTarget = junction.toTarget.map((p) => p.junction);
+	const toSource = junction.toSource.map((p) => p.junction);
+	for (const row of await matchingRows(junction.adapter, junction.filter, load, sets)) {
+		const targetKey = correlationKey(row, toTarget);
+		if (targetKey === void 0 || !targetKeys.has(targetKey)) continue;
+		const sourceKey = correlationKey(row, toSource);
+		if (sourceKey !== void 0) result.add(sourceKey);
+	}
+	return result;
+}
+/**
 * Compiles a {@link FilterExpr} into an in-memory row predicate
 * `(row) => boolean`, reusing the shared {@link walkFilter} walker so filter
 * structure matches the SQL/Mongo adapters by construction.
 *
 * An empty/absent filter (for which `walkFilter` returns `undefined`) compiles
 * to a match-everything predicate.
+*
+* A filter holding relational predicates (`ResolvedRelationFilter` operands,
+* since 0.1.147) needs `relationSets` — prepared internally by
+* `MemoryAdapter` from the related tables; a standalone call on such a
+* filter throws `REL_FILTER_NOT_SUPPORTED`.
 */
-function buildMemoryPredicate(filter) {
-	return walkFilter(filter, memoryVisitor) ?? (() => true);
+function buildMemoryPredicate(filter, relationSets) {
+	return walkFilter(filter, relationSets ? {
+		...memoryVisitor,
+		relation: (field, op, operand) => relationPredicate(relationSets, field, op, operand)
+	} : memoryVisitor) ?? (() => true);
 }
 //#endregion
 //#region src/lib/memory-engine.ts
@@ -526,7 +664,7 @@ const databases = /* @__PURE__ */ new WeakMap();
 *   runtime-owned entity with NO database can be observed as a READ-ONLY
 *   atscript table; all writes are rejected (see {@link _assertWritable}).
 */
-var MemoryAdapter = class extends BaseDbAdapter {
+var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 	/**
 	* The in-memory database: the space's (see {@link databases}), resolved once
 	* in {@link registerSpace}; an adapter used without a space keeps this own one.
@@ -582,6 +720,19 @@ var MemoryAdapter = class extends BaseDbAdapter {
 		return !fd.encrypted;
 	}
 	/**
+	* Relational predicates (`{ nav: { $some | $none: … } }`) are evaluated in
+	* reads AND mutation filters. Before a filter holding them is compiled, every
+	* related table (and junction) is loaded ONCE for that operation — through
+	* its own adapter's snapshot seam, so a provider-backed related table works
+	* too — and each predicate becomes a set of matching correlation keys
+	* (see {@link _relationSets}). Predicate-free filters take the plain path.
+	*
+	* @since 0.1.147
+	*/
+	supportsRelationFilters(_mode) {
+		return true;
+	}
+	/**
 	* Coerces a by-id value to the id field's declared leaf type. The framework
 	* calls `adapter.prepareId(value, fieldType)` when building by-id filters, so a
 	* URL id like `"21"` reaches this adapter as the STRING `"21"`. Memory does
@@ -642,14 +793,14 @@ var MemoryAdapter = class extends BaseDbAdapter {
 	/**
 	* Physical names of the primary-key field(s). Single `@meta.id` resolves via
 	* {@link AtscriptDbReadable.metaIdPhysical}; a composite key maps each logical
-	* PK path through `pathToPhysical` (falling back to the name itself). Memoized
+	* PK path through `physicalPath` (`@db.column` renames included). Memoized
 	* because it is stable per adapter (1:1 with a fixed table) yet read on every
 	* `pkKey`/projection — recomputing would re-read `this._table.*` and re-allocate.
 	*/
 	_physicalPkFields() {
 		if (this._pkFieldsCache) return this._pkFieldsCache;
 		const metaIdPhysical = this._table.metaIdPhysical;
-		const fields = metaIdPhysical ? [metaIdPhysical] : this._table.primaryKeys.map((pk) => this._table.pathToPhysical.get(pk) ?? pk);
+		const fields = metaIdPhysical ? [metaIdPhysical] : this._table.primaryKeys.map((pk) => this._table.physicalPath(pk));
 		this._pkFieldsCache = fields;
 		return fields;
 	}
@@ -807,6 +958,39 @@ var MemoryAdapter = class extends BaseDbAdapter {
 		return [...this._peekState()?.rows.values() ?? []];
 	}
 	/**
+	* A per-operation row loader for relational predicates: each related table
+	* is snapshotted at most once per operation (the first predicate that needs
+	* it loads it; later ones — and nested ones — reuse that snapshot), so a
+	* provider-backed related table is invoked once per read. `own` seeds this
+	* table's snapshot so a self relation reads the same rows as the outer scan.
+	*/
+	_snapshotLoader(own) {
+		const snapshots = /* @__PURE__ */ new Map();
+		if (own) snapshots.set(this, own);
+		return (adapter) => {
+			let rows = snapshots.get(adapter);
+			if (!rows) {
+				if (!(adapter instanceof MemoryAdapter)) throw new DbError("REL_FILTER_NOT_SUPPORTED", [{
+					path: "",
+					message: "Relational predicate: the related table is not served by the memory adapter"
+				}]);
+				rows = Promise.resolve(adapter._loadRows());
+				snapshots.set(adapter, rows);
+			}
+			return rows;
+		};
+	}
+	/**
+	* The prepared correlation sets for `filter`'s relational predicates.
+	* Callers only await it when `containsRelationFilter(filter)` — a
+	* predicate-free filter keeps its fully synchronous path. Write methods call
+	* it BEFORE reading the table state, so the related tables (a self relation
+	* included) are snapshotted before any row changes, like SQL.
+	*/
+	async _relationSets(filter, own) {
+		return prepareRelationSets(filter, this._snapshotLoader(own));
+	}
+	/**
 	* Clones the payload in, applies the version default, generates any
 	* `@db.default.increment` values, enforces PK + unique constraints, stores
 	* the row, and returns the resolved inserted id. Clone-in (`structuredClone`)
@@ -890,11 +1074,14 @@ var MemoryAdapter = class extends BaseDbAdapter {
 	*
 	* When `many` is `false` at most the first match is returned. A table that
 	* does not exist (`state` undefined) matches nothing and is not created.
+	*
+	* A filter with relational predicates needs `relationSets`, prepared by the
+	* caller BEFORE it reads `state` (see {@link _relationSets}).
 	*/
-	_selectForWrite(state, filter, expectedVersion, many) {
+	_selectForWrite(state, filter, expectedVersion, many, relationSets) {
 		const versionColumn = this._table.versionColumnPhysical;
 		if (expectedVersion !== void 0 && versionColumn === void 0) throw new Error("expectedVersion requires a versioned table");
-		const match = buildMemoryPredicate(filter);
+		const match = buildMemoryPredicate(filter, relationSets);
 		const matched = [];
 		for (const [key, row] of state?.rows ?? []) {
 			if (!match(row)) continue;
@@ -974,8 +1161,9 @@ var MemoryAdapter = class extends BaseDbAdapter {
 	}
 	async replaceOne(filter, data, expectedVersion) {
 		this._assertWritable();
+		const sets = containsRelationFilter(filter) ? await this._relationSets(filter) : void 0;
 		const state = this._peekState();
-		const matched = this._selectForWrite(state, filter, expectedVersion, false);
+		const matched = this._selectForWrite(state, filter, expectedVersion, false, sets);
 		if (!state || matched.length === 0) return {
 			matchedCount: 0,
 			modifiedCount: 0
@@ -992,8 +1180,9 @@ var MemoryAdapter = class extends BaseDbAdapter {
 	}
 	async updateOne(filter, data, ops, expectedVersion) {
 		this._assertWritable();
+		const sets = containsRelationFilter(filter) ? await this._relationSets(filter) : void 0;
 		const state = this._peekState();
-		const matched = this._selectForWrite(state, filter, expectedVersion, false);
+		const matched = this._selectForWrite(state, filter, expectedVersion, false, sets);
 		if (!state || matched.length === 0) return {
 			matchedCount: 0,
 			modifiedCount: 0
@@ -1007,8 +1196,9 @@ var MemoryAdapter = class extends BaseDbAdapter {
 	}
 	async deleteOne(filter) {
 		this._assertWritable();
+		const sets = containsRelationFilter(filter) ? await this._relationSets(filter) : void 0;
 		const state = this._peekState();
-		const matched = this._selectForWrite(state, filter, void 0, false);
+		const matched = this._selectForWrite(state, filter, void 0, false, sets);
 		if (!state || matched.length === 0) return { deletedCount: 0 };
 		state.rows.delete(matched[0].key);
 		return { deletedCount: 1 };
@@ -1060,8 +1250,14 @@ var MemoryAdapter = class extends BaseDbAdapter {
 	* working set — one provider invocation per logical read.
 	*/
 	async _filteredRows(query) {
-		const match = buildMemoryPredicate(query.filter);
-		return (await this._loadRows()).filter(match);
+		if (!containsRelationFilter(query.filter)) {
+			const match = buildMemoryPredicate(query.filter);
+			return (await this._loadRows()).filter(match);
+		}
+		const own = Promise.resolve(this._loadRows());
+		own.catch(() => {});
+		const sets = await this._relationSets(query.filter, own);
+		return (await own).filter(buildMemoryPredicate(query.filter, sets));
 	}
 	async findOne(query) {
 		const filtered = await this._filteredRows(query);
@@ -1116,14 +1312,19 @@ var MemoryAdapter = class extends BaseDbAdapter {
 	aggregateFns() {
 		return ALL_AGGREGATE_FNS;
 	}
+	/** Managed views render nothing (non-goal) — both are accepted like `aggregateFns()`. */
+	viewCapabilities() {
+		return ALL_VIEW_CAPABILITIES;
+	}
 	async updateMany(filter, data, ops) {
 		this._assertWritable();
+		const sets = containsRelationFilter(filter) ? await this._relationSets(filter) : void 0;
 		const state = this._peekState();
 		if (!state) return {
 			matchedCount: 0,
 			modifiedCount: 0
 		};
-		const matched = this._selectForWrite(state, filter, void 0, true);
+		const matched = this._selectForWrite(state, filter, void 0, true, sets);
 		for (const { key, row } of matched) this._commitUpdate(state, key, row, data, ops);
 		return {
 			matchedCount: matched.length,
@@ -1132,12 +1333,13 @@ var MemoryAdapter = class extends BaseDbAdapter {
 	}
 	async replaceMany(filter, data) {
 		this._assertWritable();
+		const sets = containsRelationFilter(filter) ? await this._relationSets(filter) : void 0;
 		const state = this._peekState();
 		if (!state) return {
 			matchedCount: 0,
 			modifiedCount: 0
 		};
-		const matched = this._selectForWrite(state, filter, void 0, true);
+		const matched = this._selectForWrite(state, filter, void 0, true, sets);
 		for (const { key, row } of matched) this._commitUpdate(state, key, row, data);
 		return {
 			matchedCount: matched.length,
@@ -1146,9 +1348,10 @@ var MemoryAdapter = class extends BaseDbAdapter {
 	}
 	async deleteMany(filter) {
 		this._assertWritable();
+		const sets = containsRelationFilter(filter) ? await this._relationSets(filter) : void 0;
 		const state = this._peekState();
 		if (!state) return { deletedCount: 0 };
-		const matched = this._selectForWrite(state, filter, void 0, true);
+		const matched = this._selectForWrite(state, filter, void 0, true, sets);
 		for (const { key } of matched) state.rows.delete(key);
 		return { deletedCount: matched.length };
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-memory",
-  "version": "0.1.145",
+  "version": "0.1.147",
   "description": "In-memory adapter for atscript-db.",
   "keywords": [
     "atscript",
@@ -36,16 +36,16 @@
     "access": "public"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.97",
-    "@atscript/typescript": "^0.1.97",
-    "@uniqu/core": "^0.1.11",
-    "unplugin-atscript": "^0.1.97"
+    "@atscript/core": "^0.1.99",
+    "@atscript/typescript": "^0.1.99",
+    "@uniqu/core": "^0.1.12",
+    "unplugin-atscript": "^0.1.99"
   },
   "peerDependencies": {
-    "@atscript/core": "^0.1.97",
-    "@atscript/typescript": "^0.1.97",
-    "@uniqu/core": "^0.1.11",
-    "@atscript/db": "^0.1.145"
+    "@atscript/core": "^0.1.99",
+    "@atscript/typescript": "^0.1.99",
+    "@uniqu/core": "^0.1.12",
+    "@atscript/db": "^0.1.147"
   },
   "scripts": {
     "postinstall": "asc -f dts",