alchemymvc 1.4.4 → 1.4.6

package/lib/app/behaviour/publishable_behaviour.js

@@ -53,6 +53,9 @@ Publish.setMethod(function beforeFind(criteria) {
 			date_condition = new Date();
 		}
 
-		criteria.where('publish_date').lt(date_condition).or().exists(false);
+		// isEmpty (not exists false): a record saved WITH an explicit null
+		// publish_date has the field present, so `$exists: false` would
+		// hide it from every publish-filtered find
+		criteria.where('publish_date').lt(date_condition).or().isEmpty();
 	}
 });

package/lib/app/behaviour/revision_behaviour.js

@@ -225,6 +225,16 @@ Revision.setMethod(function beforeSave(record, options, creating) {
 	Model.get(this.model.model_name).findById(record.$pk, function gotRecord(err, result) {
 
 		if (err || !result) {
+
+			// Clear any PREVIOUS document's entry: the weakmap is keyed
+			// on the (possibly shared) options object, and a stale value
+			// would make afterSave diff against another record's data
+			revision_before.delete(options);
+
+			if (err) {
+				alchemy.registerError(err, {context: 'Revision behaviour could not load the original ' + that.model.model_name + ' record'});
+			}
+
 			return pledge.resolve();
 		}
 
@@ -269,7 +279,11 @@ Revision.setMethod(function afterSave(record, options, created) {
 	if (created) {
 		earlier_data = {};
 	} else {
+		// Consume the entry: the weakmap is keyed on the (possibly
+		// shared) options object, so it must not leak into the next
+		// document's save
 		earlier_data = revision_before.get(options);
+		revision_before.delete(options);
 	}
 
 	// Do we have earlier data to compare to?
@@ -285,6 +299,20 @@ Revision.setMethod(function afterSave(record, options, created) {
 	// Find the complete saved item
 	Model.get(this.model.model_name).findByPk(doc.$pk, async function gotRecord(err, result) {
 
+		if (err) {
+			return pledge.reject(err);
+		}
+
+		try {
+			await createRevision(result);
+			pledge.resolve();
+		} catch (err) {
+			pledge.reject(err);
+		}
+	});
+
+	async function createRevision(result) {
+
 		if (result) {
 
 			// Get the new data
@@ -320,13 +348,13 @@ Revision.setMethod(function afterSave(record, options, created) {
 					[that.revision_model.model_name] : revision_data
 				};
 
-				// Save the data (but do not wait for it)
-				that.revision_model.save(revision_data, {allowFields: true});
+				// Save the revision. This IS awaited: a `revert()` right after
+				// a save has to see this revision, and a fire-and-forget save
+				// would also swallow any insert error.
+				await that.revision_model.save(revision_data, {allowFields: true});
 			}
 		}
-
-		pledge.resolve();
-	});
+	}
 
 	return pledge;
 });

package/lib/app/behaviour/sluggable_behaviour.js

@@ -445,8 +445,12 @@ Sluggable.setMethod(function generateSlug(title, key, record, callback) {
 				return next(err);
 			}
 
-			// Don't use the target record for duplicate checks
+			// Don't use the target record for duplicate checks.
+			// `item` must still be cleared: leaving the PREVIOUS
+			// iteration's value would count the record's own slug as
+			// taken and skip past it
 			if (found_item && for_record_id && String(for_record_id) == String(found_item._id)) {
+				item = null;
 				return next();
 			}
 

package/lib/app/datasource/mongo_datasource.js

@@ -329,6 +329,15 @@ Mongo.setMethod(function collection(name) {
 
 	if (!this.collections[name]) {
 		this.collections[name] = result;
+
+		// A failed connect must not poison the cache: connect() has its
+		// own retry logic, but a cached rejected pledge would keep this
+		// table broken for the process lifetime
+		Swift.done(result, err => {
+			if (err && this.collections[name] === result) {
+				delete this.collections[name];
+			}
+		});
 	}
 
 	return result;
@@ -507,9 +516,12 @@ Mongo.setMethod(function _create(context) {
 			model.nukeCache();
 
 			if (err != null) {
-				// In MongoDB driver 6.x, write errors are thrown as MongoServerError
-				// Check if this is a write error that should be converted to validation violations
-				if (err.code || err.writeErrors) {
+				// In MongoDB driver 6.x, write errors are thrown as MongoServerError.
+				// Only actual WRITE errors (duplicate keys, document validation)
+				// become validation violations: matching on any `err.code` would
+				// also reclassify infrastructure errors (auth failure, stepdown,
+				// shutdown) as user-input problems
+				if (err.code == 11000 || err.code == 11001 || (err.writeErrors && err.writeErrors.length)) {
 					let violations = new Classes.Alchemy.Error.Validation.Violations();
 
 					// Handle bulk write errors (array of errors)

package/lib/app/helper_datasource/00-nosql_datasource.js

@@ -930,11 +930,9 @@ function convertCriteriaGroupToConditions(criteria, group, config, context) {
 			}
 		} else {
 			let item,
-			    not,
-			    obj = {};
+			    not;
 
-			let field_entry = {},
-			    name = entry.target_path,
+			let name = entry.target_path,
 			    queries_property = name.indexOf('.') > -1;
 
 			// Do we need to look into an object itself?
@@ -954,6 +952,16 @@ function convertCriteriaGroupToConditions(criteria, group, config, context) {
 			for (let i = 0; i < entry.items.length; i++) {
 				item = entry.items[i];
 
+				// Each item gets its OWN condition objects. These used to be
+				// shared across the loop: operators that REASSIGN `obj`
+				// (equals/in/contains/isNull) silently discarded every
+				// condition a previous item had accumulated, and pushing the
+				// same `field_entry` reference once per item duplicated the
+				// last condition instead of combining them. Separate entries
+				// combine correctly through the surrounding $and.
+				let obj = {},
+				    field_entry = {};
+
 				if (context && item.value && typeof item.value == 'object') {
 					item = {
 						...item,

package/lib/app/helper_datasource/05-fallback_datasource.js

@@ -28,8 +28,7 @@ Fallback.setProperty('has_offline_cache', true);
  */
 Fallback.decorateMethod(Blast.Decorators.memoize({ignore_arguments: true}), function connect() {
 
-	var that = this,
-	    tasks = [];
+	var that = this;
 
 	// The "upper" or "local" datasource
 	this.upper = Datasource.get(this.options.upper);
@@ -51,8 +50,6 @@ Fallback.decorateMethod(Blast.Decorators.memoize({ignore_arguments: true}), func
 			next();
 		});
 	}, null);
-
-	return Function.parallel(tasks);
 });
 
 /**
@@ -165,7 +162,7 @@ Fallback.setMethod(function storeInUpperDatasource(model, data, options) {
  *
  * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.1.0
- * @version  1.4.2
+ * @version  1.4.5
  *
  * @param    {Alchemy.OperationalContext.ReadDocumentFromDatasource}   context
  *
@@ -183,7 +180,28 @@ Fallback.setMethod(function read(context) {
 		let lower_context = context.createChild();
 		lower_context.setCriteria(lower_criteria);
 
-		tasks.push(() => this.lower.read(lower_context));
+		// A rejected lower (remote) read must not reject the whole query:
+		// resolve to null instead, so the waterfall falls through to the upper
+		// (local cache) read. Without this, being offline made every find fail
+		// even though the cache had the data.
+		tasks.push(() => {
+			let attempt = new Swift();
+
+			Swift.done(this.lower.read(lower_context), (err, result) => {
+
+				if (err) {
+					if (Blast.isBrowser && typeof alchemy != 'undefined' && alchemy.distinctProblem) {
+						alchemy.distinctProblem('fallback-lower-read', 'Remote read failed, using local cache', {repeat_after: 60000});
+					}
+
+					return attempt.resolve(null);
+				}
+
+				attempt.resolve(result);
+			});
+
+			return attempt;
+		});
 	}
 
 	let upper_criteria = criteria.clone();
@@ -202,7 +220,7 @@ Fallback.setMethod(function read(context) {
  *
  * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.1.0
- * @version  1.4.2
+ * @version  1.4.5
  *
  * @param    {Model}   model
  *
@@ -220,7 +238,13 @@ Fallback.setMethod(function getRecordsToSync(model) {
 	context.setModel(model);
 	context.setCriteria(criteria);
 
-	return this.upper.read(context);
+	// Datasource#read resolves with `{items, available}` since 1.4.2, but the
+	// consumers of this method (getRecordsToBeSavedRemotely) iterate the result
+	// directly - so unwrap to the items array, or offline saves never sync.
+	return Swift.waterfall(
+		this.upper.read(context),
+		result => (result && result.items) ? result.items : (result || [])
+	);
 });
 
 /**
@@ -335,9 +359,17 @@ Fallback.setMethod(function createOrUpdate(method, context) {
 			// Lower data can already be a Document instance!
 			// @TODO: add a check for that?
 			//lower.toApp(model, null, options, saved_data.lower.result, next);
+		} else if (saved_data.upper.result) {
+			// storeInUpperDatasource already returns app-format data (its
+			// last step runs upper.toApp), so converting it AGAIN would
+			// corrupt any field whose app and datasource formats differ.
+			// This is the normal path for offline saves.
+			next(null, saved_data.upper.result);
 		} else {
-			let toapp_context = context.withDatasourceEntry(saved_data.upper.result);
-			Swift.done(upper.toApp(toapp_context), next);
+			// Both saves failed: surface the actual save error instead of
+			// letting a toApp call on `undefined` throw a misleading
+			// "Unable to convert data: no data given"
+			next(saved_data.upper.err || saved_data.lower.err || new Error('Both datasource saves failed'));
 		}
 
 	}, function done(err, result) {

package/lib/app/helper_field/schema_field.js

@@ -339,9 +339,14 @@ SchemaField.setMethod(function getSubSchemaFromModel(context) {
 			return result;
 		}
 
-		let found_schema = this.resolveSchemaPath(model.schema, result, path, path);
-
-		return found_schema;
+		// The remote request returned the raw record instead of a schema:
+		// resolve the wanted property path within that record
+		let found_context = context.createChild();
+		found_context.setSchema(model.schema);
+		found_context.setHolder(result);
+		found_context.setSubSchemaPath(context.getValuePropertyName());
+
+		return this.resolveSchemaPath(found_context);
 	});
 
 	return pledge;
@@ -371,7 +376,11 @@ SchemaField.setMethod(function _toDatasource(context, value) {
 	}
 
 	// @TODO: What about the holder?
-	let tasks = value.map(entry => this._toDatasourceFromValue(context.withWorkingValue(entry), entry));
+	// Nullish entries are junk (older versions stored `[null]` for a null
+	// array value) - drop them instead of converting them
+	let tasks = value
+		.filter(entry => entry != null)
+		.map(entry => this._toDatasourceFromValue(context.withWorkingValue(entry), entry));
 
 	return Pledge.Swift.parallel(tasks);
 });
@@ -462,8 +471,14 @@ SchemaField.setMethod(function _toDatasourceFromValueWithSubSchema(context, valu
 
 				Object.assign(record, result[0]);
 
-				// Try getting the schema again
-				sub_schema = that.getSubSchema(record);
+				// Try getting the schema again, with the enriched
+				// record as the holder (getSubSchema expects an
+				// operational context, not a record)
+				let schema_context = new Classes.Alchemy.OperationalContext.Schema(context);
+				schema_context.setSchema(that.schema);
+				schema_context.setHolder(record);
+
+				sub_schema = that.getSubSchema(schema_context);
 
 				Pledge.Swift.done(sub_schema, (err, sub_schema) => {
 
@@ -507,7 +522,12 @@ SchemaField.setMethod(function _toApp(context, value) {
 
 	value = Array.cast(value);
 
-	let tasks = value.map(entry => this._toAppFromValue(context.withWorkingValue(entry), entry));
+	// Nullish entries are junk (older versions stored `[null]` for a null
+	// array value); converting one used to reject the ENTIRE find when
+	// the sub-schema has associations
+	let tasks = value
+		.filter(entry => entry != null)
+		.map(entry => this._toAppFromValue(context.withWorkingValue(entry), entry));
 
 	let result = Pledge.Swift.waterfall(
 		Pledge.Swift.parallel(tasks),
@@ -604,7 +624,7 @@ SchemaField.setMethod(function _toAppFromValueWithSubSchema(context, value) {
 		});
 
 	} else {
-		console.warn('Failed to find sub schema for', this.name, 'in', record);
+		console.warn('Failed to find sub schema for', this.name, 'in', context.getHolder());
 	}
 
 	return Swift.waterfall(

package/lib/app/helper_model/document.js

@@ -332,7 +332,11 @@ Document.setStatic(function getDocumentClass(model_param) {
 		DocClass.Model = Blast.Classes.Hawkejs.Model.getClass(model_name);
 	}
 
-	class_cache.set(document_name, DocClass);
+	// Cache under the same key the lookup uses (the full model_name):
+	// storing under the short class name made namespaced models never hit
+	// the cache AND let a later root model with the same base name (e.g.
+	// `Task` vs `System.Task`) receive the wrong document class
+	class_cache.set(model_name, DocClass);
 
 	return DocClass;
 });
@@ -769,7 +773,7 @@ Document.setMethod(function setDataRecord(record, options) {
 			} else if (field.is_private) {
 				delete_field = true;
 
-				if (options.keep_private_fields) {
+				if (options?.keep_private_fields) {
 					delete_field = false;
 				}
 			} else {
@@ -1170,6 +1174,38 @@ Document.setMethod(function save(data, options, callback) {
 
 		save_result = save_result[0];
 
+		// Fields edited while the save was in flight would be silently
+		// reverted by adopting the response wholesale (the response only
+		// reflects the record as it was sent), so detect and keep them.
+		// A field only counts as an in-flight edit when it differs from
+		// the snapshot AND from the save result: save hooks (beforeSave,
+		// beforeNormalize) mutate the live $main after the snapshot was
+		// taken, and their values DO match the response - treating those
+		// as edits would leave every saved document marked dirty.
+		let kept_fields;
+
+		if (in_flight_snapshot && that.$main) {
+			let saved_main = save_result.$main || {},
+			    key;
+
+			for (key in that.$main) {
+
+				if (key == pk_name) {
+					continue;
+				}
+
+				if (!that.alikeWhenStored(that.$main[key], in_flight_snapshot[key])
+					&& !that.alikeWhenStored(that.$main[key], saved_main[key])) {
+
+					if (!kept_fields) {
+						kept_fields = {};
+					}
+
+					kept_fields[key] = that.$main[key];
+				}
+			}
+		}
+
 		// Use the saved data from now on
 		that.$main = save_result.$main;
 
@@ -1177,10 +1213,21 @@ Document.setMethod(function save(data, options, callback) {
 		that.$attributes.original_record = undefined;
 		that.markUnchanged();
 
-		if (that.hasObjectFields()) {
+		if (kept_fields || that.hasObjectFields()) {
 			that.storeCurrentDataAsOriginalRecord();
 		}
 
+		if (kept_fields) {
+			let key;
+
+			// Put the newer, in-flight edits back on top of the saved state
+			// and mark them as changed, so a follow-up save persists them.
+			for (key in kept_fields) {
+				that.markChangedField(key, kept_fields[key]);
+				that.$main[key] = kept_fields[key];
+			}
+		}
+
 		pledge.resolve(that);
 	}
 
@@ -1218,6 +1265,16 @@ Document.setMethod(function save(data, options, callback) {
 		}
 	}
 
+	// Snapshot the record as it is being sent, so `updateDoc` can tell which
+	// fields were edited while the save was in flight
+	let in_flight_snapshot = null;
+
+	try {
+		in_flight_snapshot = JSON.clone(main);
+	} catch (err) {
+		// Without a snapshot the response is simply adopted as-is
+	}
+
 	sub_pledge = this.$model.save(this, options, updateDoc);
 
 	return pledge;
@@ -1265,13 +1322,21 @@ Document.setMethod(function checkAndInformDatasource(options, callback) {
 				if (DocClass.Model && DocClass.Model.hasServerAction('readDatasource')) {
 					// Only store in cache when we can query the server
 					pledge.resolve(that.informDatasource());
+				} else {
+					pledge.resolve();
 				}
 			});
 		} else if (DocClass.Model.hasServerAction('readDatasource')) {
 			Blast.requestIdleCallback(function tryStore(task_data) {
 				pledge.resolve(that.informDatasource());
 			});
+		} else {
+			pledge.resolve();
 		}
+	} else {
+		// Nothing to do: the pledge still has to settle or callers
+		// awaiting it (or passing a callback) hang forever
+		pledge.resolve();
 	}
 
 	return pledge;

package/lib/app/helper_model/model.js

@@ -1617,13 +1617,19 @@ Model.setMethod(function save(data, _options, _callback) {
 			return next();
 		}
 
-		// Let the user now if it's a new record
+		// Let the user know if it's a new record.
+		// This has to be a per-document copy: writing to the shared
+		// options object would make the FIRST document's newness decide
+		// `create` for every following document (and leak a sticky
+		// `create: true` into the caller's reused options object)
+		let doc_options = options;
+
 		if (options.create == null) {
-			options.create = document.is_new_record;
+			doc_options = Object.assign({}, options, {create: document.is_new_record});
 		}
 
 		// Save the data
-		that.saveRecord(document, options, function saved(err, result) {
+		that.saveRecord(document, doc_options, function saved(err, result) {
 
 			pledge.reportProgressPart(1);
 
@@ -1892,20 +1898,6 @@ Model.setMethod(function saveRecord(document, options, callback) {
 
 		creating = options.create || document.$pk == null;
 		next();
-
-		return;
-
-		// Look through unique indexes if no _id is present
-		that.auditRecord(document, options, function afterAudit(err, doc) {
-
-			if (err) {
-				return next(err);
-			}
-
-			// Is a new record being created?
-			creating = options.create || doc.$pk == null;
-			next();
-		});
 	}, function doBeforeNormalize(next) {
 		// @TODO: make "beforeSave" only use promises
 		that.issueDataEvent('beforeNormalize', [document, options], next);
@@ -1934,28 +1926,45 @@ Model.setMethod(function saveRecord(document, options, callback) {
 		}
 	}, function doAssociated(next) {
 
-		var tasks = [],
-		    assoc,
-		    entry,
-		    key;
+		var tasks = [];
 
 		Object.each(document.$record, function eachEntry(entry, key) {
 
+			// Skip empty entries
+			if (!entry) {
+				return;
+			}
+
 			// Skip our own record
 			if (key == that.name) {
 				return;
 			}
 
-			// Get the association configuration
-			assoc = that.schema.associations[key];
+			// Get the association configuration.
+			// This has to be a per-entry constant: the doSave closures run
+			// later, so a shared variable would make every entry save
+			// through the LAST association's model (creating empty records
+			// in the wrong collection)
+			const assoc = that.schema.associations[key];
 
 			// If the association doesn't exist, do nothing
 			if (!assoc) {
 				return;
 			}
 
-			// Add the saved _id
-			entry[assoc.options.foreignKey] = saved_record[assoc.options.localKey];
+			// Populated documents that were not modified must not be
+			// re-saved as a side effect of saving their parent
+			if (typeof entry.hasChanged == 'function' && !entry.hasChanged()) {
+				return;
+			}
+
+			// Add the saved _id (an `_id: undefined` entry would make
+			// behaviours that look up the existing record choke)
+			let foreign_key_value = saved_record[assoc.options.localKey];
+
+			if (foreign_key_value != null) {
+				entry[assoc.options.foreignKey] = foreign_key_value;
+			}
 
 			// Add the task
 			tasks.push(function doSave(next) {

package/lib/class/datasource.js

@@ -276,6 +276,16 @@ Datasource.setMethod(function toDatasource(context) {
 			continue;
 		}
 
+		// Meta fields (like AssociationAlias) only exist at runtime:
+		// persisting them would store entire populated Document wrappers
+		// ($options, $record, model instance and all) in the datasource,
+		// and a self-referencing object graph in there makes the BSON
+		// serializer throw "Cannot convert circular structure to BSON".
+		// The toApp path already skips them - mirror that here.
+		if (field_context.getField()?.is_meta_field) {
+			continue;
+		}
+
 		tasks[field_name] = this.valueToDatasource(field_context);
 	}
 
@@ -331,7 +341,10 @@ Datasource.setMethod(function toApp(context) {
 					continue;
 				}
 
-				let model = this.getModel(info.modelName, false);
+				// Use the non-throwing lookup: `this.getModel()` throws
+				// for unknown models, which would reject the whole read
+				// instead of skipping the unknown alias
+				let model = Model.get(info.modelName, false);
 
 				if (!model) {
 					continue;
@@ -356,9 +369,14 @@ Datasource.setMethod(function toApp(context) {
 
 				// Helper to get cached or process entity
 				let processEntity = (entry) => {
-					// Only cache if entry has an _id
+					// Only cache if entry has an _id.
+					// The key includes the entry's field names: the same
+					// (model, id) can appear with different projections in
+					// one read (per-alias $project in the lookup pipeline),
+					// and serving a truncated cached version to a fully
+					// selected alias would silently drop fields
 					if (entry && entry._id) {
-						let cache_key = data_schema.name + ':' + entry._id;
+						let cache_key = data_schema.name + ':' + entry._id + ':' + Object.keys(entry).sort().join(',');
 						let cached = entity_cache.get(cache_key);
 
 						if (cached) {
@@ -394,7 +412,7 @@ Datasource.setMethod(function toApp(context) {
 		    field = entry.value,
 		    value = data[field_name];
 
-		if (field.is_meta_field || field == null) {
+		if (field == null || field.is_meta_field) {
 			continue;
 		}
 
@@ -550,11 +568,17 @@ Datasource.setMethod(function read(context) {
 	});
 
 	// If a cache_pledge was created, make sure it gets rejected on error
-	// so that subsequent queries with the same hash don't hang forever
+	// so that subsequent queries with the same hash don't hang forever.
+	// Also evict it: a cached rejection would replay the error for the
+	// full cache TTL, long after the datasource recovered
 	if (cache_pledge) {
 		Pledge.Swift.done(read_pledge, (err) => {
 			if (err) {
 				cache_pledge.reject(err);
+
+				if (model.cache && model.cache.get(hash) === cache_pledge) {
+					model.cache.remove(hash);
+				}
 			}
 		});
 	}

package/lib/class/field.js

@@ -461,7 +461,6 @@ Field.setStatic(function unDry(value) {
 Field.setMethod(function toDry() {
 	return {
 		value: {
-			bla: 1,
 			schema  : this.schema,
 			name    : this.name,
 			options : this.getOptionsForDrying(),
@@ -688,7 +687,7 @@ Field.setMethod(function getRecordValue(record, path_to_value_hint) {
  */
 Field.setMethod(function castContainedValues(value, to_datasource) {
 
-	if (this.is_translatable && value && this.is_translatable) {
+	if (this.is_translatable && value) {
 		let prefix;
 
 		for (prefix in value) {
@@ -907,7 +906,12 @@ Field.setMethod(function regularToDatasource(context, value) {
 		return value;
 	}
 
-	let tasks = value.map(entry => this._toDatasource(context.withWorkingValue(entry), entry));
+	// The `_toDatasource` contract says entries are never nullish:
+	// drop junk entries (like the `[null]` older versions stored for a
+	// null array value) instead of feeding them to the field logic
+	let tasks = value
+		.filter(entry => entry != null)
+		.map(entry => this._toDatasource(context.withWorkingValue(entry), entry));
 
 	return Pledge.Swift.parallel(tasks);
 });
@@ -926,6 +930,14 @@ Field.setMethod(function regularToDatasource(context, value) {
  */
 Field.setMethod(function translatableToDatasource(context, value) {
 
+	// A primitive value would be iterated key-by-key (storing
+	// {"0":"f","1":"o",...} for 'foo') - wrap it in the default prefix,
+	// mirroring what fromTranslatableToApp does on the way out
+	if (value != null && typeof value != 'object') {
+		let prefix = Blast.Globals.Prefix?.default?.locale || '__';
+		value = {[prefix]: value};
+	}
+
 	let tasks = {};
 
 	for (let key in value) {
@@ -987,7 +999,13 @@ Field.setMethod(function fromRegularToApp(context, value) {
 		context.setWorkingValue(value);
 	}
 
-	let tasks = value.map(entry => this._toApp(context.withWorkingValue(entry), entry));
+	// The `_toApp` contract says entries are never nullish: skip junk
+	// entries (like a stored `[null]`) instead of feeding them to the
+	// field logic - for sub-schemas with associations a null entry even
+	// rejected the ENTIRE find
+	let tasks = value
+		.filter(entry => entry != null)
+		.map(entry => this._toApp(context.withWorkingValue(entry), entry));
 
 	return Pledge.Swift.parallel(tasks);
 });
@@ -1091,6 +1109,13 @@ Field.setMethod(function getValue(value) {
 
 	var wrapped;
 
+	// A nullish value on an arrayable field must become an empty array:
+	// wrapping it like a regular value would store `[null]`, a junk entry
+	// that every consumer of the array then has to guard against
+	if (value == null && this.is_array && !this.is_translatable) {
+		return [];
+	}
+
 	// Make sure the value is an array
 	if (Array.isArray(value)) {
 		// If this field is not an arrayable field, wrap it again

package/lib/class/migration.js

@@ -99,13 +99,37 @@ Migration.setStatic(async function start() {
 				}
 			});
 
-			record.ended = new Date();
-			await record.save();
-
 		} catch (err) {
 			console.log(' »» Migration error:', err);
-			record.error = err.message + '\n' + err.stack;
+
+			if (err instanceof Error) {
+				record.error = err.message + '\n' + err.stack;
+			} else {
+				record.error = String(err);
+			}
+
+			try {
+				await record.save();
+			} catch (save_err) {
+				// Without an `error` field the record reads as "has not
+				// yet finished", which blocks all migrations with no
+				// recovery hint - at least say what happened
+				console.log(' »» Could not persist the migration failure:', save_err);
+			}
+
+			console.log('Migrations stopped');
+			return;
+		}
+
+		// The success stamp lives OUTSIDE the try: a transient failure
+		// while saving `ended` must not mark a COMPLETED migration as
+		// failed (which would block all future migrations)
+		record.ended = new Date();
+
+		try {
 			await record.save();
+		} catch (save_err) {
+			console.log(' »» Migration "' + name + '" finished, but its record could not be updated:', save_err);
 			console.log('Migrations stopped');
 			return;
 		}
@@ -133,10 +157,28 @@ Migration.setMethod(function processRecords(model_name, fnc) {
 		return_raw_data: true,
 	};
 
-	return model.eachRecord(options, async (record, index, next) => {
-		await fnc(model, record[model_name], index);
+	let pledge = new Pledge();
+
+	model.eachRecord(options, async (record, index, next) => {
+
+		// A throwing handler must reach `next(err)`: without it the
+		// iteration waits forever and the migration hangs with its
+		// record stuck in the "has not yet finished" state
+		try {
+			await fnc(model, record[model_name], index);
+		} catch (err) {
+			return next(err);
+		}
+
 		next();
 	}, (err) => {
-		// Done!
+
+		if (err) {
+			pledge.reject(err);
+		} else {
+			pledge.resolve();
+		}
 	});
+
+	return pledge;
 });

package/lib/class/model.js

@@ -976,8 +976,7 @@ Model.setMethod(function saveRecord(document, options, callback) {
 		}
 	}, function doAssociated(next) {
 
-		let tasks = [],
-		    assoc;
+		let tasks = [];
 
 		Object.each(document.$record, function eachEntry(entry, key) {
 
@@ -991,16 +990,31 @@ Model.setMethod(function saveRecord(document, options, callback) {
 				return;
 			}
 
-			// Get the association configuration
-			assoc = that.schema.associations[key];
+			// Get the association configuration.
+			// This has to be a per-entry constant: the doSave closures run
+			// later, so a shared variable would make every entry save
+			// through the LAST association's model (creating empty records
+			// in the wrong collection)
+			const assoc = that.schema.associations[key];
 
 			// If the association doesn't exist, do nothing
 			if (!assoc) {
 				return;
 			}
 
-			// Add the saved _id
-			entry[assoc.options.foreignKey] = saved_record[assoc.options.localKey];
+			// Populated documents that were not modified must not be
+			// re-saved as a side effect of saving their parent
+			if (typeof entry.hasChanged == 'function' && !entry.hasChanged()) {
+				return;
+			}
+
+			// Add the saved _id (an `_id: undefined` entry would make
+			// behaviours that look up the existing record choke)
+			let foreign_key_value = saved_record[assoc.options.localKey];
+
+			if (foreign_key_value != null) {
+				entry[assoc.options.foreignKey] = foreign_key_value;
+			}
 
 			// Add the task
 			tasks.push(function doSave(next) {
@@ -1063,33 +1077,37 @@ Model.setMethod(function auditRecord(document, options, callback) {
 			}
 
 			tasks[indexName] = function auditIndex(next) {
-				var query = {},
-				    fieldName;
 
-				for (fieldName in index.fields) {
+				// This used to call `datasource.read()` with its pre-1.4.0
+				// signature, which threw since the OperationalContext
+				// refactor - go through a regular criteria find instead
+				let criteria = that.find();
+
+				for (let fieldName in index.fields) {
 					if (document[fieldName] != null) {
-						query[fieldName] = document[fieldName];
+						let value = document[fieldName];
 
 						// @todo: should run through the FieldType instance
-						if (String(query[fieldName]).isObjectId()) {
-							query[fieldName] = alchemy.castObjectId(query[fieldName]);
+						if (String(value).isObjectId()) {
+							value = alchemy.castObjectId(value);
 						}
+
+						criteria.where(fieldName).equals(value);
 					}
 				}
 
-				that.datasource.read(that, query, {}, function gotRecordInfo(err, records) {
+				that.find('first', criteria, function gotRecordInfo(err, record) {
 
 					if (err != null) {
 						return next(err);
 					}
 
-					if (records[0] != null) {
-						results[indexName] = records[0];
+					if (record != null) {
+						results[indexName] = record;
 					}
 
 					next();
 				});
-
 			};
 		});
 
@@ -1402,7 +1420,7 @@ Model.setMethod(function remove(id, callback) {
  *
  * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.5.0
- * @version  1.2.0
+ * @version  1.4.5
  *
  * @param    {Object}    options    Find options
  * @param    {Function}  task       Task to perform on each record
@@ -1425,7 +1443,12 @@ Model.setMethod(function eachRecord(options, task, callback) {
 		options = {};
 	}
 
-	if (!callback) {
+	if (callback) {
+		// Errors are also delivered through the callback, and callers that
+		// pass one routinely discard the returned pledge - its rejection
+		// must not be reported as an uncaught error on top of the callback
+		pledge.warn_uncaught_errors = false;
+	} else {
 		callback = Function.thrower;
 	}
 
@@ -1450,6 +1473,11 @@ Model.setMethod(function eachRecord(options, task, callback) {
 
 		var tasks = [];
 
+		if (err) {
+			pledge.reject(err);
+			return callback(err);
+		}
+
 		if (!result.length) {
 			pledge.reportProgress(100);
 			pledge.resolve();

package/lib/class/task.js

@@ -339,6 +339,12 @@ Task.setMethod(async function start(payload) {
 	this[RUNNING_PLEDGE] = new Pledge();
 	this[INITIALIZED_PLEDGE] = new Pledge();
 
+	// These pledges may have no consumer (start()'s own promise is what
+	// most callers await), so a rejection must not log a spurious
+	// "Uncaught Pledge error"
+	this[RUNNING_PLEDGE].warn_uncaught_errors = false;
+	this[INITIALIZED_PLEDGE].warn_uncaught_errors = false;
+
 	let document = this[HISTORY_DOC];
 
 	if (!document) {
@@ -357,7 +363,25 @@ Task.setMethod(async function start(payload) {
 	// Register this command as running
 	running.push(this);
 
-	await document.save();
+	try {
+		await document.save();
+	} catch (err) {
+		// Without settling these pledges, a failed init (e.g. a transient
+		// DB error on the history save) would wedge every
+		// `waitUntilInitialized()` caller - the schedule runner would
+		// consider the task running forever and never fire it again
+		this[STATUS] = STOPPED;
+		this[INITIALIZED_PLEDGE].reject(err);
+		this[RUNNING_PLEDGE].reject(err);
+
+		let index = running.indexOf(this);
+
+		if (index > -1) {
+			running.splice(index, 1);
+		}
+
+		throw err;
+	}
 
 	// Set the id
 	this.id = String(document.$pk);
@@ -402,6 +426,19 @@ Task.setMethod(async function start(payload) {
 			this.report('done');
 		}
 	} finally {
+		// Terminal bookkeeping for EVERY exit path (done, stopped, failed):
+		// mark the task as stopped (nothing did before, so `has_stopped`
+		// stayed false forever), deregister it from the shared `running`
+		// array (which used to grow unboundedly), and settle the running
+		// pledge (which used to stay pending on stop/error).
+		this[STATUS] = STOPPED;
+
+		let index = running.indexOf(this);
+
+		if (index > -1) {
+			running.splice(index, 1);
+		}
+
 		// Always close out the history document so it doesn't get
 		// stuck as a zombie "running forever" row.
 		document.ended_at = new Date();
@@ -414,9 +451,13 @@ Task.setMethod(async function start(payload) {
 			// executor error on its way out of the catch above.
 			alchemy.registerError(save_err);
 		}
-	}
 
-	this[RUNNING_PLEDGE].resolve(result);
+		if (this.error) {
+			this[RUNNING_PLEDGE].reject(this.error);
+		} else {
+			this[RUNNING_PLEDGE].resolve(result);
+		}
+	}
 
 	return result;
 });
@@ -737,11 +778,29 @@ Task.execute = function execute(name, options, callback) {
 	}
 
 	if (!constructor) {
-		return callback(new Error('Could not find "' + name + '" task'));
+		let err = new Error('Could not find "' + name + '" task');
+
+		if (callback) {
+			callback(err);
+			return;
+		}
+
+		throw err;
 	}
 
 	task = new constructor();
-	task.start(options, callback);
+
+	// `start()` only takes a payload - the callback has to be attached
+	// to its returned promise (it used to be passed as a second argument,
+	// where it was silently ignored)
+	let promise = task.start(options);
+
+	if (callback) {
+		Pledge.done(promise, callback);
+	} else {
+		// Prevent an unhandled rejection when nobody is listening
+		promise.catch(err => alchemy.registerError(err, {context: 'Task.execute(' + name + ')'}));
+	}
 
 	return task;
 };

package/lib/core/client_base.js

@@ -291,6 +291,13 @@ ClientBase.setMethod(function issueEvent(name, args, next) {
 		args = [];
 	}
 
+	if (next) {
+		// Errors are also delivered through `next`, and callers that pass a
+		// callback routinely discard the returned pledge - its rejection
+		// must not be reported as an uncaught error on top of the callback.
+		pledge.warn_uncaught_errors = false;
+	}
+
 	if (this.constructor.event_to_method_map) {
 		method_name = this.constructor.event_to_method_map.get(name);
 	}

package/lib/core/stage.js

@@ -195,6 +195,13 @@ Stage.setMethod(function _addTask(type, fnc) {
 		}
 
 		task_map.set(fnc, task_result);
+
+		// Settle the replacement pledge once the previous state AND this
+		// task are done: it used to stay pending forever, which made
+		// `_launch` hang on `await task_map[STATUS_PLEDGE]` whenever a
+		// task was added to an already-started type (and a rejecting
+		// task_result was an unhandled rejection)
+		new_pledge.resolve(Pledge.Swift.waterfall(pledge, () => task_result));
 	} else {
 		task_map.set(fnc, null);
 	}
@@ -563,16 +570,24 @@ Stage.setMethod(async function _launch(child_stages) {
 		this[STATUS] = PRE_STATUS;
 	}
 
-	await this._doTasks('pre_tasks');
+	try {
+		await this._doTasks('pre_tasks');
 
-	if (this[STATUS] == PRE_STATUS) {
-		this[STATUS] = MAIN_STATUS;
-	}
+		if (this[STATUS] == PRE_STATUS) {
+			this[STATUS] = MAIN_STATUS;
+		}
 
-	await this._doTasks('main_tasks');
+		await this._doTasks('main_tasks');
 
-	await this.pre_tasks[STATUS_PLEDGE];
-	await this.main_tasks[STATUS_PLEDGE];
+		await this.pre_tasks[STATUS_PLEDGE];
+		await this.main_tasks[STATUS_PLEDGE];
+	} catch (err) {
+		// Reject the stage pledge too: without this, only _launch's own
+		// caller sees the failure and everything waiting on the stage
+		// (afterStages, dependent stages) hangs forever
+		this.pledge.reject(err);
+		throw err;
+	}
 
 	if (this[STATUS] != POST_STATUS) {
 		this[STATUS] = CHILD_STATUS;
@@ -594,7 +609,16 @@ Stage.setMethod(async function refreshStatus() {
 		return;
 	}
 
-	await this._doTasks('post_tasks');
+	try {
+		await this._doTasks('post_tasks');
+	} catch (err) {
+		// Surface the failure to everything waiting on this stage:
+		// leaving the pledge pending made every `afterStages()` waiter
+		// hang silently, and when called fire-and-forget (from a child's
+		// completion below) the rejection was entirely unhandled
+		this.pledge.reject(err);
+		throw err;
+	}
 
 	if (!this.ended) {
 		this.ended = Date.now();
@@ -605,7 +629,9 @@ Stage.setMethod(async function refreshStatus() {
 	this.pledge.resolve();
 
 	if (this.parent) {
-		this.parent.refreshStatus();
+		this.parent.refreshStatus().catch(err => {
+			alchemy.registerError(err, {context: 'Post-tasks of stage "' + this.parent.id + '" failed'});
+		});
 	}
 });
 

package/lib/stages/50-routes.js

@@ -118,7 +118,17 @@ const hawkejs = routes.createStage('hawkejs', () => {
 				return req.conduit.notFound('Could not find any of the given templates');
 			}
 
-			req.conduit.setHeader('cache-control', 'public, max-age=3600, must-revalidate');
+			// Only allow long-lived caching when the request is versioned
+			// with the CURRENT app version: unversioned (or stale-versioned)
+			// urls would keep serving an old template for up to an hour
+			// after a deploy.
+			let requested_version = req.conduit.param('v');
+
+			if (requested_version && String(requested_version) === String(alchemy.hawkejs.app_version)) {
+				req.conduit.setHeader('cache-control', 'public, max-age=3600, must-revalidate');
+			} else {
+				req.conduit.setHeader('cache-control', 'no-cache');
+			}
 
 			// Don't use json dry, hawkejs expects regular json
 			req.conduit.json_dry = false;

package/lib/testing/browser.js

@@ -24,6 +24,78 @@
  */
 'use strict';
 
+const fs = require('fs'),
+      child_process = require('child_process');
+
+/**
+ * Check if a browser executable actually works in headless mode.
+ * Puppeteer's own bundled-Chrome download can be missing/corrupt in some
+ * sandboxes (e.g. a pinned old revision missing its ICU data file). Such a
+ * binary still exits 0 for `--version`, but hangs and never emits a CDP
+ * handshake when actually launched headless - which is what makes
+ * `puppeteer.launch()` hang until its connect-timeout instead of failing
+ * fast. So a real headless run is checked synchronously up front instead.
+ *
+ * @author   Jelle De Loecker <jelle@elevenways.be>
+ * @since    1.4.5
+ * @version  1.4.5
+ *
+ * @param    {string}   executable_path
+ *
+ * @return   {boolean}
+ */
+function isUsableBrowser(executable_path) {
+
+	if (!executable_path || !fs.existsSync(executable_path)) {
+		return false;
+	}
+
+	let result = child_process.spawnSync(executable_path, [
+		'--headless',
+		'--disable-gpu',
+		'--no-sandbox',
+		'--dump-dom',
+		'about:blank',
+	], {timeout: 8000});
+
+	return result.status === 0 && !result.error;
+}
+
+/**
+ * Resolve which Chrome/Chromium executable to launch.
+ * Prefers `PUPPETEER_EXECUTABLE_PATH` (puppeteer already honors it, but we
+ * validate it here too) and puppeteer's own bundled download; falls back to
+ * common system-installed locations when neither actually works.
+ *
+ * @author   Jelle De Loecker <jelle@elevenways.be>
+ * @since    1.4.5
+ * @version  1.4.5
+ *
+ * @param    {Object}   puppeteer
+ *
+ * @return   {string|undefined}
+ */
+function resolveExecutablePath(puppeteer) {
+
+	let candidates = [
+		process.env.PUPPETEER_EXECUTABLE_PATH,
+		puppeteer.executablePath(),
+		'/usr/bin/chromium',
+		'/usr/bin/chromium-browser',
+		'/usr/bin/google-chrome',
+	];
+
+	for (let candidate of candidates) {
+		if (isUsableBrowser(candidate)) {
+			return candidate;
+		}
+	}
+
+	// Nothing usable found: let puppeteer try its own default and produce
+	// its normal error/timeout, rather than silently launching with none
+	return undefined;
+}
+
 /**
  * The BrowserHelper class
  *
@@ -133,7 +205,8 @@ BrowserHelper.setMethod(async function load() {
 	} else {
 		// Launch new browser
 		this.browser = await puppeteer.launch({
-			headless: this.options.headless,
+			headless       : this.options.headless,
+			executablePath : resolveExecutablePath(puppeteer),
 		});
 	}
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "alchemymvc",
 	"description": "MVC framework for Node.js",
-	"version": "1.4.4",
+	"version": "1.4.6",
 	"author": "Jelle De Loecker <jelle@elevenways.be>",
 	"keywords": [
 		"alchemy",
@@ -22,7 +22,7 @@
 		"chokidar"         : "~4.0.3",
 		"formidable"       : "~3.5.4",
 		"graceful-fs"      : "~4.2.11",
-		"hawkejs"          : "~2.4.2",
+		"hawkejs"          : "~2.4.3",
 		"jsondiffpatch"    : "~0.5.0",
 		"mime-types"       : "~3.0.2",
 		"minimist"         : "~1.2.8",
@@ -32,7 +32,7 @@
 		"ncp"              : "~2.0.0",
 		"postcss"          : "~8.5.6",
 		"postcss-prune-var": "~1.1.2",
-		"protoblast"       : "~0.9.8",
+		"protoblast"       : "~0.9.9",
 		"semver"           : "~7.7.2",
 		"socket.io"        : "~4.7.5",
 		"@11ways/socket.io-stream" : "~0.9.2",
@@ -66,7 +66,7 @@
 		"mocha"                   : "^11.7.5",
 		"mongo-unit"              : "^3.4.0",
 		"nyc"                     : "^15.1.0",
-		"puppeteer"               : "~21.3.6",
+		"puppeteer"               : "^24.43.1",
 		"source-map"              : "~0.7.3"
 	},
 	"scripts": {