@hexabot-ai/agentic 3.1.2-alpha.9 → 3.1.2-beta.1

package/dist/esm/step-executors/parallel-executor.js

@@ -3,40 +3,254 @@
  * Copyright (c) 2025 Hexastack.
  * Full terms: see LICENSE.md.
  */
-import { markStepsSkipped } from './skip-helpers';
-import { wrapSuspensionContinuation } from './suspension-continuation';
+import { getAbortReason, ParallelSuspensionError, throwIfAborted, WorkflowCancellationError, } from '../errors';
+import { markStepsCancelled } from './skip-helpers';
 /**
- * Execute a set of steps in parallel order, respecting the configured strategy.
+ * Execute a set of child steps concurrently and resolve according to the configured strategy.
  *
  * @param env Executor environment providing helpers and workflow context.
  * @param step The parallel step definition including strategy and children.
  * @param state Mutable workflow execution state.
  * @param path Path tokens locating this parallel block in the workflow.
- * @param startIndex Index to resume execution from when continuing.
- * @returns A suspension if a child pauses execution, otherwise void.
+ * @returns Always undefined; suspensions are rejected inside parallel blocks.
  */
-export async function executeParallel(env, step, state, path, startIndex = 0) {
-    for (let index = startIndex; index < step.steps.length; index += 1) {
-        const child = step.steps[index];
-        const childPath = [...path, 'parallel', index];
-        const suspension = await env.executeStep(child, state, childPath);
+export async function executeParallel(env, step, state, path) {
+    if (step.steps.length === 0) {
+        return undefined;
+    }
+    throwIfAborted(env.signal);
+    const baseOutput = cloneRecord(state.output);
+    const baseContextState = cloneRecord(env.context.state);
+    const branches = step.steps.map((child, index) => launchBranch({
+        env,
+        child,
+        index,
+        path,
+        parentState: state,
+        baseOutput,
+        baseContextState,
+    }));
+    if (step.strategy === 'wait_any') {
+        return executeWaitAny(env, branches, state);
+    }
+    return executeWaitAll(env, branches, state);
+}
+async function executeWaitAll(env, branches, state) {
+    const pending = new Set(branches);
+    const outcomes = new Map();
+    while (pending.size > 0) {
+        const { branch, result } = await raceNext(pending);
+        pending.delete(branch);
+        outcomes.set(result.index, result);
+        if (result.status === 'failed' || result.status === 'cancelled') {
+            cancelBranches(env, pending, result.error, 'Parallel branch execution was cancelled.');
+            await settleBranches(branches);
+            throw result.error;
+        }
+    }
+    mergeBranchOutputs(state, outcomes);
+}
+async function executeWaitAny(env, branches, state) {
+    const pending = new Set(branches);
+    const outcomes = new Map();
+    while (pending.size > 0) {
+        const { branch, result } = await raceNext(pending);
+        pending.delete(branch);
+        outcomes.set(result.index, result);
+        if (result.status === 'fulfilled') {
+            cancelBranches(env, pending, new WorkflowCancellationError('Parallel wait_any winner selected.'), 'Parallel wait_any branch lost the race.');
+            await settleBranches(branches);
+            mergeBranchOutputs(state, new Map([[result.index, result]]));
+            return;
+        }
+        cancelBranches(env, pending, result.error, 'Parallel branch execution was cancelled.');
+        await settleBranches(branches);
+        throw result.error;
+    }
+}
+function launchBranch({ env, child, index, path, parentState, baseOutput, baseContextState, }) {
+    const controller = createBranchController(env.signal);
+    const trackedOutput = createTrackedOutput(baseOutput);
+    const branchState = {
+        input: parentState.input,
+        output: trackedOutput.output,
+        iteration: parentState.iteration ? { ...parentState.iteration } : undefined,
+        accumulator: cloneValue(parentState.accumulator),
+        iterationStack: [...parentState.iterationStack],
+    };
+    const branchContext = createParallelBranchContext(env.context, cloneRecord(baseContextState));
+    const branchEnv = env.fork({
+        context: branchContext,
+        signal: controller.signal,
+        setCurrentStep: () => undefined,
+    });
+    const childPath = [...path, 'parallel', index];
+    const promise = runBranch(branchEnv, child, branchState, childPath, trackedOutput, index);
+    return {
+        index,
+        step: child,
+        iterationStack: [...parentState.iterationStack],
+        controller,
+        promise,
+    };
+}
+async function runBranch(env, child, branchState, childPath, trackedOutput, index) {
+    try {
+        throwIfAborted(env.signal);
+        const suspension = await env.executeStep(child, branchState, childPath);
         if (suspension) {
-            return wrapSuspensionContinuation(suspension, async () => {
-                if (step.strategy === 'wait_any') {
-                    if (index + 1 < step.steps.length) {
-                        markStepsSkipped(env, step.steps.slice(index + 1), state.iterationStack);
-                    }
-                    return undefined;
-                }
-                return executeParallel(env, step, state, path, index + 1);
-            });
-        }
-        if (step.strategy === 'wait_any') {
-            if (index + 1 < step.steps.length) {
-                markStepsSkipped(env, step.steps.slice(index + 1), state.iterationStack);
+            throw new ParallelSuspensionError();
+        }
+        throwIfAborted(env.signal);
+        return {
+            status: 'fulfilled',
+            index,
+            outputDelta: trackedOutput.getDelta(),
+        };
+    }
+    catch (error) {
+        if (env.signal.aborted) {
+            return { status: 'cancelled', index, error: getAbortReason(env.signal) };
+        }
+        return { status: 'failed', index, error };
+    }
+}
+async function raceNext(pending) {
+    return Promise.race([...pending].map((branch) => branch.promise.then((result) => ({ branch, result }))));
+}
+async function settleBranches(branches) {
+    await Promise.all(branches.map((branch) => branch.promise.catch(() => null)));
+}
+function cancelBranches(env, branches, reason, snapshotReason) {
+    for (const branch of branches) {
+        if (!branch.controller.signal.aborted) {
+            branch.controller.abort(reason instanceof Error
+                ? reason
+                : new WorkflowCancellationError(String(reason)));
+        }
+        markStepsCancelled(env, [branch.step], branch.iterationStack, reason instanceof Error ? reason.message : snapshotReason);
+    }
+}
+function mergeBranchOutputs(state, outcomes) {
+    const ordered = [...outcomes.values()].sort((left, right) => {
+        return left.index - right.index;
+    });
+    for (const outcome of ordered) {
+        if (outcome.status !== 'fulfilled') {
+            continue;
+        }
+        Object.assign(state.output, outcome.outputDelta);
+    }
+}
+function createBranchController(parentSignal) {
+    const controller = new AbortController();
+    if (parentSignal.aborted) {
+        controller.abort(getAbortReason(parentSignal));
+        return controller;
+    }
+    parentSignal.addEventListener('abort', () => controller.abort(getAbortReason(parentSignal)), { once: true });
+    return controller;
+}
+function createTrackedOutput(baseOutput) {
+    const writtenKeys = new Set();
+    const target = cloneRecord(baseOutput);
+    const output = new Proxy(target, {
+        set(record, property, value) {
+            if (typeof property === 'string') {
+                writtenKeys.add(property);
+            }
+            return Reflect.set(record, property, value);
+        },
+        deleteProperty(record, property) {
+            if (typeof property === 'string') {
+                writtenKeys.add(property);
+            }
+            return Reflect.deleteProperty(record, property);
+        },
+    });
+    return {
+        output,
+        getDelta: () => Object.fromEntries([...writtenKeys]
+            .filter((key) => Object.prototype.hasOwnProperty.call(target, key))
+            .map((key) => [key, target[key]])),
+    };
+}
+class ParallelWorkflowRuntimeControl {
+    constructor(getParent) {
+        this.getParent = getParent;
+    }
+    get status() {
+        return this.getParent().status;
+    }
+    get resumeData() {
+        return this.getParent().resumeData;
+    }
+    suspend() {
+        return Promise.reject(new ParallelSuspensionError());
+    }
+    resume(data) {
+        this.getParent().resume(data);
+    }
+    getSnapshot() {
+        return this.getParent().getSnapshot();
+    }
+}
+function createParallelBranchContext(context, branchState) {
+    let state = branchState;
+    const workflow = new ParallelWorkflowRuntimeControl(() => context.workflow);
+    return new Proxy(context, {
+        get(target, property, receiver) {
+            if (property === 'state') {
+                return state;
+            }
+            if (property === 'workflow') {
+                return workflow;
             }
-            return undefined;
+            if (property === 'snapshot') {
+                return () => cloneRecord(state);
+            }
+            if (property === 'attachWorkflowRuntime') {
+                return () => undefined;
+            }
+            return Reflect.get(target, property, receiver);
+        },
+        set(target, property, value, receiver) {
+            if (property === 'state') {
+                state = isRecord(value) ? value : {};
+                return true;
+            }
+            return Reflect.set(target, property, value, receiver);
+        },
+    });
+}
+function cloneRecord(value) {
+    return cloneValue(value);
+}
+function cloneValue(value) {
+    if (value === undefined || value === null) {
+        return value;
+    }
+    if (typeof structuredClone === 'function') {
+        try {
+            return structuredClone(value);
         }
+        catch {
+            // Fall through to JSON clone below.
+        }
+    }
+    try {
+        return JSON.parse(JSON.stringify(value));
+    }
+    catch {
+        if (Array.isArray(value)) {
+            return [...value];
+        }
+        if (isRecord(value)) {
+            return { ...value };
+        }
+        return value;
     }
-    return undefined;
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }

package/dist/esm/step-executors/skip-helpers.js

@@ -20,6 +20,29 @@ const markStepSkipped = (env, step, iterationStack, reason) => {
             break;
     }
 };
+const markStepCancelled = (env, step, iterationStack, reason) => {
+    const stepInfo = env.buildInstanceStepInfo(step, iterationStack);
+    env.markSnapshot(stepInfo, 'cancelled', reason);
+    env.emit('hook:step:cancelled', {
+        runId: env.runId,
+        step: stepInfo,
+        error: new Error(reason ?? 'Step execution was cancelled.'),
+    });
+    switch (step.type) {
+        case StepType.Parallel:
+            step.steps.forEach((child) => markStepCancelled(env, child, iterationStack, reason));
+            break;
+        case StepType.Conditional:
+            step.branches.forEach((branch) => branch.steps.forEach((child) => markStepCancelled(env, child, iterationStack, reason)));
+            break;
+        case StepType.Loop:
+        case StepType.Task:
+            break;
+    }
+};
 export const markStepsSkipped = (env, steps, iterationStack, reason) => {
     steps.forEach((step) => markStepSkipped(env, step, iterationStack, reason));
 };
+export const markStepsCancelled = (env, steps, iterationStack, reason) => {
+    steps.forEach((step) => markStepCancelled(env, step, iterationStack, reason));
+};

package/dist/esm/step-executors/task-executor.js

@@ -3,6 +3,7 @@
  * Copyright (c) 2025 Hexastack.
  * Full terms: see LICENSE.md.
  */
+import { getAbortReason, throwIfAborted } from '../errors';
 import { evaluateMapping } from '../workflow-values';
 /**
  * Execute a task step by running its task and handling suspension or output mapping.
@@ -20,6 +21,11 @@ export async function executeTaskStep(env, step, state, _path) {
         throw new Error(`Task "${step.taskName}" is not defined.`);
     }
     const stepInfo = env.buildInstanceStepInfo(step, state.iterationStack);
+    if (env.signal.aborted) {
+        const error = getAbortReason(env.signal);
+        recordTaskCancellation(env, stepInfo, error);
+        throw error;
+    }
     const scope = {
         input: state.input,
         context: env.context.state,
@@ -28,7 +34,12 @@ export async function executeTaskStep(env, step, state, _path) {
         accumulator: state.accumulator,
     };
     const inputs = await evaluateMapping(task.inputs, scope);
-    env.recordStepExecution(stepInfo, {
+    if (env.signal.aborted) {
+        const error = getAbortReason(env.signal);
+        recordTaskCancellation(env, stepInfo, error);
+        throw error;
+    }
+    const stepExecution = env.recordStepExecution(stepInfo, {
         action: task.actionName,
         status: 'running',
         startedAt: Date.now(),
@@ -38,9 +49,14 @@ export async function executeTaskStep(env, step, state, _path) {
     env.beginStepExecution?.(stepInfo.id);
     env.setCurrentStep(stepInfo);
     env.markSnapshot(stepInfo, 'running');
-    env.emit('hook:step:start', { runId: env.runId, step: stepInfo });
+    env.emit('hook:step:start', {
+        runId: env.runId,
+        step: stepInfo,
+        stepExecution,
+    });
     try {
-        const actionPromise = Promise.resolve().then(() => task.action.run(inputs, env.context, task.settings, task.bindings));
+        throwIfAborted(env.signal);
+        const actionPromise = Promise.resolve().then(() => task.action.run(inputs, env.context, task.settings, task.bindings, env.signal));
         const outcome = await waitForTaskProgress(env, stepInfo.id, actionPromise);
         if (outcome.type === 'completed') {
             await completeTask(env, stepInfo.id, stepInfo, task, state, outcome.value);
@@ -51,6 +67,11 @@ export async function executeTaskStep(env, step, state, _path) {
             recordTaskFailure(env, stepInfo, outcome.error);
             throw outcome.error;
         }
+        if (outcome.type === 'cancelled') {
+            env.clearStepSuspensions(stepInfo.id, outcome.error);
+            recordTaskCancellation(env, stepInfo, outcome.error);
+            throw outcome.error;
+        }
         return buildSuspensionContinuation(env, stepInfo.id, stepInfo, task, state, actionPromise, outcome.request);
     }
     finally {
@@ -62,22 +83,45 @@ const waitForTaskProgress = async (env, stepId, actionPromise) => {
     const suspension = env
         .waitForStepSuspension(stepId)
         .then((request) => ({ type: 'suspended', request }));
-    return Promise.race([completion, suspension]);
+    let cleanupCancellation = () => undefined;
+    const cancellation = new Promise((resolve) => {
+        if (env.signal.aborted) {
+            resolve({ type: 'cancelled', error: getAbortReason(env.signal) });
+            return;
+        }
+        const onAbort = () => {
+            resolve({ type: 'cancelled', error: getAbortReason(env.signal) });
+        };
+        env.signal.addEventListener('abort', onAbort, { once: true });
+        cleanupCancellation = () => {
+            env.signal.removeEventListener('abort', onAbort);
+        };
+    });
+    try {
+        return await Promise.race([completion, suspension, cancellation]);
+    }
+    finally {
+        cleanupCancellation();
+    }
 };
 const completeTask = async (env, stepId, stepInfo, task, state, result) => {
     await env.captureTaskOutput(task, state, result);
-    env.recordStepExecution(stepInfo, {
+    const stepExecution = env.recordStepExecution(stepInfo, {
         status: 'completed',
         endedAt: Date.now(),
         output: result,
         context: { after: env.context.snapshot() },
     });
     env.markSnapshot(stepInfo, 'completed');
-    env.emit('hook:step:success', { runId: env.runId, step: stepInfo });
+    env.emit('hook:step:success', {
+        runId: env.runId,
+        step: stepInfo,
+        stepExecution,
+    });
     env.clearStepSuspensions(stepId);
 };
 const recordSuspension = (env, stepInfo, reason, data) => {
-    env.recordStepExecution(stepInfo, {
+    const stepExecution = env.recordStepExecution(stepInfo, {
         status: 'suspended',
         endedAt: Date.now(),
         reason,
@@ -87,6 +131,7 @@ const recordSuspension = (env, stepInfo, reason, data) => {
     env.emit('hook:step:suspended', {
         runId: env.runId,
         step: stepInfo,
+        stepExecution,
         reason,
         data,
     });
@@ -137,14 +182,36 @@ const buildSuspensionContinuation = (env, stepId, stepInfo, task, state, actionP
     };
 };
 const recordTaskFailure = (env, stepInfo, error) => {
-    env.recordStepExecution(stepInfo, {
+    const normalizedError = normalizeError(error);
+    const stepExecution = env.recordStepExecution(stepInfo, {
         status: 'failed',
         endedAt: Date.now(),
-        error: normalizeError(error),
+        error: normalizedError,
         context: { after: env.context.snapshot() },
     });
     env.markSnapshot(stepInfo, 'failed', normalizeErrorMessage(error));
-    env.emit('hook:step:error', { runId: env.runId, step: stepInfo, error });
+    env.emit('hook:step:error', {
+        runId: env.runId,
+        step: stepInfo,
+        stepExecution,
+        error,
+    });
+};
+const recordTaskCancellation = (env, stepInfo, error) => {
+    const normalizedError = normalizeError(error);
+    const stepExecution = env.recordStepExecution(stepInfo, {
+        status: 'cancelled',
+        endedAt: Date.now(),
+        error: normalizedError,
+        context: { after: env.context.snapshot() },
+    });
+    env.markSnapshot(stepInfo, 'cancelled', normalizeErrorMessage(error));
+    env.emit('hook:step:cancelled', {
+        runId: env.runId,
+        step: stepInfo,
+        stepExecution,
+        error,
+    });
 };
 const normalizeError = (error) => error instanceof Error
     ? { message: error.message, stack: error.stack }

package/dist/esm/suspension-rebuilder.js

@@ -4,8 +4,6 @@
  * Full terms: see LICENSE.md.
  */
 import { executeLoop as runLoopExecutor, shouldStopLoop, updateAccumulator, } from './step-executors/loop-executor';
-import { executeParallel as runParallelExecutor } from './step-executors/parallel-executor';
-import { markStepsSkipped } from './step-executors/skip-helpers';
 import { wrapSuspensionContinuation } from './step-executors/suspension-continuation';
 import { StepType, } from './workflow-event-emitter';
 /**
@@ -166,28 +164,7 @@ export function buildSuspensionForPath(deps, steps, state, targetPath, pathPrefi
         };
     }
     if (step.type === StepType.Parallel) {
-        if (rest[0] !== 'parallel') {
-            return null;
-        }
-        const childPath = rest.slice(1);
-        const childSuspension = buildSuspensionForPath(deps, step.steps, state, childPath, [...currentPath, 'parallel'], iterationDepth, suspensionMetadata);
-        if (!childSuspension) {
-            return null;
-        }
-        const childIndex = typeof childPath[0] === 'number' ? childPath[0] : 0;
-        return wrapSuspensionContinuation(childSuspension, async () => {
-            if (step.strategy === 'wait_any') {
-                if (childIndex + 1 < step.steps.length) {
-                    markStepsSkipped(env, step.steps.slice(childIndex + 1), state.iterationStack ?? []);
-                }
-                return deps.executeFlow(steps, state, pathPrefix, current + 1);
-            }
-            const next = await runParallelExecutor(env, step, state, currentPath, childIndex + 1);
-            if (next) {
-                return wrapSuspensionContinuation(next, () => deps.executeFlow(steps, state, pathPrefix, current + 1));
-            }
-            return deps.executeFlow(steps, state, pathPrefix, current + 1);
-        });
+        return null;
     }
     if (step.type === StepType.Conditional) {
         if (rest[0] !== 'branch' || typeof rest[1] !== 'number') {

package/dist/esm/utils/naming.js

@@ -3,7 +3,7 @@
  * Copyright (c) 2025 Hexastack.
  * Full terms: see LICENSE.md.
  */
-const SNAKE_CASE_REGEX = /^[a-z0-9]+(?:_[a-z0-9]+)+$/;
+export const SNAKE_CASE_REGEX = /^[a-z0-9]+(?:_[a-z0-9]+)*$/;
 /**
  * Verifies that names follow the snake_case convention required by the system.
  *

package/dist/esm/utils/timeout.js

@@ -3,34 +3,89 @@
  * Copyright (c) 2025 Hexastack.
  * Full terms: see LICENSE.md.
  */
+import { getAbortReason, throwIfAborted } from '../errors';
 /**
  * Resolves after the specified duration; useful for retry delays.
  *
  * @param durationMs - Number of milliseconds to wait before resolving.
+ * @param signal - Optional signal used to cancel the wait.
  * @returns A promise that resolves once the duration elapses.
  */
-export const sleep = (durationMs) => new Promise((resolve) => setTimeout(resolve, durationMs));
+export const sleep = (durationMs, signal) => {
+    if (!signal) {
+        return new Promise((resolve) => setTimeout(resolve, durationMs));
+    }
+    throwIfAborted(signal);
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, durationMs);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(getAbortReason(signal));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+};
 /**
  * Wraps a promise and rejects if it does not settle within the timeout.
  *
  * @param promise - Operation that may take longer than the allowed timeout.
  * @param timeoutMs - Maximum time in milliseconds to wait before rejecting.
+ * @param signal - Optional signal used to cancel the operation.
  * @returns The result of the original promise when it resolves in time.
  * @throws Error when the timeout is exceeded.
  */
-export async function withTimeout(promise, timeoutMs) {
-    if (!timeoutMs) {
+export async function withTimeout(promise, timeoutMs, signal) {
+    if (!timeoutMs && !signal) {
         return promise;
     }
     return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => {
-            reject(new Error(`Step execution exceeded timeout of ${timeoutMs}ms`));
-        }, timeoutMs);
+        let settled = false;
+        const timer = timeoutMs
+            ? setTimeout(() => {
+                settled = true;
+                signal?.removeEventListener('abort', onAbort);
+                reject(new Error(`Step execution exceeded timeout of ${timeoutMs}ms`));
+            }, timeoutMs)
+            : undefined;
+        const onAbort = () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (timer) {
+                clearTimeout(timer);
+            }
+            reject(getAbortReason(signal));
+        };
+        if (signal) {
+            if (signal.aborted) {
+                onAbort();
+                return;
+            }
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
         promise.then((value) => {
-            clearTimeout(timer);
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (timer) {
+                clearTimeout(timer);
+            }
+            signal?.removeEventListener('abort', onAbort);
             resolve(value);
         }, (error) => {
-            clearTimeout(timer);
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (timer) {
+                clearTimeout(timer);
+            }
+            signal?.removeEventListener('abort', onAbort);
             reject(error);
         });
     });

package/dist/esm/utils/workflow-definition-resources.js

@@ -0,0 +1,68 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+const getSettingsRef = (definition, settingsKey) => {
+    const settings = definition.settings;
+    if (!settings || typeof settings !== 'object') {
+        return null;
+    }
+    const value = settings[settingsKey];
+    return typeof value === 'string' && value.trim() ? value : null;
+};
+/**
+ * Collect external resource IDs referenced by workflow definition defs.
+ */
+export const collectWorkflowDefinitionResourceRefs = (definition, descriptors) => {
+    const result = Object.fromEntries(descriptors.map((descriptor) => [descriptor.kind, new Set()]));
+    for (const def of Object.values(definition.defs ?? {})) {
+        for (const descriptor of descriptors) {
+            if (def.kind !== descriptor.kind) {
+                continue;
+            }
+            const ref = getSettingsRef(def, descriptor.settingsKey);
+            if (ref) {
+                result[descriptor.kind].add(ref);
+            }
+        }
+    }
+    return Object.fromEntries(Object.entries(result).map(([kind, refs]) => [kind, Array.from(refs)]));
+};
+/**
+ * Rewrite external resource IDs referenced by workflow definition defs.
+ */
+export const remapWorkflowDefinitionResourceRefs = (definition, descriptors, idMaps) => {
+    let didChange = false;
+    const nextDefs = Object.fromEntries(Object.entries(definition.defs ?? {}).map(([defName, def]) => {
+        const descriptor = descriptors.find((item) => item.kind === def.kind);
+        if (!descriptor) {
+            return [defName, def];
+        }
+        const currentRef = getSettingsRef(def, descriptor.settingsKey);
+        const nextRef = currentRef
+            ? idMaps[descriptor.kind]?.[currentRef]
+            : undefined;
+        if (!currentRef || !nextRef || nextRef === currentRef) {
+            return [defName, def];
+        }
+        didChange = true;
+        return [
+            defName,
+            {
+                ...def,
+                settings: {
+                    ...(def.settings ?? {}),
+                    [descriptor.settingsKey]: nextRef,
+                },
+            },
+        ];
+    }));
+    if (!didChange) {
+        return definition;
+    }
+    return {
+        ...definition,
+        defs: nextDefs,
+    };
+};