@speclynx/apidom-overlay 5.0.2 → 5.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-overlay",
-  "version": "5.0.2",
+  "version": "5.1.1",
   "description": "Apply Overlay 1.x.y documents to API definitions.",
   "keywords": [
     "apidom",
@@ -53,12 +53,12 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^8.0.0",
-    "@speclynx/apidom-core": "5.0.2",
-    "@speclynx/apidom-datamodel": "5.0.2",
-    "@speclynx/apidom-error": "5.0.2",
-    "@speclynx/apidom-json-path": "5.0.2",
-    "@speclynx/apidom-ns-overlay-1": "5.0.2",
-    "@speclynx/apidom-reference": "5.0.2",
+    "@speclynx/apidom-core": "5.1.1",
+    "@speclynx/apidom-datamodel": "5.1.1",
+    "@speclynx/apidom-error": "5.1.1",
+    "@speclynx/apidom-json-path": "5.1.1",
+    "@speclynx/apidom-ns-overlay-1": "5.1.1",
+    "@speclynx/apidom-reference": "5.1.1",
     "type-fest": "^5.8.0"
   },
   "files": [
@@ -71,5 +71,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "01792b567baea3a47cb08d09e478178aa04afda9"
+  "gitHead": "b661f6f038953d118ad09eec0d7da7927db46f5c"
 }

package/src/apply/realms/apidom.cjs

@@ -25,6 +25,18 @@ const defaultApplyOptions = {
   strict: false
 };
 
+/**
+ * Merges caller options over the defaults. A partial options object leaves the
+ * fields it omits undefined, which must still mean the documented defaults.
+ * `immutable` is spelled out because it is the only default that is not falsy,
+ * so a caller forwarding an undefined value must not end up mutating in place.
+ */
+const withDefaults = options => ({
+  ...defaultApplyOptions,
+  ...options,
+  immutable: options.immutable ?? defaultApplyOptions.immutable
+});
+
 /**
  * Default customMerge that enforces Overlay spec type compatibility.
  * Throws OverlayError on incompatible type combinations.
@@ -85,12 +97,37 @@ const resolveParent = (normalizedPath, root) => {
  * @public
  */
 const applyUpdateAction = (normalizedPaths, updateValue, targetElement, options = defaultApplyOptions) => {
-  let result = options.immutable ? (0, _apidomDatamodel.cloneDeep)(targetElement) : targetElement;
+  const opts = withDefaults(options);
+  let result = opts.immutable ? (0, _apidomDatamodel.cloneDeep)(targetElement) : targetElement;
   for (const normalizedPath of normalizedPaths) {
+    /**
+     * Every matched node gets its own copy of the update value. deepmerge
+     * shallow clones members, so the merged result shares key elements and
+     * non-mergeable values with its source regardless of the clone option —
+     * without this each target would alias every other target, and a copy
+     * action would alias the copy source in the target document.
+     */
+    const clonedUpdateValue = (0, _apidomDatamodel.cloneDeep)(updateValue);
     const resolved = resolveParent(normalizedPath, result);
     if (resolved === null) {
-      // targeting root
-      result = mergeValue(result, updateValue, options);
+      /**
+       * Targeting root. There is no parent slot to write the merged element
+       * into, so the merge is transplanted back onto the target itself — every
+       * other target shape updates the document in place and the root must not
+       * be the silent exception. Merging always yields the target's own
+       * constructor, so the transplant is type-safe. Two cases cannot be
+       * written in place and fall back to rebinding: a primitive root replaced
+       * by a differently typed value, and a frozen root, whose properties
+       * cannot be assigned.
+       */
+      const merged = mergeValue(result, clonedUpdateValue, opts);
+      if (merged.constructor === result.constructor && !result.isFrozen) {
+        result.content = merged.content;
+        result.meta = merged.meta;
+        result.attributes = merged.attributes;
+      } else {
+        result = merged;
+      }
       continue;
     }
     const {
@@ -100,12 +137,12 @@ const applyUpdateAction = (normalizedPaths, updateValue, targetElement, options
     if ((0, _apidomDatamodel.isObjectElement)(parent)) {
       const current = parent.get(key);
       if (current !== undefined) {
-        parent.set(key, mergeValue(current, updateValue, options));
+        parent.set(key, mergeValue(current, clonedUpdateValue, opts));
       }
     } else if ((0, _apidomDatamodel.isArrayElement)(parent)) {
       const current = parent.get(key);
       if (current !== undefined) {
-        parent.content[key] = mergeValue(current, updateValue, options);
+        parent.content[key] = mergeValue(current, clonedUpdateValue, opts);
       }
     }
   }
@@ -125,7 +162,13 @@ const applyCopyAction = (normalizedPaths, copyExpression, targetElement, options
   if (sourceMatches.length > 1) {
     throw new _OverlayError.default(`Copy source JSONPath "${copyExpression}" must select a single node, but selected ${sourceMatches.length}`);
   }
-  const sourceValue = sourceMatches[0];
+
+  /**
+   * Snapshot the copy source. Matched targets are updated in document order and
+   * the source may sit under one of them, so a live reference would let later
+   * targets copy a source that an earlier target already modified.
+   */
+  const sourceValue = (0, _apidomDatamodel.cloneDeep)(sourceMatches[0]);
   return applyUpdateAction(normalizedPaths, sourceValue, targetElement, options);
 };
 
@@ -135,7 +178,8 @@ const applyCopyAction = (normalizedPaths, copyExpression, targetElement, options
  */
 exports.applyCopyAction = applyCopyAction;
 const applyRemoveAction = (normalizedPaths, targetElement, options = defaultApplyOptions) => {
-  const result = options.immutable ? (0, _apidomDatamodel.cloneDeep)(targetElement) : targetElement;
+  const opts = withDefaults(options);
+  const result = opts.immutable ? (0, _apidomDatamodel.cloneDeep)(targetElement) : targetElement;
   // reverse document order so higher array indices are removed first (avoids index shifting)
   const sorted = [...normalizedPaths].reverse();
   for (const normalizedPath of sorted) {
@@ -158,14 +202,20 @@ const applyRemoveAction = (normalizedPaths, targetElement, options = defaultAppl
 
 /**
  * Applies a single overlay action to a target element.
- * Immutable — returns a new element with the action applied.
+ *
+ * Immutable by default. The target is cloned once up front and the action is
+ * applied to the clone, so the returned element is always independent of the
+ * input, including when the action changes nothing. Pass `immutable: false` to
+ * apply the action in place; the one shape that cannot be applied in place is
+ * a `target: $` action replacing a primitive root with a differently typed
+ * value, so the return value is authoritative in both modes.
  *
  * @public
  */
 exports.applyRemoveAction = applyRemoveAction;
 const applyAction = (actionElement, targetElement, options = defaultApplyOptions) => {
-  const internalOpts = options;
-  const tracer = internalOpts.tracer ?? (options.trace ? new _TraceBuilder.default(options.trace) : undefined);
+  const opts = withDefaults(options);
+  const tracer = opts.tracer ?? (opts.trace ? new _TraceBuilder.default(opts.trace) : undefined);
   const actionValidation = (0, _validate.validateAction)(actionElement);
   if (!actionValidation.valid) throw actionValidation.error;
   const targetExpression = (0, _apidomCore.toValue)(actionElement.target);
@@ -178,7 +228,7 @@ const applyAction = (actionElement, targetElement, options = defaultApplyOptions
     }
   });
   if (matches.length === 0) {
-    if (options.strict) {
+    if (opts.strict) {
       const error = new _OverlayError.default(`Action target "${targetExpression}" matched zero nodes (strict mode)`, {
         action: actionElement
       });
@@ -198,13 +248,20 @@ const applyAction = (actionElement, targetElement, options = defaultApplyOptions
       matchCount: 0,
       normalizedPaths: []
     });
-    return targetElement;
+    return opts.immutable ? (0, _apidomDatamodel.cloneDeep)(targetElement) : targetElement;
   }
+
+  // clone once, then apply the action mutably to the clone
+  const workingElement = opts.immutable ? (0, _apidomDatamodel.cloneDeep)(targetElement) : targetElement;
+  const mutatingOptions = {
+    ...opts,
+    immutable: false
+  };
   try {
     // remove action
     const removeValue = actionElement.removeField;
     if (removeValue !== undefined && (0, _apidomCore.toValue)(removeValue) === true) {
-      const result = applyRemoveAction(normalizedPaths, targetElement, options);
+      const result = applyRemoveAction(normalizedPaths, workingElement, mutatingOptions);
       tracer?.action({
         target: targetExpression,
         type: 'remove',
@@ -218,7 +275,7 @@ const applyAction = (actionElement, targetElement, options = defaultApplyOptions
     if (actionElement.update !== undefined) {
       const nodesValidation = (0, _validate.validateTargetNodes)(matches);
       if (!nodesValidation.valid) throw nodesValidation.error;
-      const result = applyUpdateAction(normalizedPaths, actionElement.update, targetElement, options);
+      const result = applyUpdateAction(normalizedPaths, actionElement.update, workingElement, mutatingOptions);
       tracer?.action({
         target: targetExpression,
         type: 'update',
@@ -233,7 +290,7 @@ const applyAction = (actionElement, targetElement, options = defaultApplyOptions
       const nodesValidation = (0, _validate.validateTargetNodes)(matches);
       if (!nodesValidation.valid) throw nodesValidation.error;
       const copyExpression = (0, _apidomCore.toValue)(actionElement.copy);
-      const result = applyCopyAction(normalizedPaths, copyExpression, targetElement, options);
+      const result = applyCopyAction(normalizedPaths, copyExpression, workingElement, mutatingOptions);
       tracer?.action({
         target: targetExpression,
         type: 'copy',
@@ -248,7 +305,7 @@ const applyAction = (actionElement, targetElement, options = defaultApplyOptions
       matchCount: matches.length,
       normalizedPaths
     });
-    return targetElement;
+    return workingElement;
   } catch (error) {
     // enrich OverlayError with action context, preserving original stack
     if (error instanceof _OverlayError.default && !error.action) {
@@ -268,7 +325,22 @@ const applyAction = (actionElement, targetElement, options = defaultApplyOptions
 
 /**
  * Applies an entire overlay document to a target element.
- * Immutable — returns a new element with all actions applied sequentially.
+ *
+ * Immutable by default. The target is cloned once up front and all actions are
+ * applied to the clone sequentially, so the returned element is always
+ * independent of the input, including when no action changes anything. Pass
+ * `immutable: false` to apply the actions in place; the one shape that cannot
+ * be applied in place is a `target: $` action replacing a primitive root with
+ * a differently typed value, so the return value is authoritative in both
+ * modes.
+ *
+ * When the target is a `ParseResultElement`, a new parse result is returned
+ * carrying the new tree as its result element; the caller's parse result and
+ * its result element are left untouched. Every other child — annotations, and
+ * an `api` element that is not the result element itself — is shared with the
+ * input rather than copied, since no overlay action can reach it.
+ * Under `immutable: false` the caller's parse result is updated in place
+ * instead, with its result element replaced by the new tree.
  *
  * @public
  */
@@ -278,31 +350,73 @@ const applyOverlay = (overlayElement, targetElement, options = defaultApplyOptio
   if (!(0, _apidomNsOverlay.isOverlay1Element)(overlay)) {
     throw new _OverlayError.default('First argument must be an Overlay 1.x document');
   }
+  const opts = withDefaults(options);
+  let parseResult;
+  let resultElement;
   let target;
   if (targetElement instanceof _apidomDatamodel.ParseResultElement) {
     if (targetElement.result === undefined) {
       throw new _OverlayError.default('Target ParseResultElement contains no result element');
     }
-    target = targetElement.result;
+    /**
+     * Only the result element changes, so the wrapper is cloned shallowly: the
+     * clone gets its own content list, which the new tree replaces the result
+     * element in, and every child the overlay never touches is shared with the
+     * input instead of copied.
+     */
+    parseResult = opts.immutable ? (0, _apidomDatamodel.cloneShallow)(targetElement) : targetElement;
+    resultElement = parseResult.result;
+    target = resultElement;
   } else {
     target = targetElement;
   }
-  if (!(0, _apidomDatamodel.isArrayElement)(overlay.actions)) {
-    return targetElement;
-  }
-  const tracer = options.trace ? new _TraceBuilder.default(options.trace) : undefined;
+  target = opts.immutable ? (0, _apidomDatamodel.cloneDeep)(target) : target;
+
+  /**
+   * Constructed only once the target has been validated: the constructor writes
+   * a success verdict into the caller's trace object, which must not survive a
+   * throw from the checks above.
+   */
+  const tracer = opts.trace ? new _TraceBuilder.default(opts.trace) : undefined;
   const internalOptions = tracer ? {
-    ...options,
+    ...opts,
     tracer
-  } : options;
-  for (const action of overlay.actions) {
-    target = applyAction(action, target, internalOptions);
+  } : opts;
+  // clone once, then apply the actions mutably to the clone
+  const mutatingOptions = {
+    ...internalOptions,
+    immutable: false
+  };
+  if ((0, _apidomDatamodel.isArrayElement)(overlay.actions)) {
+    for (const action of overlay.actions) {
+      target = applyAction(action, target, mutatingOptions);
+    }
   }
-  if (targetElement instanceof _apidomDatamodel.ParseResultElement) {
-    if (target !== targetElement.result) {
-      targetElement.replaceResult(target);
+  if (parseResult !== undefined) {
+    /**
+     * The result marker is a class on the element itself, and replacing a
+     * primitive root swaps in the update value's meta wholesale, so an action
+     * can strip it. Restore it before the element goes back into the wrapper,
+     * otherwise the returned parse result has no result element at all.
+     */
+    if (!(0, _apidomDatamodel.includesClasses)(target, ['result'])) {
+      target.classes.push('result');
+    }
+
+    /**
+     * replaceResult locates the slot by scanning for the marker, so the element
+     * being replaced has to carry one too. An earlier action that stripped the
+     * marker off the element still sitting in the wrapper would otherwise leave
+     * that lookup with nothing to find, and the new tree would be dropped on
+     * the floor.
+     */
+    if (target !== resultElement) {
+      if (!(0, _apidomDatamodel.includesClasses)(resultElement, ['result'])) {
+        resultElement.classes.push('result');
+      }
+      parseResult.replaceResult(target);
     }
-    return targetElement;
+    return parseResult;
   }
   return target;
 };

package/src/apply/realms/apidom.mjs

@@ -1,4 +1,4 @@
-import { isObjectElement, isArrayElement, cloneDeep, ParseResultElement } from '@speclynx/apidom-datamodel';
+import { isObjectElement, isArrayElement, includesClasses, cloneDeep, cloneShallow, ParseResultElement } from '@speclynx/apidom-datamodel';
 import { deepmerge, toValue } from '@speclynx/apidom-core';
 import { evaluate, NormalizedPath } from '@speclynx/apidom-json-path';
 import { isOverlay1Element } from '@speclynx/apidom-ns-overlay-1';
@@ -16,6 +16,18 @@ const defaultApplyOptions = {
   strict: false
 };
 
+/**
+ * Merges caller options over the defaults. A partial options object leaves the
+ * fields it omits undefined, which must still mean the documented defaults.
+ * `immutable` is spelled out because it is the only default that is not falsy,
+ * so a caller forwarding an undefined value must not end up mutating in place.
+ */
+const withDefaults = options => ({
+  ...defaultApplyOptions,
+  ...options,
+  immutable: options.immutable ?? defaultApplyOptions.immutable
+});
+
 /**
  * Default customMerge that enforces Overlay spec type compatibility.
  * Throws OverlayError on incompatible type combinations.
@@ -76,12 +88,37 @@ const resolveParent = (normalizedPath, root) => {
  * @public
  */
 export const applyUpdateAction = (normalizedPaths, updateValue, targetElement, options = defaultApplyOptions) => {
-  let result = options.immutable ? cloneDeep(targetElement) : targetElement;
+  const opts = withDefaults(options);
+  let result = opts.immutable ? cloneDeep(targetElement) : targetElement;
   for (const normalizedPath of normalizedPaths) {
+    /**
+     * Every matched node gets its own copy of the update value. deepmerge
+     * shallow clones members, so the merged result shares key elements and
+     * non-mergeable values with its source regardless of the clone option —
+     * without this each target would alias every other target, and a copy
+     * action would alias the copy source in the target document.
+     */
+    const clonedUpdateValue = cloneDeep(updateValue);
     const resolved = resolveParent(normalizedPath, result);
     if (resolved === null) {
-      // targeting root
-      result = mergeValue(result, updateValue, options);
+      /**
+       * Targeting root. There is no parent slot to write the merged element
+       * into, so the merge is transplanted back onto the target itself — every
+       * other target shape updates the document in place and the root must not
+       * be the silent exception. Merging always yields the target's own
+       * constructor, so the transplant is type-safe. Two cases cannot be
+       * written in place and fall back to rebinding: a primitive root replaced
+       * by a differently typed value, and a frozen root, whose properties
+       * cannot be assigned.
+       */
+      const merged = mergeValue(result, clonedUpdateValue, opts);
+      if (merged.constructor === result.constructor && !result.isFrozen) {
+        result.content = merged.content;
+        result.meta = merged.meta;
+        result.attributes = merged.attributes;
+      } else {
+        result = merged;
+      }
       continue;
     }
     const {
@@ -91,12 +128,12 @@ export const applyUpdateAction = (normalizedPaths, updateValue, targetElement, o
     if (isObjectElement(parent)) {
       const current = parent.get(key);
       if (current !== undefined) {
-        parent.set(key, mergeValue(current, updateValue, options));
+        parent.set(key, mergeValue(current, clonedUpdateValue, opts));
       }
     } else if (isArrayElement(parent)) {
       const current = parent.get(key);
       if (current !== undefined) {
-        parent.content[key] = mergeValue(current, updateValue, options);
+        parent.content[key] = mergeValue(current, clonedUpdateValue, opts);
       }
     }
   }
@@ -115,7 +152,13 @@ export const applyCopyAction = (normalizedPaths, copyExpression, targetElement,
   if (sourceMatches.length > 1) {
     throw new OverlayError(`Copy source JSONPath "${copyExpression}" must select a single node, but selected ${sourceMatches.length}`);
   }
-  const sourceValue = sourceMatches[0];
+
+  /**
+   * Snapshot the copy source. Matched targets are updated in document order and
+   * the source may sit under one of them, so a live reference would let later
+   * targets copy a source that an earlier target already modified.
+   */
+  const sourceValue = cloneDeep(sourceMatches[0]);
   return applyUpdateAction(normalizedPaths, sourceValue, targetElement, options);
 };
 
@@ -124,7 +167,8 @@ export const applyCopyAction = (normalizedPaths, copyExpression, targetElement,
  * @public
  */
 export const applyRemoveAction = (normalizedPaths, targetElement, options = defaultApplyOptions) => {
-  const result = options.immutable ? cloneDeep(targetElement) : targetElement;
+  const opts = withDefaults(options);
+  const result = opts.immutable ? cloneDeep(targetElement) : targetElement;
   // reverse document order so higher array indices are removed first (avoids index shifting)
   const sorted = [...normalizedPaths].reverse();
   for (const normalizedPath of sorted) {
@@ -147,13 +191,19 @@ export const applyRemoveAction = (normalizedPaths, targetElement, options = defa
 
 /**
  * Applies a single overlay action to a target element.
- * Immutable — returns a new element with the action applied.
+ *
+ * Immutable by default. The target is cloned once up front and the action is
+ * applied to the clone, so the returned element is always independent of the
+ * input, including when the action changes nothing. Pass `immutable: false` to
+ * apply the action in place; the one shape that cannot be applied in place is
+ * a `target: $` action replacing a primitive root with a differently typed
+ * value, so the return value is authoritative in both modes.
  *
  * @public
  */
 export const applyAction = (actionElement, targetElement, options = defaultApplyOptions) => {
-  const internalOpts = options;
-  const tracer = internalOpts.tracer ?? (options.trace ? new TraceBuilder(options.trace) : undefined);
+  const opts = withDefaults(options);
+  const tracer = opts.tracer ?? (opts.trace ? new TraceBuilder(opts.trace) : undefined);
   const actionValidation = validateAction(actionElement);
   if (!actionValidation.valid) throw actionValidation.error;
   const targetExpression = toValue(actionElement.target);
@@ -166,7 +216,7 @@ export const applyAction = (actionElement, targetElement, options = defaultApply
     }
   });
   if (matches.length === 0) {
-    if (options.strict) {
+    if (opts.strict) {
       const error = new OverlayError(`Action target "${targetExpression}" matched zero nodes (strict mode)`, {
         action: actionElement
       });
@@ -186,13 +236,20 @@ export const applyAction = (actionElement, targetElement, options = defaultApply
       matchCount: 0,
       normalizedPaths: []
     });
-    return targetElement;
+    return opts.immutable ? cloneDeep(targetElement) : targetElement;
   }
+
+  // clone once, then apply the action mutably to the clone
+  const workingElement = opts.immutable ? cloneDeep(targetElement) : targetElement;
+  const mutatingOptions = {
+    ...opts,
+    immutable: false
+  };
   try {
     // remove action
     const removeValue = actionElement.removeField;
     if (removeValue !== undefined && toValue(removeValue) === true) {
-      const result = applyRemoveAction(normalizedPaths, targetElement, options);
+      const result = applyRemoveAction(normalizedPaths, workingElement, mutatingOptions);
       tracer?.action({
         target: targetExpression,
         type: 'remove',
@@ -206,7 +263,7 @@ export const applyAction = (actionElement, targetElement, options = defaultApply
     if (actionElement.update !== undefined) {
       const nodesValidation = validateTargetNodes(matches);
       if (!nodesValidation.valid) throw nodesValidation.error;
-      const result = applyUpdateAction(normalizedPaths, actionElement.update, targetElement, options);
+      const result = applyUpdateAction(normalizedPaths, actionElement.update, workingElement, mutatingOptions);
       tracer?.action({
         target: targetExpression,
         type: 'update',
@@ -221,7 +278,7 @@ export const applyAction = (actionElement, targetElement, options = defaultApply
       const nodesValidation = validateTargetNodes(matches);
       if (!nodesValidation.valid) throw nodesValidation.error;
       const copyExpression = toValue(actionElement.copy);
-      const result = applyCopyAction(normalizedPaths, copyExpression, targetElement, options);
+      const result = applyCopyAction(normalizedPaths, copyExpression, workingElement, mutatingOptions);
       tracer?.action({
         target: targetExpression,
         type: 'copy',
@@ -236,7 +293,7 @@ export const applyAction = (actionElement, targetElement, options = defaultApply
       matchCount: matches.length,
       normalizedPaths
     });
-    return targetElement;
+    return workingElement;
   } catch (error) {
     // enrich OverlayError with action context, preserving original stack
     if (error instanceof OverlayError && !error.action) {
@@ -256,7 +313,22 @@ export const applyAction = (actionElement, targetElement, options = defaultApply
 
 /**
  * Applies an entire overlay document to a target element.
- * Immutable — returns a new element with all actions applied sequentially.
+ *
+ * Immutable by default. The target is cloned once up front and all actions are
+ * applied to the clone sequentially, so the returned element is always
+ * independent of the input, including when no action changes anything. Pass
+ * `immutable: false` to apply the actions in place; the one shape that cannot
+ * be applied in place is a `target: $` action replacing a primitive root with
+ * a differently typed value, so the return value is authoritative in both
+ * modes.
+ *
+ * When the target is a `ParseResultElement`, a new parse result is returned
+ * carrying the new tree as its result element; the caller's parse result and
+ * its result element are left untouched. Every other child — annotations, and
+ * an `api` element that is not the result element itself — is shared with the
+ * input rather than copied, since no overlay action can reach it.
+ * Under `immutable: false` the caller's parse result is updated in place
+ * instead, with its result element replaced by the new tree.
  *
  * @public
  */
@@ -265,31 +337,73 @@ export const applyOverlay = (overlayElement, targetElement, options = defaultApp
   if (!isOverlay1Element(overlay)) {
     throw new OverlayError('First argument must be an Overlay 1.x document');
   }
+  const opts = withDefaults(options);
+  let parseResult;
+  let resultElement;
   let target;
   if (targetElement instanceof ParseResultElement) {
     if (targetElement.result === undefined) {
       throw new OverlayError('Target ParseResultElement contains no result element');
     }
-    target = targetElement.result;
+    /**
+     * Only the result element changes, so the wrapper is cloned shallowly: the
+     * clone gets its own content list, which the new tree replaces the result
+     * element in, and every child the overlay never touches is shared with the
+     * input instead of copied.
+     */
+    parseResult = opts.immutable ? cloneShallow(targetElement) : targetElement;
+    resultElement = parseResult.result;
+    target = resultElement;
   } else {
     target = targetElement;
   }
-  if (!isArrayElement(overlay.actions)) {
-    return targetElement;
-  }
-  const tracer = options.trace ? new TraceBuilder(options.trace) : undefined;
+  target = opts.immutable ? cloneDeep(target) : target;
+
+  /**
+   * Constructed only once the target has been validated: the constructor writes
+   * a success verdict into the caller's trace object, which must not survive a
+   * throw from the checks above.
+   */
+  const tracer = opts.trace ? new TraceBuilder(opts.trace) : undefined;
   const internalOptions = tracer ? {
-    ...options,
+    ...opts,
     tracer
-  } : options;
-  for (const action of overlay.actions) {
-    target = applyAction(action, target, internalOptions);
+  } : opts;
+  // clone once, then apply the actions mutably to the clone
+  const mutatingOptions = {
+    ...internalOptions,
+    immutable: false
+  };
+  if (isArrayElement(overlay.actions)) {
+    for (const action of overlay.actions) {
+      target = applyAction(action, target, mutatingOptions);
+    }
   }
-  if (targetElement instanceof ParseResultElement) {
-    if (target !== targetElement.result) {
-      targetElement.replaceResult(target);
+  if (parseResult !== undefined) {
+    /**
+     * The result marker is a class on the element itself, and replacing a
+     * primitive root swaps in the update value's meta wholesale, so an action
+     * can strip it. Restore it before the element goes back into the wrapper,
+     * otherwise the returned parse result has no result element at all.
+     */
+    if (!includesClasses(target, ['result'])) {
+      target.classes.push('result');
+    }
+
+    /**
+     * replaceResult locates the slot by scanning for the marker, so the element
+     * being replaced has to carry one too. An earlier action that stripped the
+     * marker off the element still sitting in the wrapper would otherwise leave
+     * that lookup with nothing to find, and the new tree would be dropped on
+     * the floor.
+     */
+    if (target !== resultElement) {
+      if (!includesClasses(resultElement, ['result'])) {
+        resultElement.classes.push('result');
+      }
+      parseResult.replaceResult(target);
     }
-    return targetElement;
+    return parseResult;
   }
   return target;
 };

package/src/apply/realms/pojo.cjs

@@ -11,15 +11,27 @@ var _apidom = require("./apidom.cjs");
 /**
  * Applies a single overlay action (POJO) to a target (POJO).
  *
+ * The refracted target never escapes this function and the result is converted
+ * straight back to a POJO, so it is applied in place.
+ *
  * @public
  */
-const applyAction = (action, target, options) => (0, _apidomCore.toValue)((0, _apidom.applyAction)((0, _apidomNsOverlay.refractAction)(action), (0, _apidomDatamodel.refract)(target), options));
+const applyAction = (action, target, options) => (0, _apidomCore.toValue)((0, _apidom.applyAction)((0, _apidomNsOverlay.refractAction)(action), (0, _apidomDatamodel.refract)(target), {
+  ...options,
+  immutable: false
+}));
 
 /**
  * Applies an entire overlay document (POJO) to a target (POJO).
  *
+ * The refracted target never escapes this function and the result is converted
+ * straight back to a POJO, so it is applied in place.
+ *
  * @public
  */
 exports.applyAction = applyAction;
-const applyOverlay = (overlay, target, options) => (0, _apidomCore.toValue)((0, _apidom.applyOverlay)((0, _apidomNsOverlay.refractOverlay1)(overlay), (0, _apidomDatamodel.refract)(target), options));
+const applyOverlay = (overlay, target, options) => (0, _apidomCore.toValue)((0, _apidom.applyOverlay)((0, _apidomNsOverlay.refractOverlay1)(overlay), (0, _apidomDatamodel.refract)(target), {
+  ...options,
+  immutable: false
+}));
 exports.applyOverlay = applyOverlay;