WIP: docs: add CONFIGURATION_RESOLUTION.md

Author: javier-godoy

CONFIGURATION_RESOLUTION.md

@@ -0,0 +1,96 @@
+# Configuration Resolution: Scope-First vs. Type-First
+
+## The Two Strategies
+
+Given `Foo extends Entity` with configurations at four points in the matrix:
+
+| | Instance | Global |
+|---|---|---|
+| **Foo** | I·Foo | G·Foo |
+| **Entity** | I·Entity | G·Entity |
+
+**Scope-first** exhausts all instance settings before looking at global ones:
+```
+I·Foo → I·Entity → G·Foo → G·Entity → Default
+```
+
+**Type-first** exhausts all Foo-specific settings before looking at Entity:
+```
+I·Foo → G·Foo → I·Entity → G·Entity → Default
+```
+
+Both agree on `I·Foo` being first and `G·Entity` being last. The dispute is the middle two.
+
+---
+
+## Where Scope-First Makes Sense
+
+**Setting: `textAlign` or `nullRepresentation`**
+
+A developer creates a reporting grid and writes:
+```java
+easyGrid.configuration.forType(Entity.class).setTextAlign(RIGHT);
+```
+The intent is *"every Entity-like column in this grid should be right-aligned."* Since `Foo IS-AN Entity`, Foo columns should also be right-aligned. Instance context wins: the developer explicitly opted every Entity column into this layout decision, and Foo, being substitutable for Entity, should inherit it.
+
+If type-first were applied, `G·Foo` would sit between `I·Foo` and `I·Entity`. An unrelated global renderer for Foo would silently block the instance-level alignment — which is the opposite of what the developer intended.
+
+---
+
+## Where Type-First Makes Sense
+
+**Setting: `rendererFactory`**
+
+Globally, `Foo` has a specialized renderer registered:
+```java
+GlobalEasyGridConfiguration.forType(Foo.class)
+    .setRendererFactory(FooRenderers.of(...));
+```
+Independently, an instance configures Entity columns with a generic formatter:
+```java
+easyGrid.configuration.forType(Entity.class).setFormatter(e -> e.getId().toString());
+```
+
+Under scope-first, `I·Entity` wins over `G·Foo`. The Foo-specific renderer — which encodes *what a Foo looks like*, arguably a type invariant — gets silently replaced by a generic Entity formatter that the developer may not have intended to apply to Foo.
+
+Type-first preserves the type contract: `G·Foo` sits above `I·Entity`, so Foo's rendering semantics are honoured even across scope boundaries.
+
+---
+
+## Liskov Substitution Principle
+
+LSP says: a `Foo` must be usable wherever an `Entity` is expected, without callers needing to know the difference.
+
+Applied to configuration, it has two implications that pull in opposite directions:
+
+**LSP supports scope-first for behavioural settings.** If you configure `Entity` at instance level — null representation, alignment, a locale-specific formatter — you are specifying how *this grid* handles all Entity values. A `Foo` substituting for `Entity` should satisfy those same observable postconditions. Refusing to inherit `I·Entity` because Foo has a `G·Foo` entry would mean the grid behaves differently for `Foo` vs `Entity` in ways the calling code did not anticipate.
+
+**LSP supports type-first for type-defining settings.** LSP also requires that subtypes honour their own invariants. If `Foo` has a type-level rendering contract — *this is how a Foo is displayed* — then substituting a generic `Entity` renderer for it violates the Foo invariant. The renderer is not just a postcondition on the grid; it is a property of `Foo` itself.
+
+The tension resolves to: **scope-first is correct as a default ordering**, but a setting that constitutes a type invariant (renderer factory, type-specific formatter) has stronger claims when registered at global-type specificity than a setting that constitutes an instance context decision (null representation, alignment).
+
+---
+
+## The Current Bug
+
+The current `InstanceEasyGridConfiguration` constructs the parent of any instance-level type config by calling `GlobalEasyGridConfiguration.resolve(type)` — jumping straight to global scope. For a `Foo` column, the effective chain is:
+
+```
+I·Foo → G·Foo → G·Entity → Default
+```
+
+`I·Entity` never appears. Instance-level Entity configuration is invisible to Foo columns within the same instance. This is wrong under either strategy.
+
+---
+
+## What Should Be Implemented
+
+The correct chain for scope-first (the generally right default) is:
+
+```
+I·Foo → I·Entity → I·Object → G·Foo → G·Entity → G·Object → Default
+```
+
+Concretely, when `InstanceEasyGridConfiguration` creates a config for `Foo`, its parent should be `I·Entity` (obtained by walking the instance's *own* class-map up the hierarchy), not `G·Foo` directly. Only after the instance hierarchy is exhausted should the chain cross into the global scope — at the matching type level.
+
+This means `EasyGridConfigurationClassMap.getOrCreate` needs to resolve parents by walking the *same map's* hierarchy first, and the cross-scope link (`resolve` jumping to global) should only be installed at the root of each instance's hierarchy chain, not at every node.