velocious 1.0.556 → 1.0.558

package/src/frontend-models/base.js

@@ -12,7 +12,7 @@ import {deserializeFrontendModelTransportValue, serializeFrontendModelTransportV
 import runWithTransportDeadline from "./transport-deadline.js"
 import {REQUEST_TIME_ZONE_HEADER, validateTimeZone} from "../time-zone.js"
 import VelociousWebsocketClient from "../http-client/websocket-client.js"
-import {bufferOutgoingEvent, drainBufferedOutgoingEvents} from "./outgoing-event-buffer.js"
+import {bufferOutgoingEvent, clearBufferedOutgoingEvents, drainBufferedOutgoingEvents} from "./outgoing-event-buffer.js"
 import {defineModelScope} from "../utils/model-scope.js"
 import isPlainObject from "../utils/plain-object.js"
 import {readPayloadAssociationCount, readPayloadComputedAbility, readPayloadQueryData, setPayloadAssociationCount, setPayloadComputedAbility, setPayloadQueryData} from "../record-payload-values.js"
@@ -154,6 +154,64 @@ let frontendModelIdleResolvers = []
  * Internal websocket client.
  * @type {VelociousWebsocketClient | null} */
 let internalWebsocketClient = null
+/** @type {AbortSignal | null} */
+let internalWebsocketClientSignal = null
+/** @type {(() => void) | null} */
+let internalWebsocketClientSignalCleanup = null
+
+/**
+ * Detaches an owned WebSocket client from the shared cache if it is still current.
+ * @param {VelociousWebsocketClient} client - Client whose ownership is ending.
+ * @returns {void}
+ */
+function detachInternalWebsocketClient(client) {
+  if (internalWebsocketClient !== client) return
+
+  internalWebsocketClient = null
+  internalWebsocketClientSignalCleanup?.()
+  internalWebsocketClientSignal = null
+  internalWebsocketClientSignalCleanup = null
+}
+
+/**
+ * Disposes the owned WebSocket client before transport/session configuration changes.
+ * @returns {void}
+ */
+function resetInternalWebsocketClient() {
+  const client = internalWebsocketClient
+
+  if (!client) return
+
+  detachInternalWebsocketClient(client)
+  void client.disconnectAndStopReconnect()
+}
+
+/**
+ * Binds the owned WebSocket client lifetime to the current session signal.
+ * @param {AbortSignal | undefined} sessionSignal - Current session signal.
+ * @returns {void}
+ */
+function bindInternalWebsocketClientSignal(sessionSignal) {
+  if (internalWebsocketClientSignal === sessionSignal) return
+
+  internalWebsocketClientSignalCleanup?.()
+  internalWebsocketClientSignal = sessionSignal || null
+  internalWebsocketClientSignalCleanup = null
+
+  if (!sessionSignal || !internalWebsocketClient) return
+
+  const client = internalWebsocketClient
+  const onSessionAbort = () => {
+    detachInternalWebsocketClient(client)
+    clearBufferedOutgoingEvents()
+    void client.disconnectAndStopReconnect()
+  }
+
+  sessionSignal.addEventListener("abort", onSessionAbort, {once: true})
+  internalWebsocketClientSignalCleanup = () => sessionSignal.removeEventListener("abort", onSessionAbort)
+
+  if (sessionSignal.aborted) onSessionAbort()
+}
 
 /**
  * Runs frontend model transport is idle.
@@ -237,7 +295,13 @@ async function trackFrontendModelTransportRequest(callback) {
  * @returns {VelociousWebsocketClient | null} Websocket client or null.
  */
 function resolveInternalWebsocketClient() {
-  if (internalWebsocketClient) return internalWebsocketClient
+  if (internalWebsocketClient) {
+    const client = internalWebsocketClient
+
+    bindInternalWebsocketClientSignal(frontendModelTransportSignal())
+
+    return client
+  }
 
   const websocketUrl = frontendModelTransportConfig.websocketUrl
 
@@ -248,41 +312,68 @@ function resolveInternalWebsocketClient() {
 
   if (!resolvedUrl) return null
 
-  internalWebsocketClient = new VelociousWebsocketClient({
+  const client = new VelociousWebsocketClient({
     autoReconnect: true,
     sessionStore: frontendModelTransportConfig.sessionStore,
     url: resolvedUrl
   })
-  internalWebsocketClient.onReconnect = flushBufferedOutgoingEventsAfterReconnect
+  internalWebsocketClient = client
+  client.onReconnect = async () => await flushBufferedOutgoingEventsAfterReconnect(client)
 
-  return internalWebsocketClient
+  bindInternalWebsocketClientSignal(frontendModelTransportSignal())
+
+  return client
 }
 
 /**
  * Runs flush buffered outgoing events after reconnect.
+ * @param {VelociousWebsocketClient} client - Reconnected client that owns this flush.
  * @returns {Promise<void>} */
-async function flushBufferedOutgoingEventsAfterReconnect() {
-  if (!internalWebsocketClient) return
+async function flushBufferedOutgoingEventsAfterReconnect(client) {
+  if (internalWebsocketClient !== client) return
 
   const events = drainBufferedOutgoingEvents()
+  const sessionSignal = frontendModelTransportSignal()
 
-  for (let index = 0; index < events.length; index += 1) {
-    try {
-      await internalWebsocketClient.post(events[index].customPath, events[index].payload)
-    } catch {
-      const socketOpen = internalWebsocketClient.socket?.readyState === internalWebsocketClient.socket?.OPEN
+  await runWithTransportDeadline(
+    {
+      errorMessage: "Buffered frontend-model WebSocket flush timed out",
+      signal: sessionSignal,
+      timeoutMs: frontendModelTransportTimeoutMs()
+    },
+    async (signal) => {
+      for (let index = 0; index < events.length; index += 1) {
+        if (internalWebsocketClient !== client) return
 
-      if (socketOpen) {
-        continue
-      }
+        try {
+          await client.post(events[index].customPath, events[index].payload, {signal})
 
-      for (let remaining = index; remaining < events.length; remaining += 1) {
-        bufferOutgoingEvent(events[remaining])
-      }
+          if (internalWebsocketClient !== client) return
+        } catch {
+          if (internalWebsocketClient !== client) return
+          if (sessionSignal?.aborted) return
 
-      return
+          if (signal.aborted) {
+            for (let remaining = index; remaining < events.length; remaining += 1) {
+              bufferOutgoingEvent(events[remaining])
+            }
+
+            return
+          }
+
+          const socketOpen = client.socket?.readyState === client.socket?.OPEN
+
+          if (socketOpen) continue
+
+          for (let remaining = index; remaining < events.length; remaining += 1) {
+            bufferOutgoingEvent(events[remaining])
+          }
+
+          return
+        }
+      }
     }
-  }
+  )
 }
 
 /**
@@ -1784,6 +1875,29 @@ function frontendModelTransportSignal() {
   return configuredSignal || undefined
 }
 
+/**
+ * Resolves per-startup controls with the configured session cancellation.
+ * @param {{timeoutMs?: number, signal?: AbortSignal}} controls - Call controls.
+ * @returns {{timeoutMs?: number, signal?: AbortSignal}} - Effective startup controls.
+ */
+function frontendModelWebsocketStartupControls(controls) {
+  const sessionSignal = frontendModelTransportSignal()
+  let signal = controls.signal || sessionSignal
+
+  if (controls.signal && sessionSignal && controls.signal !== sessionSignal) {
+    signal = AbortSignal.any([controls.signal, sessionSignal])
+  }
+
+  const configuredTimeoutMs = frontendModelTransportTimeoutMs()
+  const timeoutMs = controls.timeoutMs === undefined
+    ? configuredTimeoutMs
+    : configuredTimeoutMs === undefined
+      ? controls.timeoutMs
+      : Math.min(controls.timeoutMs, configuredTimeoutMs)
+
+  return {signal, timeoutMs}
+}
+
 /**
  * Runs perform shared frontend model api request.
  * @param {Record<string, ?>} requestPayload - Shared request payload.
@@ -2897,7 +3011,7 @@ export default class FrontendModelBase {
     if (Object.prototype.hasOwnProperty.call(config, "websocketUrl")) {
       frontendModelTransportConfig.websocketUrl = config.websocketUrl
       // Reset cached internal client so the new URL takes effect on next subscribe
-      internalWebsocketClient = null
+      resetInternalWebsocketClient()
     }
 
     if (Object.prototype.hasOwnProperty.call(config, "requestHeaders")) {
@@ -2909,7 +3023,10 @@ export default class FrontendModelBase {
     }
 
     if (Object.prototype.hasOwnProperty.call(config, "signal")) {
-      frontendModelTransportConfig.signal = config.signal
+      if (frontendModelTransportConfig.signal !== config.signal) {
+        frontendModelTransportConfig.signal = config.signal
+        resetInternalWebsocketClient()
+      }
     }
 
     if (Object.prototype.hasOwnProperty.call(config, "timeZone")) {
@@ -2923,7 +3040,7 @@ export default class FrontendModelBase {
     if (Object.prototype.hasOwnProperty.call(config, "sessionStore")) {
       frontendModelTransportConfig.sessionStore = config.sessionStore
       // Reset cached internal client so the new sessionStore is picked up.
-      internalWebsocketClient = null
+      resetInternalWebsocketClient()
     }
 
     if (Object.prototype.hasOwnProperty.call(config, "offlineSync")) {
@@ -2933,16 +3050,17 @@ export default class FrontendModelBase {
 
   /**
    * Connect the internal WebSocket and enable auto-reconnect.
+   * @param {{timeoutMs?: number, signal?: AbortSignal}} [options] - Startup controls composed with the configured transport controls.
    * @returns {Promise<void>} - Resolves when connected.
    */
-  static async connectWebsocket() {
+  static async connectWebsocket(options = {}) {
     const client = resolveInternalWebsocketClient()
 
     if (!client) {
       throw new Error("connectWebsocket requires configureTransport({websocketUrl})")
     }
 
-    await client.connect()
+    await client.connect(frontendModelWebsocketStartupControls(options))
   }
 
   /**
@@ -2952,7 +3070,10 @@ export default class FrontendModelBase {
   static async disconnectWebsocket() {
     if (!internalWebsocketClient) return
 
-    await internalWebsocketClient.disconnectAndStopReconnect()
+    const client = internalWebsocketClient
+
+    detachInternalWebsocketClient(client)
+    await client.disconnectAndStopReconnect()
   }
 
   /**
@@ -3026,7 +3147,7 @@ export default class FrontendModelBase {
    * functions change (e.g. current-user sign-in/out). The handle
    * retries when the WS client isn't ready and reopens on close.
    * @param {string} connectionType - Connection class name registered on the server.
-   * @param {{shouldConnect: () => boolean, params: () => Record<string, ?>, onMessage?: (body: ?) => void}} options - Connection lifecycle and payload callbacks.
+   * @param {{shouldConnect: () => boolean, params: () => Record<string, ?>, signal?: AbortSignal, onMessage?: (body: ?) => void}} options - Connection lifecycle, cancellation, and payload callbacks.
    * @returns {{sync: () => void, close: () => void}} - Handle used to resync or close the managed connection.
    */
   static openManagedConnection(connectionType, options) {
@@ -3040,11 +3161,29 @@ export default class FrontendModelBase {
      * @type {ReturnType<typeof setTimeout> | null} */
     let retryTimer = null
     let lastParamsJson = ""
+    const controls = frontendModelWebsocketStartupControls({signal: options.signal})
+    const clearRetryTimer = () => {
+      if (retryTimer === null) return
+
+      globalThis.clearTimeout(retryTimer)
+      retryTimer = null
+    }
+
+    const close = () => {
+      if (closed) return
+
+      closed = true
+      clearRetryTimer()
+      controls.signal?.removeEventListener("abort", close)
+      if (connection && !connection.isClosed()) connection.close()
+      connection = null
+    }
 
     const sync = () => {
       if (closed) return
 
       if (!options.shouldConnect()) {
+        clearRetryTimer()
         if (connection && !connection.isClosed()) connection.close()
         connection = null
         lastParamsJson = ""
@@ -3087,7 +3226,7 @@ export default class FrontendModelBase {
       }
 
       lastParamsJson = nextParamsJson
-      connection = FrontendModelBase.openWebsocketConnection(connectionType, {
+      connection = client.openConnection(connectionType, {
         params: nextParams,
         onMessage: options.onMessage,
         onClose: () => {
@@ -3100,14 +3239,13 @@ export default class FrontendModelBase {
       })
     }
 
-    const close = () => {
-      closed = true
-      if (retryTimer !== null) globalThis.clearTimeout(retryTimer)
-      if (connection && !connection.isClosed()) connection.close()
-      connection = null
-    }
+    controls.signal?.addEventListener("abort", close, {once: true})
 
-    sync()
+    if (controls.signal?.aborted) {
+      close()
+    } else {
+      sync()
+    }
 
     return {sync, close}
   }
@@ -3118,34 +3256,47 @@ export default class FrontendModelBase {
    * `openConnection`. Apps use this for per-session state/messaging
    * that doesn't fit the pub/sub Channel model (locale, presence).
    * @param {string} connectionType - Name the server registered the class under.
-   * @param {{params?: Record<string, ?>, onConnect?: () => void, onMessage?: (body: Record<string, unknown>) => void, onDisconnect?: () => void, onResume?: () => void, onClose?: (reason: string) => void}} [options] - Connection options and event handlers.
+   * @param {{params?: Record<string, ?>, timeoutMs?: number, signal?: AbortSignal, onConnect?: () => void, onMessage?: (body: Record<string, unknown>) => void, onDisconnect?: () => void, onResume?: () => void, onClose?: (reason: string) => void}} [options] - Connection options, readiness controls, and event handlers. Connect the client first; the timeout covers server-confirmed readiness and the signal cancels readiness without entering the wire payload.
    * @returns {{ready: Promise<void>, close: () => void}} - Websocket connection handle.
    */
-  static openWebsocketConnection(connectionType, options) {
+  static openWebsocketConnection(connectionType, options = {}) {
     const client = /** @type {?} */ (frontendModelTransportConfig.websocketClient || resolveInternalWebsocketClient())
 
     if (!client || typeof client.openConnection !== "function") {
       throw new Error("openWebsocketConnection requires configureTransport({websocketUrl})")
     }
 
-    return client.openConnection(connectionType, options || {})
+    const {signal, timeoutMs, ...connectionOptions} = options
+
+    return client.openConnection(connectionType, {
+      ...connectionOptions,
+      ...frontendModelWebsocketStartupControls({signal, timeoutMs})
+    })
   }
 
   /**
    * Subscribes to a pub/sub `WebsocketChannel`. Thin wrapper around
    * the internal client's `subscribeChannel`.
    * @param {string} channelType - Channel class name registered on the server.
-   * @param {{params?: Record<string, ?>, onMessage?: (body: Record<string, unknown>) => void, onDisconnect?: () => void, onResume?: () => void, onClose?: (reason: string) => void}} [options] - Channel subscription options and event handlers.
+   * @param {{params?: Record<string, ?>, timeoutMs?: number, signal?: AbortSignal, onMessage?: (body: Record<string, unknown>) => void, onDisconnect?: () => void, onResume?: () => void, onClose?: (reason: string) => void}} [options] - Channel options, startup controls, and event handlers. The timeout covers connect and server-confirmed readiness only; the signal cancels startup without entering the wire payload.
    * @returns {{ready: Promise<void>, close: () => void}} - Websocket channel handle from the configured client.
    */
-  static subscribeWebsocketChannel(channelType, options) {
+  static subscribeWebsocketChannel(channelType, options = {}) {
     const client = /** @type {?} */ (frontendModelTransportConfig.websocketClient || resolveInternalWebsocketClient())
 
     if (!client || typeof client.subscribeChannel !== "function") {
       throw new Error("subscribeWebsocketChannel requires configureTransport({websocketUrl})")
     }
 
-    return client.subscribeChannel(channelType, options || {})
+    const {signal, timeoutMs, ...channelOptions} = options
+    const startupControls = frontendModelWebsocketStartupControls({signal, timeoutMs})
+    const handle = client.subscribeChannel(channelType, {...channelOptions, ...startupControls})
+
+    if (typeof client.connect === "function") {
+      void client.connect(startupControls).catch(() => handle.close())
+    }
+
+    return handle
   }
 
   /**

package/src/http-client/websocket-client.js

@@ -23,5 +23,53 @@ export default class VelociousWebsocketClient extends SnapReqWebSocketClient {
       url: args.url ?? DEFAULT_URL,
       deserialize: args.deserialize ?? deserializeFrontendModelTransportValue
     })
+    this.reconnectGeneration = 0
+    /** @type {Set<Promise<void>>} */
+    this.runningReconnectTasks = new Set()
+  }
+
+  /**
+   * Ignores an online result resolved after reconnect teardown began.
+   * @returns {Promise<boolean>} - Whether this client generation is online.
+   */
+  async _isOnline() {
+    const generation = this.reconnectGeneration
+    const isOnline = await super._isOnline()
+
+    return generation === this.reconnectGeneration && isOnline
+  }
+
+  /**
+   * Tracks automatic reconnect work so teardown can drain stale attempts.
+   * @returns {Promise<void>} - Resolves after the reconnect attempt settles.
+   */
+  async _attemptReconnect() {
+    const reconnectTask = super._attemptReconnect()
+
+    this.runningReconnectTasks.add(reconnectTask)
+
+    try {
+      await reconnectTask
+    } finally {
+      this.runningReconnectTasks.delete(reconnectTask)
+    }
+  }
+
+  /**
+   * Stops reconnect, drains work that already passed SnapReq's reconnect guard,
+   * and clears state changed by a stale attempt while it settled.
+   * @returns {Promise<void>} - Resolves once no reconnect can resurrect a socket.
+   */
+  async disconnectAndStopReconnect() {
+    this.reconnectGeneration += 1
+    await super.disconnectAndStopReconnect()
+
+    if (this.runningReconnectTasks.size === 0) return
+
+    while (this.runningReconnectTasks.size > 0) {
+      await Promise.all(this.runningReconnectTasks)
+    }
+
+    await super.disconnectAndStopReconnect()
   }
 }

package/src/tenants/tenant.js

@@ -11,19 +11,21 @@ import TenantIterator from "./tenant-iterator.js"
  * class is the single discoverable home for switching into a tenant's context, reading the
  * current one, iterating every tenant of a database identifier, and dropping a tenant's
  * database. Switching delegates to {@link Current} (which owns the async-context tenant
- * state) and additionally runs the callback inside `ensureConnections`, so entering a tenant
+ * state) and additionally runs the callback inside `ensureConnections`, initializing registered
+ * tenant-switched models whose tables exist before the callback runs. Entering a tenant therefore
  * makes its database immediately queryable — the apartment-style "switch" semantics — without
- * the caller establishing connections itself; iteration and drop drive the app's tenant
- * database provider hooks.
+ * the caller establishing connections or model metadata itself; iteration and drop drive the
+ * app's tenant database provider hooks.
  */
 export default class Tenant {
   /**
    * Runs `callback` with `tenant` as the current tenant, restoring the previous tenant after.
    * The callback runs inside `ensureConnections`, so every database identifier the tenant
    * activates (the global database plus the tenant's database) has a checked-out connection
-   * available for the callback's duration: switching into a tenant makes it queryable without
-   * the caller wiring up connections. Already-checked-out connections are reused, so nesting
-   * `Tenant.with` calls does not open redundant connections. The callback receives the active
+   * available for the callback's duration. Registered tenant-switched models whose tables exist
+   * are initialized before the callback runs, so switching into a tenant makes it queryable
+   * without the caller wiring up connections or model metadata. Already-checked-out connections
+   * and in-progress model initialization promises are reused. The callback receives the active
    * connections keyed by identifier, the same as `ensureConnections`.
    * @template T
    * @param {object} tenant Descriptor understood by the app's tenantDatabaseResolver.
@@ -33,7 +35,41 @@ export default class Tenant {
   static async with(tenant, callback) {
     const configuration = Current.configuration()
 
-    return await Current.withTenant(tenant, async () => await configuration.ensureConnections(callback))
+    return await Current.withTenant(tenant, async () => await configuration.ensureConnections(async (connections) => {
+      await this._ensureCurrentTenantModelsInitialized(configuration)
+
+      return await callback(connections)
+    }))
+  }
+
+  /**
+   * Initializes registered tenant-switched models whose tables exist in the
+   * current tenant before runtime callbacks can build synchronous query scopes.
+   * Models for absent optional tables remain deferred until they are used.
+   * @param {import("../configuration.js").default} configuration - Current configuration.
+   * @returns {Promise<void>} - Resolves when available tenant models are initialized.
+   */
+  static async _ensureCurrentTenantModelsInitialized(configuration) {
+    for (const modelClass of Object.values(configuration.getModelClasses())) {
+      if (modelClass.isInitialized() || !modelClass.hasTenantDatabaseIdentifierResolver()) continue
+
+      const databaseIdentifier = modelClass.getTenantDatabaseIdentifier()
+
+      if (!databaseIdentifier || !configuration.isDatabaseIdentifierActive(databaseIdentifier)) continue
+
+      const connection = modelClass.connection()
+      const table = await connection.getTableByName(modelClass.tableName(), {throwError: false})
+
+      if (!table) continue
+
+      if (Object.keys(modelClass.getTranslationsMap()).length > 0) {
+        const translationsTable = await connection.getTableByName(modelClass.getTranslationsTableName(), {throwError: false})
+
+        if (!translationsTable) continue
+      }
+
+      await modelClass.ensureInitialized({configuration})
+    }
   }
 
   /**
@@ -47,9 +83,10 @@ export default class Tenant {
   /**
    * Lists the tenants for a database identifier through the provider and runs `callback`
    * within each tenant's context, optionally filtered and several at a time. Like
-   * {@link Tenant.with}, the callback runs inside `ensureConnections` so each tenant's
-   * database is queryable without the caller wiring up connections. Returns how many tenants
-   * the callback ran for (after filtering).
+   * {@link Tenant.with}, the callback runs inside `ensureConnections` after available
+   * tenant-switched models are initialized, so each tenant's database is queryable without the
+   * caller wiring up connections or model metadata. Returns how many tenants the callback ran
+   * for (after filtering).
    * @param {{identifier: string, callback: function({databaseConfiguration: import("../configuration-types.js").DatabaseConfigurationType, tenant: ?}) : Promise<void>, parallel?: number, filter?: (tenant: ?) => boolean, configuration?: import("../configuration.js").default}} args - Tenant database identifier, per-tenant operation, filtering, and concurrency settings.
    * @returns {Promise<number>} - Number of processed tenants.
    */
@@ -71,7 +108,10 @@ export default class Tenant {
     // their callbacks, such as create, before the tenant database exists) while runtime
     // iteration here gets the tenant's connections established the same way Tenant.with does.
     return await iterator.run(tenants, async (callbackArgs) => {
-      await configuration.ensureConnections({name: `Tenant.each: ${identifier}`}, async () => await callback(callbackArgs))
+      await configuration.ensureConnections({name: `Tenant.each: ${identifier}`}, async () => {
+        await this._ensureCurrentTenantModelsInitialized(configuration)
+        await callback(callbackArgs)
+      })
     })
   }
 

package/src/testing/factory/factory-registry.js

@@ -333,17 +333,27 @@ export default class FactoryRegistry {
     const {traits, overrides} = normalizeInvocationArgs(args)
     /** @type {Array<?>} */
     const results = []
+    /** @type {import("./factory-runner.js").CompiledPlan | undefined} */
+    let planTemplate
 
-    for (let index = 0; index < count; index++) {
-      results.push(await this._runFactory({factoryName, traits, overrides, strategy}))
+    this._activeEvaluations += 1
+
+    try {
+      for (let index = 0; index < count; index++) {
+        const invocation = await this._runFactoryInvocation({factoryName, traits, overrides, strategy, planTemplate})
+
+        planTemplate = invocation.planTemplate
+        results.push(invocation.result)
+      }
+    } finally {
+      this._activeEvaluations -= 1
     }
 
     return results
   }
 
   /**
-   * Compiles and runs a factory invocation under a strategy, tracking active
-   * evaluations for the mutation guard.
+   * Compiles and runs a factory invocation under a strategy.
    * @param {object} args - Options.
    * @param {string} args.factoryName - Factory name.
    * @param {string[]} args.traits - Ordered traits.
@@ -351,7 +361,21 @@ export default class FactoryRegistry {
    * @param {"attributesFor" | "build" | "create"} args.strategy - Strategy name.
    * @returns {Promise<?>} - The strategy result.
    */
-  async _runFactory({factoryName, traits, overrides, strategy}) {
+  async _runFactory(args) {
+    return (await this._runFactoryInvocation(args)).result
+  }
+
+  /**
+   * Runs one event-tracked invocation, optionally reusing declaration planning.
+   * @param {object} args - Options.
+   * @param {string} args.factoryName - Factory name.
+   * @param {string[]} args.traits - Ordered traits.
+   * @param {Record<string, ?>} args.overrides - Overrides.
+   * @param {"attributesFor" | "build" | "create"} args.strategy - Strategy name.
+   * @param {import("./factory-runner.js").CompiledPlan} [args.planTemplate] - Reusable declaration plan.
+   * @returns {Promise<{result: ?, planTemplate: import("./factory-runner.js").CompiledPlan}>} - Result and declaration plan.
+   */
+  async _runFactoryInvocation({factoryName, traits, overrides, strategy, planTemplate}) {
     this._activeEvaluations += 1
 
     const invocationId = this._events.nextInvocationId()
@@ -360,12 +384,13 @@ export default class FactoryRegistry {
     try {
       this._events.emit("start", {invocationId, factory: factoryName, strategy, traits})
 
-      const plan = this._runner.compile(factoryName, traits, overrides)
-      const result = await this._strategies[strategy].run({registry: this, plan})
+      const compiledPlanTemplate = planTemplate || this._runner.compileTemplate(factoryName, traits)
+      const compiledPlan = this._runner.applyOverrides(compiledPlanTemplate, overrides)
+      const result = await this._strategies[strategy].run({registry: this, plan: compiledPlan})
 
       this._events.emit("success", {invocationId, factory: factoryName, strategy, traits, durationMs: Date.now() - startedAt})
 
-      return result
+      return {result, planTemplate: compiledPlanTemplate}
     } catch (error) {
       this._events.emit("failure", {invocationId, factory: factoryName, strategy, traits, durationMs: Date.now() - startedAt, error})