In 6.x we could then think about removing one of the different declarations.

How? It seems like only one of them provides the full feature set. The other forms are for 'simple' cases. Maybe we could remove the 'dot notation' form, but I think that is also supported by contain().

Yeah, now they are now equal in support with this.
If we want dot notation removed, we would probably want to deprecate that on the contain() part too.

My issue isn't really with the dot notation. It's with array structure like this where the aliases and config keys can be mixed at the same level:

$usersQuery->contain([
    'Articles' => [
        'conditions' => [.....],   // option key
        'Comments',  // model alias
    ],
]);

I would prefer if the 2nd level associations were also under the config key:

$usersQuery->contain([
    'Articles' => [
        'conditions' => [.....],
        'associated' => ['Comments']
    ],
]);

I can agree that

$usersQuery->contain([
    'Articles' => [
        'conditions' => [.....],   // option key
        'Comments',  // model alias
    ],
]);

is awkward. I'm on-board for not having that anymore. Would it suffice to deprecate only this call style in 5.x? That would allow us to remove the problematic scenario with a graceful upgrade path.

It looks like this call style can be detected by having a mix of string and int keys which should be simple enough to detect. I think this also sets us up better for contain options to use a builder pattern more easily in the future.

If aliases were always UpperCaseCamel (upper case first letter), there would also be no collisions.
Same if all other keys would be underscored, e.g. _conditions etc.
But otherwise I agree that we should not use that mixed format anymore.

Would it suffice to deprecate only this call style in 5.x?

I would be happy with just that.

It looks like this call style can be detected by having a mix of string and int keys which should be simple enough to detect.

Not always, I think you can have this form too:

$usersQuery->contain([
    'Articles' => [
        'conditions' => [.....],   // option as key
        'Comments' => [..options for this inner model...]  // model alias as key
    ],
]);

I think this also sets us up better for contain options to use a builder pattern more easily in the future.

Yes, adding builders in future would be nice. I believe that will also make it easier for AI agents to write CakePHP code.

If aliases were always UpperCaseCamel (upper case first letter), there would also be no collisions.

Yes when naming the aliases as per convention the chances of collision are negligible but it's also about readability. I personally find that this mix of options and alias as same level adds unnecessary cognitive load.

So what course do we go?
What exactly do we deprecated, what do we propose people use?

Is the proposal to check if the isn't isn't one of the allowed option keys and if so suggest using associated ?

My main concern would be that this verbose form is super hard to type for default case when u just want list them nested.
I hope we find another agreement on shortcutting.

Is is annoying. I'm not sure how to improve it with fluid getters other than with a closure - but we already do that to modify the query.

The few times you need to set options, I would in this syntax prefer underscores. We could throw deprecations in 5.x.