@harperfast/harper 5.0.25 → 5.1.0-beta.1

package/resources/Table.ts

@@ -6,7 +6,8 @@
 
 import { CONFIG_PARAMS, OPERATIONS_ENUM, SYSTEM_TABLE_NAMES, SYSTEM_SCHEMA_NAME } from '../utility/hdbTerms.ts';
 import { type Database } from 'lmdb';
-import { getIndexedValues } from '../utility/lmdb/commonUtility.js';
+import { Script } from 'node:vm';
+import { getIndexedValues } from '../utility/lmdb/commonUtility.ts';
 import { getThisNodeId, exportIdMapping } from './nodeIdMapping.ts';
 import lodash from 'lodash';
 import { ExtendedIterable, SKIP } from '@harperfast/extended-iterable';
@@ -25,10 +26,10 @@ import lmdbProcessRows from '../dataLayer/harperBridge/lmdbBridge/lmdbUtility/lm
 import { Resource, transformForSelect } from './Resource.ts';
 import { when, promiseNormalize } from '../utility/when.ts';
 import { DatabaseTransaction, ImmediateTransaction, TRANSACTION_STATE } from './DatabaseTransaction.ts';
-import * as envMngr from '../utility/environment/environmentManager.js';
+import * as envMngr from '../utility/environment/environmentManager.ts';
 import { addSubscription } from './transactionBroadcast.ts';
-import { handleHDBError, ClientError, ServerError, AccessViolation } from '../utility/errors/hdbError.js';
-import * as signalling from '../utility/signalling.js';
+import { handleHDBError, ClientError, ServerError, AccessViolation } from '../utility/errors/hdbError.ts';
+import * as signalling from '../utility/signalling.ts';
 import { SchemaEventMsg, UserEventMsg } from '../server/threads/itc.js';
 import { databases, table } from './databases.ts';
 import {
@@ -38,6 +39,7 @@ import {
 	flattenKey,
 	COERCIBLE_OPERATORS,
 	executeConditions,
+	resolveComparator,
 } from './search.ts';
 import { logger } from '../utility/logging/logger.ts';
 import { Addition, assignTrackedAccessors, updateAndFreeze, hasChanges, GenericTrackedObject } from './tracked.ts';
@@ -45,7 +47,8 @@ import { transaction, contextStorage } from './transaction.ts';
 import { MAXIMUM_KEY, writeKey, compareKeys } from 'ordered-binary';
 import { getWorkerIndex, getWorkerCount } from '../server/threads/manageThreads.js';
 import { HAS_BLOBS, auditRetention, removeAuditEntry } from './auditStore.ts';
-import { autoCast, autoCastBooleanStrict } from '../utility/common_utils.js';
+import { buildEmbedBefore, createDefaultEmbedder, type EmbedAttribute, type Embedder } from './models/embedHook.ts';
+import { autoCast, autoCastBooleanStrict } from '../utility/common_utils.ts';
 import {
 	recordUpdater,
 	removeEntry,
@@ -61,7 +64,7 @@ import fs from 'node:fs';
 import { Blob, deleteBlobsInObject, findBlobsInObject, startPreCommitBlobsForRecord } from './blob.ts';
 import { onStorageReclamation } from '../server/storageReclamation.ts';
 import { RequestTarget } from './RequestTarget.ts';
-import harperLogger from '../utility/logging/harper_logger.js';
+import harperLogger from '../utility/logging/harper_logger.ts';
 import { throttle } from '../server/throttle.ts';
 import { RocksDatabase } from '@harperfast/rocksdb-js';
 import { LMDBTransaction, ImmediateTransaction as ImmediateLMDBTransaction } from './LMDBTransaction';
@@ -78,11 +81,21 @@ export type Attribute = {
 	nullable?: boolean;
 	expiresAt?: boolean;
 	isPrimaryKey?: boolean;
-	indexed?: unknown;
-	relationship?: unknown;
-	computed?: unknown;
+	indexed?: any;
+	relationship?: any;
+	computed?: any;
+	resolve?: any;
+	computedFromExpression?: any;
+	embed?: { source: string; model: string };
+	version?: any;
 	properties?: Array<Attribute>;
 	elements?: Attribute;
+	sealed?: boolean;
+
+	definition?: any;
+	set?: any;
+	enumerable?: boolean;
+	select?: any;
 };
 
 type MaybePromise<T> = T | Promise<T>;
@@ -91,6 +104,7 @@ const NULL_WITH_TIMESTAMP = new Uint8Array(9);
 NULL_WITH_TIMESTAMP[8] = 0xc0; // null
 const UNCACHEABLE_TIMESTAMP = Infinity; // we use this when dynamic content is accessed that we can't safely cache, and this prevents earlier timestamps from change the "last" modification
 const RECORD_PRUNING_INTERVAL = 60000; // one minute
+const CACHEABLE_STATUS_CODES = new Set([200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414, 501]);
 envMngr.initSync();
 const LMDB_PREFETCH_WRITES = envMngr.get(CONFIG_PARAMS.STORAGE_PREFETCHWRITES);
 const LOCK_TIMEOUT = 10000;
@@ -131,6 +145,7 @@ type ResidencyDefinition = number | string[] | void;
  * Instances of the returned class are Resource instances, intended to provide a consistent view or transaction of the table
  * @param options
  */
+// #section: setup-and-factory
 export function makeTable(options) {
 	const {
 		primaryKey,
@@ -154,9 +169,11 @@ export function makeTable(options) {
 	const updateRecord = recordUpdater(primaryStore, tableId, auditStore);
 	let sourceLoad: any; // if a source has a load function (replicator), record it here
 	let hasSourceGet: any;
-	let primaryKeyAttribute: Attribute = {};
+	let primaryKeyAttribute: Attribute | undefined;
 	let lastEvictionCompletion: Promise<void> = Promise.resolve();
-	let createdTimeProperty: Attribute, updatedTimeProperty: Attribute, expiresAtProperty: Attribute;
+	let createdTimeProperty: Attribute | undefined,
+		updatedTimeProperty: Attribute | undefined,
+		expiresAtProperty: Attribute | undefined;
 	for (const attribute of attributes) {
 		if (attribute.assignCreatedTime || attribute.name === '__createdtime__') createdTimeProperty = attribute;
 		if (attribute.assignUpdatedTime || attribute.name === '__updatedtime__') updatedTimeProperty = attribute;
@@ -223,6 +240,7 @@ export function makeTable(options) {
 		#savingOperation?: any; // operation for the record is currently being saved
 
 		declare getProperty: (name: string) => any;
+		// #section: static-config
 		static name = tableName; // for display/debugging purposes
 		static primaryStore = primaryStore;
 		static auditStore = auditStore;
@@ -241,6 +259,11 @@ export function makeTable(options) {
 		static updatedTimeProperty = updatedTimeProperty;
 		static propertyResolvers;
 		static userResolvers = {};
+		// `@embed` hook registry. `userSetEmbedders` records names set explicitly via
+		// `setEmbedAttribute` so a schema reload refreshes defaults without clobbering them.
+		static userEmbedders: { [name: string]: Embedder } = {};
+		static userSetEmbedders: Set<string> = new Set();
+		static embedAttributes: EmbedAttribute[] = (attributes as any[]).filter((a) => a?.embed);
 		static source?: typeof TableResource;
 		declare static sourceOptions: any;
 		declare static intermediateSource: boolean;
@@ -258,6 +281,7 @@ export function makeTable(options) {
 		 * @param options
 		 * @returns
 		 */
+		// #section: resource-registry
 		static sourcedFrom(source, options) {
 			// define a source for retrieving invalidated entries for caching purposes
 			if (options) {
@@ -503,10 +527,10 @@ export function makeTable(options) {
 									}
 								});
 								if (txnInProgress) txnInProgress.committed = commitResolution;
-								if (userRoleUpdate && commitResolution && !commitResolution?.waitingForUserChange) {
+								if (userRoleUpdate && commitResolution && !(commitResolution as any).waitingForUserChange) {
 									// if the user role changed, asynchronously signal the user change (but don't block this function)
 									commitResolution.then(() => signalling.signalUserChange(new UserEventMsg(process.pid)));
-									commitResolution.waitingForUserChange = true; // only need to send one signal per transaction
+									(commitResolution as any).waitingForUserChange = true; // only need to send one signal per transaction
 								}
 
 								if (event.onCommit) {
@@ -554,11 +578,7 @@ export function makeTable(options) {
 			}
 			return resource;
 		}
-		_loadRecord<Record extends object = any>(
-			target: RequestTarget,
-			request: Context,
-			resourceOptions?: any
-		): MaybePromise<TableResource<Record>> {
+		_loadRecord(target: RequestTarget, request: Context, resourceOptions?: any): MaybePromise<TableResource<Record>> {
 			const id = target && typeof target === 'object' ? target.id : target;
 			if (id == null) return this;
 			checkValidId(id);
@@ -587,9 +607,10 @@ export function makeTable(options) {
 							// return 504 (rather than 404) if there is no content and the cache-control header
 							// dictates not to go to source
 							if (!this.doesExist()) throw new ServerError('Entry is not cached', 504);
+							if (hasSourceGet && target) target.loadedFromSource = false; // mark it as cached
 						} else if (resourceOptions?.ensureLoaded) {
 							const loadingFromSource = ensureLoadedFromSource(
-								this.constructor.source,
+								(this.constructor as any).source,
 								id,
 								entry,
 								request,
@@ -598,7 +619,7 @@ export function makeTable(options) {
 							);
 							if (loadingFromSource) {
 								txn?.disregardReadTxn(); // this could take some time, so don't keep the transaction open if possible
-								return when(loadingFromSource, (entry) => {
+								return when(loadingFromSource as Promise<Entry>, (entry) => {
 									TableResource._updateResource(this, entry);
 									return this;
 								});
@@ -624,19 +645,20 @@ export function makeTable(options) {
 		 */
 		ensureLoaded() {
 			const loadedFromSource = ensureLoadedFromSource(
-				this.constructor.source,
+				(this.constructor as any).source,
 				this.getId(),
 				this.#entry,
 				this.getContext()
 			);
 			if (loadedFromSource) {
-				return when(loadedFromSource, (entry) => {
+				return when(loadedFromSource as Promise<Entry>, (entry) => {
 					this.#entry = entry;
 					this.#record = entry.value;
 					this.#version = entry.version;
 				});
 			}
 		}
+		// #section: lifecycle-admin
 		static getNewId(): any {
 			const type = primaryKeyAttribute?.type;
 			// the default Resource behavior is to return a GUID, but for a table we can return incrementing numeric keys if the type is (or can be) numeric
@@ -936,19 +958,13 @@ export function makeTable(options) {
 				new SchemaEventMsg(process.pid, OPERATIONS_ENUM.DROP_TABLE, databaseName, tableName)
 			);
 		}
-		/**
-		 * This retrieves the data of this resource. By default, with no argument, just return `this`.
-		 */
-		get(): TableResource<Record> | undefined;
+		// #section: read-path
 		/**
 		 * This retrieves the data of this resource.
 		 * @param target - If included, is an identifier/query that specifies the requested target to retrieve and query
 		 */
-		get(target: RequestTargetOrId): Record | AsyncIterable<Record> | Promise<Record | AsyncIterable<Record>>;
-		get(
-			target?: RequestTargetOrId
-		): TableResource<Record> | undefined | Record | AsyncIterable<Record> | Promise<Record | AsyncIterable<Record>> {
-			const constructor: Resource = this.constructor;
+		get(target?: any): any {
+			const constructor: any = this.constructor;
 			if (typeof target === 'string' && constructor.loadAsInstance !== false) return this.getProperty(target);
 			if (isSearchTarget(target)) {
 				// go back to the static search method so it gets a chance to override
@@ -966,7 +982,7 @@ export function makeTable(options) {
 					recordCount: undefined,
 					estimatedRecordRange: undefined,
 				};
-				if (this.getContext()?.includeExpensiveRecordCountEstimates) {
+				if ((this.getContext() as any)?.includeExpensiveRecordCountEstimates) {
 					return TableResource.getRecordCount().then((recordCount) => {
 						description.recordCount = recordCount.recordCount;
 						description.estimatedRecordRange = recordCount.estimatedRange;
@@ -976,7 +992,7 @@ export function makeTable(options) {
 				return description;
 			}
 			if (target !== undefined && constructor.loadAsInstance === false) {
-				const context = this.getContext();
+				const context: any = this.getContext();
 				const txn = txnForContext(context);
 				const readTxn = txn.getReadTxn();
 				if (readTxn?.isDone) {
@@ -985,7 +1001,7 @@ export function makeTable(options) {
 				const id = requestTargetToId(target);
 				checkValidId(id);
 				let allowed = true;
-				if (target.checkPermission) {
+				if ((target as any)?.checkPermission) {
 					// requesting authorization verification
 					allowed = this.allowRead(context.user, target, context);
 				}
@@ -1045,11 +1061,12 @@ export function makeTable(options) {
 				}
 				return promiseNormalize(record, target);
 			}
-			if (this.doesExist() || target?.ensureLoaded === false || this.getContext()?.returnNonexistent) {
+			if (this.doesExist() || target?.ensureLoaded === false || (this.getContext() as any)?.returnNonexistent) {
 				return this;
 			}
 			return undefined;
 		}
+		// #section: authz-hooks
 		/**
 		 * Determine if the user is allowed to get/read data from the current resource
 		 */
@@ -1063,20 +1080,20 @@ export function makeTable(options) {
 					// If attribute permissions are defined, we need to ensure there is a select that only returns the attributes the user has permission to
 					// or if there are relationships, we need to ensure that the user has permission to read from the related table
 					// Note that if we do not have a select, we do not return any relationships by default.
-					if (!target) target = {};
+					if (!target) target = {} as any;
 					if (select) {
 						const selectArray = Array.isArray(select) ? select : [select];
 						const attrsForType = attribute_permissions?.length > 0 && attributesAsObject(attribute_permissions, 'read');
-						target.select = selectArray
-							.map((property) => {
+						(target as any).select = selectArray
+							.map((property: any) => {
 								const propertyName = property.name || property;
 								if (!attrsForType || attrsForType[propertyName]) {
 									const relatedTable = propertyResolvers[propertyName]?.definition?.tableClass;
 									if (relatedTable) {
 										// if there is a related table, we need to ensure the user has permission to read from that table and that attributes are properly restricted
 										if (!property.name) property = { name: property };
-										if (!property.checkPermission && target.checkPermission)
-											property.checkPermission = target.checkPermission;
+										if (!property.checkPermission && (target as any).checkPermission)
+											property.checkPermission = (target as any).checkPermission;
 										if (!relatedTable.prototype.allowRead.call(null, user, property, context)) return false;
 										if (!property.select) return property.name; // no select was applied, just return the name
 									}
@@ -1160,6 +1177,7 @@ export function makeTable(options) {
 			return !!tablePermission?.delete && checkContextPermissions(context);
 		}
 
+		// #section: write-path-public
 		/**
 		 * Start updating a record. The returned resource will record changes which are written
 		 * once the corresponding transaction is committed. These changes can (eventually) include CRDT type operations.
@@ -1209,29 +1227,29 @@ export function makeTable(options) {
 					// updates that were passed into this method
 					let allowed = true;
 					if (target == undefined) throw new TypeError('Can not put a record without a target');
-					if (target.checkPermission) {
+					if ((target as any)?.checkPermission) {
 						// requesting authorization verification
-						allowed = this.allowUpdate(context.user, updates, context);
+						allowed = this.allowUpdate((context as any).user, updates, context);
 					}
 					return when(allowed, (allowed) => {
 						if (!allowed) {
-							throw new AccessViolation(context.user);
+							throw new AccessViolation((context as any).user);
 						}
 						let loading: Promise<any>;
-						if (!this.#entry && this.constructor.loadAsInstance === false) {
+						if (!this.#entry && (this.constructor as any).loadAsInstance === false) {
 							// load the record if it hasn't been done yet
 							loading = this._loadRecord(target, context, { ensureLoaded: true, async: true }) as Promise<any>;
 						}
 						return when(loading, () => {
 							this.#changes = updates;
-							this._writeUpdate(id, this.#changes, false);
-							return this;
+							// `when` awaits the embed hook (when `@embed` is active) before resolving,
+							// so the caller's `save()` doesn't run before the write is staged.
+							return when(this._writeUpdate(id, this.#changes, false), () => this);
 						});
 					});
 				}
 			}
-			this._writeUpdate(id, this.#changes, fullUpdate);
-			return this;
+			return when(this._writeUpdate(id, this.#changes, fullUpdate), () => this);
 		}
 
 		/**
@@ -1239,29 +1257,31 @@ export function makeTable(options) {
 		 */
 		save() {
 			if (this.#savingOperation) {
-				const transaction = txnForContext(this.getContext());
-				if (transaction.save) {
-					try {
-						return transaction.save(this.#savingOperation);
-					} finally {
-						this.#savingOperation = null;
-					}
+				try {
+					return this.#saveOperation(this.#savingOperation);
+				} finally {
+					this.#savingOperation = null;
 				}
 			}
 		}
+		#saveOperation(operation: any) {
+			const transaction = txnForContext(this.getContext());
+			if (transaction.save) return transaction.save(operation) || operation.promise || operation.result;
+		}
 
-		addTo(property, value) {
+		addTo(property: any, value: any) {
 			if (typeof value === 'number' || typeof value === 'bigint') {
-				if (this.#savingOperation?.fullUpdate) this.set(property, (+this.getProperty(property) || 0) + value);
+				if (this.#savingOperation?.fullUpdate)
+					(this as any).set(property, (+this.getProperty(property) || 0) + (value as any));
 				else {
-					if (!this.#savingOperation) this.update();
-					this.set(property, new Addition(value));
+					if (!this.#savingOperation) (this as any).update();
+					(this as any).set(property, new Addition(value));
 				}
 			} else {
 				throw new Error('Can not add a non-numeric value');
 			}
 		}
-		subtractFrom(property, value) {
+		subtractFrom(property: any, value: any) {
 			if (typeof value === 'number') {
 				return this.addTo(property, -value);
 			} else {
@@ -1289,11 +1309,11 @@ export function makeTable(options) {
 			const context = this.getContext();
 			if ((target as RequestTarget)?.checkPermission) {
 				// requesting authorization verification
-				allowed = this.allowDelete(context.user, target as RequestTarget, context);
+				allowed = this.allowDelete((context as any).user, target as any, context);
 			}
 			return when(allowed, (allowed: boolean) => {
 				if (!allowed) {
-					throw new AccessViolation(context.user);
+					throw new AccessViolation((context as any).user);
 				}
 				this._writeInvalidate(target ? requestTargetToId(target) : this.getId());
 			});
@@ -1330,7 +1350,7 @@ export function makeTable(options) {
 						INVALIDATED,
 						audit,
 						{
-							user: context?.user,
+							user: (context as any)?.user,
 							residencyId: options?.residencyId,
 							nodeId: options?.nodeId,
 							viaNodeId: options?.viaNodeId,
@@ -1355,8 +1375,8 @@ export function makeTable(options) {
 				invalidated: true,
 				entry: this.#entry,
 				before:
-					this.constructor.source?.relocate && !context?.source
-						? this.constructor.source.relocate.bind(this.constructor.source, id, undefined, context)
+					(this.constructor as any).source?.relocate && !(context as any)?.source
+						? (this.constructor as any).source.relocate.bind((this.constructor as any).source, id, undefined, context)
 						: undefined,
 				commit: (txnTime, existingEntry, _retry, transaction: any) => {
 					if (precedesExistingVersion(txnTime, existingEntry, options?.nodeId) <= 0) return;
@@ -1385,7 +1405,7 @@ export function makeTable(options) {
 						metadata,
 						audit,
 						{
-							user: context.user,
+							user: (context as any)?.user,
 							residencyId: options.residencyId,
 							nodeId: options.nodeId,
 							viaNodeId: options?.viaNodeId,
@@ -1469,12 +1489,12 @@ export function makeTable(options) {
 				committed = true;
 				if (primaryStore.ifVersion) {
 					// LMDB: committing the wrapper calls doneReadTxn(), removing it from trackedTxns
-					return lmdbTransaction.commit();
+					return (lmdbTransaction as any).commit();
 				}
 				// RocksDB: eviction writes went directly into the raw transaction via options;
 				// commit it directly, as DatabaseTransaction.commit() would abort it (no tracked writes).
 				// Wrap in Promise.resolve so callers can rely on a thenable return regardless of engine.
-				return Promise.resolve((transaction as any).commit());
+				return (transaction as any).commit();
 			} finally {
 				if (!committed) {
 					// Skip path or thrown error: abort instead of committing so we don't apply
@@ -1496,77 +1516,82 @@ export function makeTable(options) {
 		static operation(operation, context) {
 			operation.table ||= tableName;
 			operation.schema ||= databaseName;
-			return global.operation(operation, context);
+			return (global as any).operation(operation, context);
 		}
 
 		/**
 		 * Store the provided record data into the current resource. This is not written
 		 * until the corresponding transaction is committed.
 		 */
+		// @ts-expect-error The implementation intentionally uses a different argument order for back-compat
 		put(
 			target: RequestTarget,
 			record: Record & RecordObject
 		): void | (Record & Partial<RecordObject>) | Promise<void | (Record & Partial<RecordObject>)> {
 			if (record === undefined || record instanceof URLSearchParams) {
-				// legacy argument position, shift the arguments and go through the update method for back-compat
-				this.update(target, true);
-				return this.save();
+				// legacy argument position, shift the arguments and go through the update method for back-compat.
+				// `when` settles the embed hook before `save()` so the write is staged first.
+				return when((this as any).update(target, true), () => this.save() as any) as any;
 			} else {
 				let allowed = true;
 				if (target == undefined) throw new TypeError('Can not put a record without a target');
 				const context = this.getContext();
-				if (target.checkPermission) {
+				if ((target as any).checkPermission) {
 					// requesting authorization verification
-					allowed = this.allowUpdate(context.user, record, context);
+					allowed = this.allowUpdate((context as any).user, record, context);
 				}
 				return when(allowed, (allowed) => {
 					if (!allowed) {
-						throw new AccessViolation(context.user);
+						throw new AccessViolation((context as any).user);
 					}
 					// standard path, handle arrays as multiple updates, and otherwise do a direct update
 					if (Array.isArray(record)) {
-						return Promise.all(
-							record.map((element) => {
-								const id = element[primaryKey];
-								this._writeUpdate(id, element, true);
-								return this.save();
-							})
-						);
+						// Capture each element's operation synchronously (before any async `@embed`
+						// hook resolves): `#savingOperation` is a single field that parallel writes
+						// would otherwise clobber, so a deferred `save()` would commit the wrong op
+						// — e.g. one element's save running before a later element's vector is written.
+						const writes = record.map((element) => {
+							const id = element[primaryKey];
+							const writePromise = this._writeUpdate(id, element, true);
+							const operation = this.#savingOperation;
+							return when(writePromise, () => this.#saveOperation(operation));
+						});
+						this.#savingOperation = null;
+						return Promise.all(writes) as any;
 					} else {
-						const id = requestTargetToId(target);
-						this._writeUpdate(id, record, true);
-						return this.save();
+						const id = requestTargetToId(target as any);
+						return when(this._writeUpdate(id, record, true), () => this.save() as any);
 					}
-				});
+				}) as any;
 			}
 			// always return undefined
 		}
 
 		create(
-			target: RequestTarget,
+			target: RequestTargetOrId,
 			record: Partial<Record & RecordObject>
 		): void | (Record & Partial<RecordObject>) | Promise<Record & Partial<RecordObject>> {
 			let allowed = true;
 			const context = this.getContext();
 			if (!record && !(target instanceof URLSearchParams)) {
 				// single argument, shift arguments
-				record = target;
+				record = target as any;
 				target = undefined;
 			}
 			if (!record || typeof record !== 'object' || Array.isArray(record)) {
 				throw new TypeError('Can not create a record without an object');
 			}
-			if (target?.checkPermission) {
+			if ((target as any)?.checkPermission) {
 				// requesting authorization verification
-				allowed = this.allowCreate(context.user, record, context);
+				allowed = this.allowCreate((context as any).user, record as any, context);
 			}
 			return when(allowed, (allowed) => {
 				if (!allowed) {
-					throw new AccessViolation(context.user);
+					throw new AccessViolation((context as any).user);
 				}
-				let id = requestTargetToId(target) ?? record[primaryKey];
+				let id = requestTargetToId(target as any) ?? record[primaryKey];
 				if (id === undefined) {
-					id = this.constructor.getNewId();
+					id = (this.constructor as any).getNewId();
 					record[primaryKey] = id; // make this immediately available
 				} else {
 					const existing = primaryStore.getSync(id);
@@ -1574,9 +1599,11 @@ export function makeTable(options) {
 						throw new ClientError('Record already exists', 409);
 					}
 				}
-				this._writeUpdate(id, record, true);
-				return record;
-			});
+				// `_writeUpdate` may return a promise when an `@embed` directive
+				// requires running an embedder before the per-write `commit(...)`
+				// closure. `when()` passes through synchronous returns.
+				return when(this._writeUpdate(id, record, true), () => record);
+			}) as any;
 		}
 
 		// @ts-expect-error The implementation handles the possibility of target and recordUpdate being swapped
@@ -1585,39 +1612,39 @@ export function makeTable(options) {
 			recordUpdate: Partial<Record & RecordObject>
 		): void | (Record & Partial<RecordObject>) | Promise<void | (Record & Partial<RecordObject>)> {
 			if (recordUpdate === undefined || recordUpdate instanceof URLSearchParams) {
-				// legacy argument position, shift the arguments and go through the update method for back-compat
-				this.update(target, false);
-				return this.save();
+				// legacy argument position, shift the arguments and go through the update method for back-compat.
+				// `when` settles the embed hook before `save()` so the write is staged first.
+				return when(this.update(target, false), () => this.save() as any) as any;
 			} else {
 				// standard path, ensure there is no return object
 				return when(this.update(target, recordUpdate), () => {
-					return when(this.save(), () => undefined); // wait for the update and save, but return undefined
-				});
+					return when(this.save() as any, () => undefined); // wait for the update and save, but return undefined
+				}) as any;
 			}
 		}
+		// #section: write-path-internals
 		// perform the actual write operation; this may come from a user request to write (put, post, etc.), or
 		// a notification that a write has already occurred in the canonical data source, we need to update our
 		// local copy
 		_writeUpdate(id: Id, recordUpdate: any, fullUpdate: boolean, options?: any) {
 			const context = this.getContext();
 			const transaction = txnForContext(context);
-
 			checkValidId(id);
 			const entry = this.#entry ?? primaryStore.getEntry(id, { transaction: transaction.getReadTxn() });
 			const writeToSource = () => {
-				if (!this.constructor.source || context?.source) return;
+				if (!(this.constructor as any).source || (context as any)?.source) return;
 				if (fullUpdate) {
 					// full update is a put
-					if (this.constructor.source.put) {
-						return () => this.constructor.source.put(id, recordUpdate, context);
+					if ((this.constructor as any).source.put) {
+						return () => (this.constructor as any).source.put(id, recordUpdate, context);
 					}
 				} else {
 					// incremental update
-					if (this.constructor.source.patch) {
-						return () => this.constructor.source.patch(id, recordUpdate, context);
-					} else if (this.constructor.source.put) {
+					if ((this.constructor as any).source.patch) {
+						return () => (this.constructor as any).source.patch(id, recordUpdate, context);
+					} else if ((this.constructor as any).source.put) {
 						// if this is incremental, but only have put, we can use that by generating the full record (at least the expected one)
-						return () => this.constructor.source.put(id, updateAndFreeze(this), context);
+						return () => (this.constructor as any).source.put(id, updateAndFreeze(this), context);
 					}
 				}
 			};
@@ -1626,13 +1653,13 @@ export function makeTable(options) {
 				key: id,
 				store: primaryStore,
 				entry,
-				nodeName: context?.nodeName,
+				nodeName: (context as any)?.nodeName,
 				fullUpdate,
 				deferSave: true,
 				validate: (txnTime) => {
 					if (!recordUpdate) recordUpdate = this.#changes;
 					if (fullUpdate || (recordUpdate && hasChanges(this.#changes === recordUpdate ? this : recordUpdate))) {
-						if (!context?.source) {
+						if (!(context as any)?.source) {
 							transaction.checkOverloaded();
 							this.validate(recordUpdate, !fullUpdate);
 							if (updatedTimeProperty) {
@@ -1669,7 +1696,7 @@ export function makeTable(options) {
 							// TODO: else freeze after we have applied the changes
 						}
 					} else {
-						transaction.removeWrite?.(write);
+						(transaction as any).removeWrite?.(write);
 						return false;
 					}
 				},
@@ -1853,7 +1880,7 @@ export function makeTable(options) {
 					let recordToStore: any;
 					if (fullUpdate && !incrementalUpdateToApply) recordToStore = recordUpdate;
 					else {
-						if (this.constructor.loadAsInstance === false)
+						if ((this.constructor as any).loadAsInstance === false)
 							recordToStore = updateAndFreeze(existingRecord, incrementalUpdateToApply ?? recordUpdate);
 						else {
 							this.#record = existingRecord;
@@ -1864,7 +1891,8 @@ export function makeTable(options) {
 					if (recordToStore && recordToStore.getRecord)
 						throw new Error('Can not assign a record to a record, check for circular references');
 					if (residencyId == undefined) {
-						if (entry?.residencyId) context.previousResidency = TableResource.getResidencyRecord(entry.residencyId);
+						if (entry?.residencyId)
+							(context as any).previousResidency = TableResource.getResidencyRecord(entry.residencyId);
 						const residency = residencyFromFunction(TableResource.getResidency(recordToStore, context));
 						if (residency) {
 							if (!residency.includes(server.hostname)) {
@@ -1931,12 +1959,12 @@ export function makeTable(options) {
 							audit,
 							{
 								omitLocalRecord,
-								user: context?.user,
+								user: (context as any)?.user,
 								residencyId,
 								expiresAt,
 								nodeId: options?.nodeId,
 								viaNodeId: options?.viaNodeId,
-								originatingOperation: context?.originatingOperation,
+								originatingOperation: (context as any)?.originatingOperation,
 								transaction,
 								tableToTrack: databaseName === 'system' ? null : options?.replay ? null : tableName, // don't track analytics on system tables
 								additionalAuditRefs: additionalAuditRefs.length > 0 ? additionalAuditRefs : undefined,
@@ -1949,33 +1977,52 @@ export function makeTable(options) {
 				},
 			};
 			this.#savingOperation = write;
-			write.beforeIntermediate = preCommitBlobsForRecordBefore(write, recordUpdate);
-			return transaction.addWrite(write);
+			// `@embed` hook must run before `addWrite` so the embedder's vector is on the
+			// record when `commit` runs. (The txn `before` slot runs after commit, which
+			// suits blob writes but not embedding, where the vector must be present at commit.)
+			// Known limitation of this write-time placement (a validate-time alternative was
+			// tried and reverted as a Harper-foreign pattern): the embedder sees this write's
+			// payload, before table validation — so a write that later fails validation still
+			// calls the backend, and a tracked-instance mutation (update(id,{}); row.source=…;
+			// save()) that sets the source via accessors after update() won't re-embed. A
+			// resource-layer re-embed is the proper fix; tracked as a follow-up.
+			const embedBefore = buildEmbedBefore(
+				recordUpdate,
+				context,
+				options,
+				TableResource.embedAttributes,
+				TableResource.userEmbedders
+			);
+			const proceed = (): any => {
+				write.beforeIntermediate = preCommitBlobsForRecordBefore(write, recordUpdate);
+				return transaction.addWrite(write as any);
+			};
+			return embedBefore ? embedBefore().then(proceed) : proceed();
 		}
 
 		async delete(target: RequestTargetOrId): Promise<boolean> {
 			if (isSearchTarget(target)) {
 				target.select = ['$id']; // just get the primary key of each record so we can delete them
 				for await (const entry of this.search(target)) {
-					this._writeDelete(entry.$id);
+					this._writeDelete((entry as any).$id);
 				}
 				return true;
 			}
 			if (target) {
 				let allowed = true;
 				const context = this.getContext();
-				if (target.checkPermission) {
+				if ((target as any)?.checkPermission) {
 					// requesting authorization verification
-					allowed = this.allowDelete(context.user, target, context);
+					allowed = this.allowDelete((context as any).user, target as any, context);
 				}
 				return when(allowed, (allowed: boolean) => {
 					if (!allowed) {
-						throw new AccessViolation(context.user);
+						throw new AccessViolation((context as any).user);
 					}
-					const id = requestTargetToId(target);
+					const id = requestTargetToId(target as any);
 					this._writeDelete(id);
 					return true;
-				});
+				}) as any;
 			}
 			this._writeDelete(this.getId());
 			return Boolean(this.#record);
@@ -1990,10 +2037,10 @@ export function makeTable(options) {
 				key: id,
 				store: primaryStore,
 				entry,
-				nodeName: context?.nodeName,
+				nodeName: (context as any)?.nodeName,
 				before:
-					this.constructor.source?.delete && !context?.source
-						? this.constructor.source.delete.bind(this.constructor.source, id, undefined, context)
+					(this.constructor as any).source?.delete && !(context as any)?.source
+						? (this.constructor as any).source.delete.bind((this.constructor as any).source, id, undefined, context)
 						: undefined,
 				commit: (txnTime, existingEntry, retry, transaction: any) => {
 					const existingRecord = existingEntry?.value;
@@ -2015,7 +2062,7 @@ export function makeTable(options) {
 							0,
 							audit,
 							{
-								user: context?.user,
+								user: (context as any)?.user,
 								nodeId: options?.nodeId,
 								viaNodeId: options?.viaNodeId,
 								transaction,
@@ -2028,10 +2075,11 @@ export function makeTable(options) {
 						removeEntry(primaryStore, existingEntry);
 					}
 				},
-			});
+			} as any);
 			return true;
 		}
 
+		// #section: search-query
 		search(target: RequestTarget): AsyncIterable<Record & Partial<RecordObject>> {
 			const context = this.getContext();
 			const txn = txnForContext(context);
@@ -2039,14 +2087,14 @@ export function makeTable(options) {
 			if (target.parseError) throw target.parseError; // if there was a parse error, we can throw it now
 			if (target.checkPermission) {
 				// requesting authorization verification
-				const allowed = this.allowRead(context.user, target, context);
+				const allowed = this.allowRead((context as any).user, target, context);
 				if (!allowed) {
-					throw new AccessViolation(context.user);
+					throw new AccessViolation((context as any).user);
 				}
 			}
 			if (context) context.lastModified = UNCACHEABLE_TIMESTAMP;
 
-			let conditions = target.conditions;
+			let conditions: any = target.conditions;
 			if (!conditions) conditions = Array.isArray(target) ? target : target[Symbol.iterator] ? Array.from(target) : [];
 			else if (conditions.length === undefined) {
 				conditions = conditions[Symbol.iterator] ? Array.from(conditions) : [conditions];
@@ -2064,7 +2112,7 @@ export function makeTable(options) {
 			let orderAlignedCondition;
 			const filtered = {};
 
-			function prepareConditions(conditions: Condition[], operator: string) {
+			function prepareConditions(conditions: any[], operator: string) {
 				// some validation:
 				switch (operator) {
 					case 'and':
@@ -2082,15 +2130,37 @@ export function makeTable(options) {
 						condition.conditions = prepareConditions(condition.conditions, condition.operator);
 						continue;
 					}
+					// Normalize `not_X` comparator forms passed in via structured queries.
+					// The REST parser already does this, but programmatic callers may
+					// pass `not_in`, `not_starts_with`, etc. directly.
+					if (condition.comparator) {
+						const resolved = resolveComparator(condition.comparator);
+						if (resolved.negated) {
+							condition.comparator = resolved.comparator;
+							condition.negated = true;
+						}
+					}
 					const attribute_name = condition[0] ?? condition.attribute;
-					const attribute = attribute_name == null ? primaryKeyAttribute : findAttribute(attributes, attribute_name);
+					let attribute = attribute_name == null ? primaryKeyAttribute : findAttribute(attributes, attribute_name);
+					if (!attribute && Array.isArray(attribute_name) && attribute_name.length > 1) {
+						// Plain JSON nested path: the leaf may not be declared in the
+						// schema. Fall back to the root attribute so we can validate
+						// existence without requiring the inner structure to be typed.
+						attribute = findAttribute(attributes, attribute_name[0]);
+					}
 					if (!attribute) {
 						if (attribute_name != null && !target.allowConditionsOnDynamicAttributes)
 							throw handleHDBError(new Error(), `${attribute_name} is not a defined attribute`, 404);
 					} else if (attribute.type || COERCIBLE_OPERATORS[condition.comparator]) {
-						// Do auto-coercion or coercion as required by the attribute type
-						if (condition[1] === undefined) condition.value = coerceTypedValues(condition.value, attribute);
-						else condition[1] = coerceTypedValues(condition[1], attribute);
+						// Do auto-coercion or coercion as required by the attribute type.
+						// Skipped for nested paths into plain JSON — the root attribute's
+						// type is not the leaf type, so coercion would be wrong.
+						const isNestedPathRoot =
+							Array.isArray(attribute_name) && attribute_name.length > 1 && !attribute.relationship;
+						if (!isNestedPathRoot) {
+							if (condition[1] === undefined) condition.value = coerceTypedValues(condition.value, attribute);
+							else condition[1] = coerceTypedValues(condition[1], attribute);
+						}
 					}
 					if (condition.chainedConditions) {
 						if (condition.chainedConditions.length === 1 && (!condition.operator || condition.operator == 'and')) {
@@ -2120,7 +2190,7 @@ export function makeTable(options) {
 							}
 							const isGe = lower.comparator === 'ge' || lower.comparator === 'greater_than_equal';
 							const isLe = upper.comparator === 'le' || upper.comparator === 'less_than_equal';
-							condition.comparator = (isGe ? 'ge' : 'gt') + (isLe ? 'le' : 'lt');
+							condition.comparator = ((isGe ? 'ge' : 'gt') + (isLe ? 'le' : 'lt')) as any;
 							condition.value = [lower.value, upper.value];
 						} else throw new Error('Multiple chained conditions are not currently supported');
 					}
@@ -2150,11 +2220,11 @@ export function makeTable(options) {
 			let postOrdering;
 			if (sort) {
 				// TODO: Support index-assisted sorts of unions, which will require potentially recursively adding/modifying an order aligned condition and be able to recursively undo it if necessary
-				if (operator !== 'or') {
+				if ((operator as any) !== 'or') {
 					const attribute_name = sort.attribute;
 					if (attribute_name == undefined) throw new ClientError('Sort requires an attribute');
 					orderAlignedCondition = conditions.find(
-						(condition) => flattenKey(condition.attribute) === flattenKey(attribute_name)
+						(condition) => flattenKey(condition.attribute as any) === flattenKey(attribute_name as any)
 					);
 					if (orderAlignedCondition) {
 						// if there is a condition on the same attribute as the first sort, we can use it to align the sort
@@ -2165,7 +2235,7 @@ export function makeTable(options) {
 							throw handleHDBError(
 								new Error(),
 								`${
-									Array.isArray(attribute_name) ? attribute_name.join('.') : attribute_name
+									Array.isArray(attribute_name) ? (attribute_name as any).join('.') : attribute_name
 								} is not a defined attribute`,
 								404
 							);
@@ -2177,7 +2247,7 @@ export function makeTable(options) {
 							throw handleHDBError(
 								new Error(),
 								`${
-									Array.isArray(attribute_name) ? attribute_name.join('.') : attribute_name
+									Array.isArray(attribute_name) ? (attribute_name as any).join('.') : attribute_name
 								} is not indexed and not combined with any other conditions`,
 								404
 							);
@@ -2213,7 +2283,7 @@ export function makeTable(options) {
 					operator,
 					postOrdering,
 					selectApplied: Boolean(select),
-				};
+				} as any;
 			}
 			// we mark the read transaction as in use (necessary for a stable read
 			// transaction, and we really don't care if the
@@ -2230,7 +2300,7 @@ export function makeTable(options) {
 				(results: any[], filters: Function[]) => transformToEntries(results, select, context, readTxn, filters),
 				filtered
 			);
-			const ensure_loaded = target.ensureLoaded !== false;
+			const ensure_loaded = (target as any).ensureLoaded !== false;
 			const transformToRecord = TableResource.transformEntryForSelect(
 				select,
 				context,
@@ -2263,7 +2333,7 @@ export function makeTable(options) {
 					const columns = [];
 					for (const column of select) {
 						if (column === '*') columns.push(...attributes.map((attribute) => attribute.name));
-						else columns.push(column.name || column);
+						else columns.push((column as any).name || column);
 					}
 					return columns;
 				}
@@ -2303,14 +2373,14 @@ export function makeTable(options) {
 							? entries[Symbol.asyncIterator]()
 							: entries[Symbol.iterator]();
 					let dbDone: boolean;
-					const dbOrderedAttribute = sort.dbOrderedAttribute;
+					const dbOrderedAttribute = (sort as any).dbOrderedAttribute;
 					let enqueuedEntryForNextGroup: any;
 					let lastGroupingValue: any;
 					let firstEntry = true;
 					function createComparator(order: Sort) {
 						const nextComparator = order.next && createComparator(order.next);
 						const descending = order.descending;
-						context.sort = order; // make sure this is set to the current sort order
+						(context as any).sort = order; // make sure this is set to the current sort order
 						return (entryA, entryB) => {
 							const a = getAttributeValue(entryA, order.attribute, context);
 							const b = getAttributeValue(entryB, order.attribute, context);
@@ -2369,7 +2439,7 @@ export function makeTable(options) {
 									ordered.push(entry);
 								}
 							} while (true);
-							if (sort.isGrouped) {
+							if ((sort as any).isGrouped) {
 								// TODO: Return grouped results
 							}
 							ordered.sort(comparator);
@@ -2397,8 +2467,8 @@ export function makeTable(options) {
 						for (let i = 0; i < select.length; i++) {
 							const column = select[i];
 							let columnSort;
-							if (column.name === sort.attribute[0]) {
-								columnSort = column.sort || (column.sort = {});
+							if ((column as any).name === sort.attribute[0]) {
+								columnSort = (column as any).sort || ((column as any).sort = {});
 								while (columnSort.next) columnSort = columnSort.next;
 								columnSort.attribute = sort.attribute.slice(1);
 								columnSort.descending = sort.descending;
@@ -2409,7 +2479,7 @@ export function makeTable(options) {
 										attribute: sort.attribute.slice(1),
 										descending: sort.descending,
 									},
-								};
+								} as any;
 							}
 						}
 					}
@@ -2492,7 +2562,7 @@ export function makeTable(options) {
 							this?.isSync,
 							(entry: Entry) => entry
 						);
-						if (entry?.then) return entry.then(transform.bind(this));
+						if ((entry as any)?.then) return (entry as any).then(transform.bind(this));
 						record = entry?.value;
 					}
 					if (
@@ -2602,12 +2672,22 @@ export function makeTable(options) {
 						} else {
 							value = record[attribute_name];
 							if (value && typeof value === 'object' && attribute_name !== attribute) {
-								value = TableResource.transformEntryForSelect(
+								const subTransform = TableResource.transformEntryForSelect(
 									attribute.select || attribute,
 									context,
 									readTxn,
 									null
-								)({ value });
+								);
+								// Plain JSON nested values: arrays project per-element so that
+								// `select: [{ name: 'addresses', select: ['city'] }]` returns
+								// `addresses: [{ city }, { city }]` rather than a single object.
+								if (Array.isArray(value)) {
+									value = value.map((item) =>
+										item && typeof item === 'object' ? subTransform({ value: item } as any) : item
+									);
+								} else if (!(value instanceof Date)) {
+									value = subTransform({ value } as any);
+								}
 							}
 						}
 						callback(value, attribute_name);
@@ -2618,7 +2698,7 @@ export function makeTable(options) {
 							selected = value;
 						});
 					} else if (Array.isArray(select)) {
-						if (select.asArray) {
+						if ((select as any).asArray) {
 							selected = [];
 							select.forEach((attribute, index) => {
 								if (attribute === '*') select[index] = record;
@@ -2626,7 +2706,7 @@ export function makeTable(options) {
 							});
 						} else {
 							selected = {};
-							const forceNulls = select.forceNulls;
+							const forceNulls = (select as any).forceNulls;
 							for (const attribute of select) {
 								if (attribute === '*')
 									for (const key in record) {
@@ -2650,12 +2730,13 @@ export function makeTable(options) {
 			return transform;
 		}
 
+		// #section: pub-sub
 		async subscribe(request: SubscriptionRequest): Promise<AsyncIterable<Record>> {
 			if (!auditStore) throw new Error('Can not subscribe to a table without an audit log');
 			if (!audit) {
 				table({ table: tableName, database: databaseName, schemaDefined, attributes, audit: true });
 			}
-			if (!request) request = {};
+			if (!request) request = {} as any;
 			const getFullRecord = !request.rawEvents;
 			// While the count, !omitCurrent, and non-collection branches replay older messages, real-time
 			// messages from the listener accumulate here and are drained at the end of the IIFE so they
@@ -2670,7 +2751,7 @@ export function makeTable(options) {
 			const subscription = addSubscription(
 				TableResource,
 				thisId,
-				function (id: Id, auditRecord: any, localTime: number, beginTxn: boolean) {
+				function (id: Id, auditRecord?: any, localTime?: any, beginTxn?: any) {
 					if (dropDuringReplay) return;
 					try {
 						let type = auditRecord.type;
@@ -2969,13 +3050,13 @@ export function makeTable(options) {
 			} else {
 				let allowed = true;
 				const context = this.getContext();
-				if (target.checkPermission) {
+				if ((target as any)?.checkPermission) {
 					// requesting authorization verification
-					allowed = this.allowCreate(context.user, message, context);
+					allowed = this.allowDelete((context as any).user, target as any, context);
 				}
 				return when(allowed, (allowed: boolean) => {
 					if (!allowed) {
-						throw new AccessViolation(context.user);
+						throw new AccessViolation((context as any).user);
 					}
 					const id = requestTargetToId(target);
 					this._writePublish(id, message, options);
@@ -2991,16 +3072,16 @@ export function makeTable(options) {
 				key: id,
 				store: primaryStore,
 				entry: this.#entry,
-				nodeName: context?.nodeName,
+				nodeName: (context as any)?.nodeName,
 				validate: () => {
-					if (!context?.source) {
+					if (!(context as any)?.source) {
 						transaction.checkOverloaded();
 						this.validate(message);
 					}
 				},
 				before:
-					this.constructor.source?.publish && !context?.source
-						? this.constructor.source.publish.bind(this.constructor.source, id, message, context)
+					(this.constructor as any).source?.publish && !(context as any)?.source
+						? (this.constructor as any).source.publish.bind((this.constructor as any).source, id, message, context)
 						: undefined,
 				commit: (txnTime, existingEntry, _retry, transaction: any) => {
 					// just need to update the version number of the record so it points to the latest audit record
@@ -3021,7 +3102,7 @@ export function makeTable(options) {
 						0,
 						true,
 						{
-							user: context?.user,
+							user: (context as any)?.user,
 							residencyId: options?.residencyId,
 							expiresAt: context?.expiresAt,
 							nodeId: options?.nodeId,
@@ -3039,6 +3120,7 @@ export function makeTable(options) {
 			write.beforeIntermediate = preCommitBlobsForRecordBefore(write, message, undefined, true);
 			transaction.addWrite(write);
 		}
+		// #section: validation
 		validate(record: any, patch?: boolean) {
 			let validationErrors;
 			const validateValue = (value, attribute: Attribute, name) => {
@@ -3208,6 +3290,7 @@ export function makeTable(options) {
 				throw new ClientError(validationErrors.join('. '));
 			}
 		}
+		// #section: stats-admin
 		getUpdatedTime() {
 			return this.#version;
 		}
@@ -3226,7 +3309,7 @@ export function makeTable(options) {
 				schemaDefined,
 				attributes: new_attributes,
 			});
-			return TableResource.indexingOperation;
+			return (TableResource as any).indexingOperation;
 		}
 		static async removeAttributes(names: string[]) {
 			const new_attributes = attributes.filter((attribute) => !names.includes(attribute.name));
@@ -3236,7 +3319,7 @@ export function makeTable(options) {
 				schemaDefined,
 				attributes: new_attributes,
 			});
-			return TableResource.indexingOperation;
+			return (TableResource as any).indexingOperation;
 		}
 		/**
 		 * Get the size of the table in bytes (based on amount of pages stored in the database)
@@ -3329,6 +3412,14 @@ export function makeTable(options) {
 		 * When attributes have been changed, we update the accessors that are assigned to this table
 		 */
 		static updatedAttributes() {
+			// Refresh on every call: schema reload mutates `attributes` in place, so the
+			// class-construction snapshot would otherwise go stale.
+			this.embedAttributes = (this.attributes as any[]).filter((a) => a?.embed);
+			// Drop registry entries for attributes that are no longer `@embed`, so a dropped
+			// directive doesn't leave a stale embedder or block a default refresh on re-add.
+			const embedNames = new Set(this.embedAttributes.map((a) => a.name));
+			for (const name of Object.keys(this.userEmbedders)) if (!embedNames.has(name)) delete this.userEmbedders[name];
+			for (const name of this.userSetEmbedders) if (!embedNames.has(name)) this.userSetEmbedders.delete(name);
 			propertyResolvers = this.propertyResolvers = {
 				$id: (object, context, entry) => ({ value: entry.key }),
 				$updatedtime: (object, context, entry) => entry.version,
@@ -3344,6 +3435,11 @@ export function makeTable(options) {
 				attribute.resolve = null; // reset this
 				const relationship = attribute.relationship;
 				const computed = attribute.computed;
+				// Register the default embedder unless an author override is set. Sits outside
+				// the resolver chain below so `@embed` fields still flow through auto-HNSW indexing.
+				if (attribute.embed && !TableResource.userSetEmbedders.has(attribute.name)) {
+					this.userEmbedders[attribute.name] = createDefaultEmbedder(attribute.embed);
+				}
 				if (relationship) {
 					if (attribute.indexed) {
 						console.error(
@@ -3363,12 +3459,14 @@ export function makeTable(options) {
 								const id = object[relationship.from ? relationship.from : primaryKey];
 								const relatedTable = attribute.elements.definition.tableClass;
 								if (returnEntry) {
-									return searchByIndex(
-										{ attribute: relationship.to, value: id },
-										txnForContext(context).getReadTxn(),
-										false,
-										relatedTable,
-										false
+									return (
+										searchByIndex(
+											{ attribute: relationship.to, value: id },
+											txnForContext(context).getReadTxn(),
+											false,
+											relatedTable,
+											false
+										) as any
 									).map((entry) => {
 										if (entry && entry.key !== undefined) return entry;
 										return relatedTable.primaryStore.getEntry(entry, {
@@ -3449,6 +3547,15 @@ export function makeTable(options) {
 				} else if (computed) {
 					if (typeof computed.from === 'function') {
 						this.setComputedAttribute(attribute.name, computed.from);
+					} else if (attribute.computedFromExpression) {
+						// build a fallback scope object with all attribute names set to undefined,
+						// matching the behavior in graphql.ts to prevent ReferenceErrors
+						const attributesFallback: { [key: string]: undefined } = {};
+						for (const attr of this.attributes) attributesFallback[attr.name] = undefined;
+						this.setComputedAttribute(
+							attribute.name,
+							createComputedFrom(attribute.computedFromExpression, attributesFallback)
+						);
 					}
 					propertyResolvers[attribute.name] = attribute.resolve = (object, context, entry) => {
 						const value = typeof computed.from === 'string' ? object[computed.from] : object;
@@ -3503,6 +3610,7 @@ export function makeTable(options) {
 				}
 			}
 		}
+		// #section: computed-history
 		static setComputedAttribute(attribute_name, resolver) {
 			const attribute = findAttribute(attributes, attribute_name);
 			if (!attribute) {
@@ -3515,6 +3623,25 @@ export function makeTable(options) {
 			}
 			this.userResolvers[attribute_name] = resolver;
 		}
+		/**
+		 * Override the default embedder for an `@embed` attribute. Return the vector to
+		 * store at `attribute_name`. The embedder receives the write payload (the fields
+		 * present in the PUT/PATCH body), not the post-merge record, so multi-field
+		 * concatenation only works when all source fields are in the same write.
+		 */
+		static setEmbedAttribute(attribute_name: string, embedder: Embedder): void {
+			const attribute = findAttribute(attributes, attribute_name);
+			if (!attribute) {
+				console.error(`The attribute "${attribute_name}" does not exist in the table "${tableName}"`);
+				return;
+			}
+			if (!attribute.embed) {
+				console.error(`The attribute "${attribute_name}" is not declared with @embed in the table "${tableName}"`);
+				return;
+			}
+			this.userEmbedders[attribute_name] = embedder;
+			this.userSetEmbedders.add(attribute_name);
+		}
 		static async deleteHistory(endTime = 0, cleanupDeletedRecords = false) {
 			let completion: Promise<void>;
 			for (const auditRecord of auditStore.getRange({
@@ -3688,34 +3815,35 @@ export function makeTable(options) {
 	function checkValidId(id) {
 		switch (typeof id) {
 			case 'number':
+				if (isNaN(id)) throw new ClientError('Invalid primary key of NaN', 400);
 				return true;
 			case 'string':
 				if (id.length < 659) return true; // max number of characters that can't expand our key size limit
 				if (id.length > MAX_KEY_BYTES) {
 					// we can quickly determine this is too big
-					throw new Error('Primary key size is too large: ' + id.length);
+					throw new ClientError('Primary key size is too large: ' + id.length, 400);
 				}
 				// TODO: We could potentially have a faster test here, Buffer.byteLength is close, but we have to handle characters < 4 that are escaped in ordered-binary
 				break; // otherwise we have to test it, in this range, unicode characters could put it over the limit
 			case 'object':
 				if (id === null) {
-					throw new Error('Invalid primary key of null');
+					throw new ClientError('Invalid primary key of null', 400);
 				}
 				break; // otherwise we have to test it
 			case 'bigint':
 				if (id < 2n ** 64n && id > -(2n ** 64n)) return true;
 				break; // otherwise we have to test it
 			default:
-				throw new Error('Invalid primary key type: ' + typeof id);
+				throw new ClientError('Invalid primary key type: ' + typeof id, 400);
 		}
 		// otherwise it is difficult to determine if the key size is too large
 		// without actually attempting to serialize it
 		const length = writeKey(id, TEST_WRITE_KEY_BUFFER, 0);
-		if (length > MAX_KEY_BYTES) throw new Error('Primary key size is too large: ' + id.length);
+		if (length > MAX_KEY_BYTES) throw new ClientError('Primary key size is too large: ' + id.length, 400);
 		return true;
 	}
 	function requestTargetToId(target: RequestTargetOrId): Id {
-		return typeof target === 'object' && target ? target.id : (target as Id);
+		return typeof target === 'object' && target ? (target as any).id : (target as Id);
 	}
 	function isSearchTarget(target: RequestTargetOrId): target is RequestTarget {
 		return typeof target === 'object' && target && (target as RequestTarget).isCollection;
@@ -3874,6 +4002,10 @@ export function makeTable(options) {
 	}
 
 	function ensureLoadedFromSource(source: typeof TableResource, id, entry, context, resource?, target?) {
+		if (context?.onlyIfCached) {
+			if (!entry?.value) throw new ServerError('Entry is not cached', 504);
+			return;
+		}
 		if (hasSourceGet) {
 			let needsSourceData = false;
 			if (context.noCache) needsSourceData = true;
@@ -3902,10 +4034,9 @@ export function makeTable(options) {
 					return entry;
 				});
 				// if the resource defines a method for indicating if stale-while-revalidate is allowed for a record
-				if (context?.onlyIfCached || (entry?.value && resource?.allowStaleWhileRevalidate?.(entry, id))) {
+				if (entry?.value && resource?.allowStaleWhileRevalidate?.(entry, id)) {
 					// since we aren't waiting for it any errors won't propagate so we should at least log them
 					loadingFromSource.catch((error) => logger.warn?.(error));
-					if (context?.onlyIfCached && !resource.doesExist()) throw new ServerError('Entry is not cached', 504);
 					return; // go ahead and return and let the current stale value be used while we re-validate
 				} else return loadingFromSource; // return the promise for the resolved value
 			}
@@ -3928,7 +4059,7 @@ export function makeTable(options) {
 		if (transaction) {
 			if (!transaction.db && isRocksDB) {
 				// this is an uninitialized DatabaseTransaction, we can claim it
-				transaction.db = primaryStore;
+				transaction.db = primaryStore as any;
 				if (context?.timestamp) transaction.timestamp = context.timestamp;
 				return transaction;
 			}
@@ -3951,7 +4082,9 @@ export function makeTable(options) {
 				transaction = nextTxn;
 			} while (true);
 		} else {
-			transaction = isRocksDB ? new ImmediateTransaction(primaryStore) : new ImmediateLMDBTransaction(primaryStore);
+			transaction = (
+				isRocksDB ? new ImmediateTransaction(primaryStore as any) : new ImmediateLMDBTransaction(primaryStore as any)
+			) as any;
 			if (context) {
 				context.transaction = transaction;
 				if (context.timestamp) transaction.timestamp = context.timestamp;
@@ -4030,7 +4163,7 @@ export function makeTable(options) {
 		return ids;
 	}
 
-	function precedesExistingVersion(txnTime: number, existingEntry: Entry, nodeId?: number): number {
+	function precedesExistingVersion(txnTime: number, existingEntry: Partial<Entry>, nodeId?: number): number {
 		if (nodeId === undefined) {
 			nodeId = getThisNodeId(auditStore);
 		}
@@ -4132,7 +4265,7 @@ export function makeTable(options) {
 			expiresAt: undefined,
 			lastModified: undefined,
 		};
-		const responseHeaders = context?.responseHeaders;
+		const responseHeaders = (context as any)?.responseHeaders;
 		return new Promise((resolve, reject) => {
 			// we don't want to wait for the transaction because we want to return as fast as possible
 			// and let the transaction commit in the background
@@ -4157,15 +4290,14 @@ export function makeTable(options) {
 							if (typeof updatedRecord !== 'object') throw new Error('Only objects can be cached and stored in tables');
 							if (updatedRecord.status > 0 && updatedRecord.headers) {
 								// if the source has a status code and headers, treat it as a response
-								if (updatedRecord.status >= 300) {
-									if (updatedRecord.status === 304) {
-										// revalidation of our current cached record
-										updatedRecord = existingRecord;
-										version = existingVersion;
-									} else {
-										// if the source has an error status, we need to throw an error
-										throw new ServerError(updatedRecord.body || 'Error from source', updatedRecord.status);
-									} // there are definitely more status codes to handle
+								const status = updatedRecord.status;
+								if (status === 304) {
+									// revalidation of our current cached record
+									updatedRecord = existingRecord;
+									version = existingVersion;
+								} else if (!CACHEABLE_STATUS_CODES.has(status)) {
+									// non-cacheable status - propagate to client without caching
+									throw new ServerError(updatedRecord.body || 'Error from source', status);
 								} else {
 									let headers: any;
 									const sourceHeaders = updatedRecord.headers;
@@ -4193,27 +4325,37 @@ export function makeTable(options) {
 									if (data !== undefined) {
 										// we have structured data that we have parsed
 										delete headers['content-type']; // don't store the content type if we have already parsed it
-										updatedRecord = {
-											headers,
-											data,
-										};
+										updatedRecord = { headers, data };
 									} else {
-										updatedRecord = {
-											headers,
-											body: createBlob(updatedRecord.body),
-										};
+										updatedRecord = { headers, body: createBlob(updatedRecord.body) };
 									}
+									if (status !== 200) updatedRecord.status = status;
 								}
 							}
 							if (typeof updatedRecord.toJSON === 'function') updatedRecord = updatedRecord.toJSON();
 							if (primaryKey && updatedRecord[primaryKey] !== id) updatedRecord[primaryKey] = id;
 						}
 						resolved = true;
-						resolve({
+						const resolvedEntry: Entry = {
 							key: id,
 							version,
 							value: updatedRecord,
-						});
+							expiresAt: sourceContext.expiresAt,
+							metadataFlags: 0,
+							size: 0,
+							localTime: 0,
+							nodeId: 0,
+							residencyId: 0,
+						} as any;
+						// Give the plain object the RecordObject prototype so getExpiresAt/getUpdatedTime
+						// are available on the immediately-resolved entry. We mutate the prototype
+						// in-place rather than copying so that the commit callback (which adds
+						// createdAt/updatedAt to updatedRecord) is still reflected in the entry value.
+						if (updatedRecord && updatedRecord.constructor === Object) {
+							Object.setPrototypeOf(updatedRecord, primaryStore.encoder.structPrototype);
+							entryMap.set(updatedRecord, resolvedEntry);
+						}
+						resolve(resolvedEntry);
 					} catch (error) {
 						error.message += ` while resolving record ${id} for ${tableName}`;
 						if (
@@ -4231,7 +4373,7 @@ export function makeTable(options) {
 								key: id,
 								version: existingVersion,
 								value: existingRecord,
-							});
+							} as any);
 							logger.trace?.(error.message, '(returned stale record)');
 						} else reject(error);
 						const resolveDuration = performance.now() - start;
@@ -4328,7 +4470,7 @@ export function makeTable(options) {
 									omitLocalRecord ? INVALIDATED : 0,
 									(audit && (hasChanges || omitLocalRecord)) || null,
 									{
-										user: sourceContext?.user,
+										user: (sourceContext as any)?.user,
 										expiresAt: sourceContext.expiresAt,
 										residencyId,
 										transaction,
@@ -4352,7 +4494,7 @@ export function makeTable(options) {
 										txnTime,
 										0,
 										(audit && hasChanges) || null,
-										{ user: sourceContext?.user, transaction, tableToTrack: tableName },
+										{ user: (sourceContext as any)?.user, transaction, tableToTrack: tableName },
 										'delete',
 										Boolean(invalidated)
 									);
@@ -4362,6 +4504,19 @@ export function makeTable(options) {
 							}
 						},
 					};
+					// The cache-from-source write bypasses `_writeUpdate`, so wire the embed hook here
+					// too (always the originating node). It runs after the client GET has resolved with
+					// fresh source data, so it's a background commit: an embedder failure aborts the cache
+					// write via the outer error handler (row re-embeds next read) and never reaches the
+					// caller. Source-resolution errors are handled earlier, with the stale-data fallback.
+					const embedBefore = buildEmbedBefore(
+						updatedRecord,
+						sourceContext,
+						undefined,
+						TableResource.embedAttributes,
+						TableResource.userEmbedders
+					);
+					if (embedBefore) await embedBefore();
 					sourceWrite.before = preCommitBlobsForRecordBefore(sourceWrite, updatedRecord);
 					dbTxn.addWrite(sourceWrite);
 				}),
@@ -4554,8 +4709,10 @@ export function makeTable(options) {
 			if (shardOrResidencyList >= 65536) throw new Error(`Shard id ${shardOrResidencyList} must be below 65536`);
 			const residencyList = server.shards?.get?.(shardOrResidencyList);
 			if (residencyList) {
-				logger.trace?.(`Shard ${shardOrResidencyList} mapped to ${residencyList.map((node) => node.name).join(', ')}`);
-				return residencyList.map((node) => node.name);
+				logger.trace?.(
+					`Shard ${shardOrResidencyList} mapped to ${residencyList.map((node) => (node as any).name).join(', ')}`
+				);
+				return residencyList.map((node) => (node as any).name);
 			}
 			throw new Error(`Shard ${shardOrResidencyList} is not defined`);
 		}
@@ -4579,9 +4736,9 @@ export function makeTable(options) {
 	function preCommitBlobsForRecordBefore(
 		write: any,
 		record: any,
-		before?: () => Promise<void>,
+		before?: () => Promise<void> | void,
 		saveInRecord?: boolean
-	): Promise<void> | void {
+	): any {
 		const preCommit = startPreCommitBlobsForRecord(record, primaryStore.rootStore, saveInRecord);
 		if (preCommit) {
 			// track the blobs on the write so abort/skip paths can clean up the files if the commit doesn't reference them
@@ -4590,14 +4747,15 @@ export function makeTable(options) {
 			// them to finish and we return a new callback for the before phase of the commit
 			const callSources = before;
 			return callSources
-				? async () => {
+				? async (): Promise<any> => {
 						// if we are calling the sources first and waiting for blobs, do those in order
-						await callSources();
+						const result = callSources();
+						if (result && (result as any).then) await result;
 						await preCommit.complete();
 					}
 				: () => preCommit.complete();
 		}
-		return before;
+		return before as any;
 	}
 }
 
@@ -4615,6 +4773,20 @@ function noop() {
 	// prefetch callback
 }
 
+/**
+ * Recreate a computed "from" function from a stored expression string. This is used when a table
+ * is loaded from metadata on a thread that hasn't loaded the GraphQL schema, so the computed
+ * function needs to be reconstructed from the persisted expression.
+ */
+function createComputedFrom(computedFromExpression: string, attributesFallback?: any) {
+	const script = new Script(
+		attributesFallback
+			? `function computed(attributes) { return function(record) { with(attributes) { with (record) { return ${computedFromExpression}; } } } } computed;`
+			: `function computed() { return function(record) { with (record) { return ${computedFromExpression}; } } } computed;`
+	);
+	return script.runInThisContext()(attributesFallback);
+}
+
 const ENDS_WITH_TIMEZONE = /[+-][0-9]{2}:[0-9]{2}|[a-zA-Z]$/;
 /**
  * Coerce a string to the type defined by the attribute