Reject two model elements at the same position that share a name

[goloroden]

What is this feature about?

Element identity in ESDM is (containment position + name), and today uniqueness is only a per-kind, per-array modeling convention the schema does not enforce. The resolver indexes each kind into its own map, so two elements of different kinds that occupy the same containment position and share a name coexist silently: an aggregate and a dynamic-consistency-boundary both named loan in one bounded context, a bounded-context and a policy both named orders in one domain, or a command and an event both named place-order under one aggregate.

The reference notation (#8) turns this from a smell into a correctness requirement. A reference is a containment path that carries no kind (esdm:library/lending/loan), resolved by walking the hierarchy by name. For that walk to land on exactly one element, a name must identify exactly one element at each position, across all kinds that can sit there. The notation depends on this invariant, so a violation must be an error, not a warning.

What needs to be done to implement this feature?

• Add a lint rule that throws when two model elements occupy the same containment position and share a name, across kinds, at every position where more than one kind can sit:
  • under a domain (bounded-context, subdomain, policy, event-handler, process-manager, external-system, domain-story),
  • under a bounded context (aggregate, dynamic-consistency-boundary, read-model, query, entity, value-object, domain-service, actor, and free-standing events),
  • under an aggregate or dynamic-consistency-boundary (command, event, and - once Feature documents are keyed on domain and name, discarding their scope #38 is fixed - feature).
• Severity is Error: the reference notation relies on this uniqueness, so a clash is a defect, not a suggestion. Confirm the exact category and the diagnostic wording; both are user-facing and need sign-off.
• Place the rule in the rules package, not next to the resolver's existing duplicate-name check. Rules only run when the model is otherwise error-free, so a collision reported by the resolver would silence every other rule - on a large model the author would see that one error and nothing else.
• Cover the migration: models that lint clean today go red on upgrade. The diagnostic has to make the cause obvious on first read, and the release note has to say what changed and why.
• Cover the rule with tests for the throwing and the non-throwing cases.
• Document the rule and its rationale.

What else should we know?

• Related to Provide a stable reference notation for model elements so external documents can link to them #8 (reference notation): the notation addresses an element by its containment path with no kind, and relies on this rule to keep every reference unambiguous.
• Origin: raised while designing Provide a stable reference notation for model elements so external documents can link to them #8; elevated from a warning to an error once the notation was made kind-free and containment-first.
• Implementation trap: the composite keys invite a naive cross-kind comparison, but event keys carry four segments where the others carry three. A free-standing event keys as domain/bc//name, an entity at the same position as domain/bc/name - so a plain key comparison misses exactly the free-standing-event collisions listed above.
• Related to esdm view does not render entities and free-standing events #36: today a collision has no observable symptom, because path narrowing silently returns the first matching sibling. Once narrowing renders every match, a collision becomes directly visible instead of something the modeler has to infer. That shapes how the rule's documentation should describe detection: the symptom is not a missing document, it is a path that resolves to the wrong element.
• Related to Feature documents are keyed on domain and name, discarding their scope #38: features currently key on domain/name, which both hides collisions at the unit position and invents duplicates across units. The checklist entry above depends on that fix.

[zlatkoc]

Field data, in case it is useful: we are investigating ESDM, using a micro-lending domain as the worked example — a complete DCB-only model, ~175 documents, 4 bounded contexts — and we hit exactly this twice before any rule existed. Both cases sit at positions already on your checklist.

1. Under the domain: a subdomain and a process manager both named loan-servicing. esdm view silently resolved to one of them, so the process manager became unreachable through the census; esdm lint stayed clean throughout, since names were unique per kind. We renamed the subdomain (loan-administration) to get out of the way.

2. Under a bounded context: an entity and an actor both named applicant in the origination context. Same silent shadowing, same clean lint.

Two observations that may help the spec:

• Error severity is right, and our own counter-example argues for it. After those two collisions we adopted "entity and boundary names must differ" as a convention in the example model — and still knowingly kept one violation (an entity and a dynamic-consistency-boundary both named loan-application, a near-exact instance of the loan example in the issue), because nothing enforced the convention and the rename felt like churn at the time. That is exactly how a warning-level convention decays. An Error would have forced the rename we should have made, and we would take that trade gladly.

• Detection today is indirect, which is worth a line in the rule's documentation: the only symptom is a document you know exists not appearing in view. Existing models will meet this rule on upgrade, and "where did my document go" is how they will recognize what it caught.

Happy to implement the rule against the checklist — one file in rules/ plus tests, following the existing uniqueness-handling patterns — if an external code contribution is welcome here.

[goloroden]

Thanks - field data from a model that size is exactly what this issue was missing. I reproduced both cases against main, and the short version is: your first observation holds, the second one points at something real but the cause is different, and chasing it turned up two further defects that matter more than the collision itself.

Case 1 holds, with one correction. A subdomain and a process-manager sharing a name under one domain:

$ esdm lint
(no diagnostics)

$ esdm view
domain library  1 sub · 1 bc · 1 pm
├─ subdomain lending (core)  cataloging
├─ bounded-context cataloging  1 agg · 1 rm · 1 qry
└─ process-manager lending  at-most-once

$ esdm view library/lending
subdomain lending (core)  cataloging

Both documents appear in the full census, so nothing is swallowed there. What resolves silently is path narrowing: the walk takes the first sibling whose name matches and stops, and since children are appended kind by kind in a fixed order, the subdomain always wins. The symptom is therefore not "the document is gone" but "the path lands on something else".

Case 2 is not shadowing. Entities are never rendered by esdm view at all - a bounded context lists aggregates, DCBs, read models, queries, value objects, domain services and actors, but no entities. Your entity was missing with or without the same-named actor.

And that turned out to be the smaller half. Free-standing events are not rendered either. Events are only ever collected under aggregates; the DCB branch renders commands and nothing else. For a DCB-only model like yours that means esdm view shows no event at all - the events exist, they are referenced, they have no node. Here is a complete model with 20 documents, lint-clean, where exactly two are missing from the tree:

├─ bounded-context ordering  1 agg · 1 dcb · 1 rm · 1 qry · 1 vo · 1 ds · 1 act
│  ├─ aggregate order  1 cmd · 1 evt
│  │  ├─ command place  → placed
│  │  └─ event placed  ← place
│  ├─ dynamic-consistency-boundary capacity  1 cmd · 1 consult
│  │  └─ command reserve  → reserved          <- event "reserved" has no node
│  ├─ read-model orders  ← 1 evt
│  ├─ query list-orders  → orders
│  ├─ value-object money                      <- entity "line-item" has no node
│  ├─ domain-service pricing  1 fn
│  └─ actor customer (human)

Neither gap has a counter in the stats line either, which is the tell: they were forgotten, not curated away. The test that should have caught this is called "renders every catalog kind in an extended model" and asserts against a hand-maintained list that never mentioned an entity.

What we are changing. The rule we settled on is that an element sits at the position its own scope names, and relationships show up as annotations, never as placement. context-mapping is the documented exception - it has no scope by design. Three defects follow from that principle, all of them separate from this issue:

1. esdm view does not render entities and free-standing events #36 - the view gaps above, plus a catalog-driven test that iterates the schema's kind enum instead of a hand-written list, plus path narrowing rendering all matching nodes rather than the first.
2. Publisher resolution is rebuilt twice and wrong in both copies #37 - "which command publishes this event" is implemented three times - correctly in the resolver, and rebuilt twice, both times wrong. A DCB-bound command may publish an aggregate-owned event, which the resolver explicitly allows; the event-without-publisher rule then throws a false positive, and the view drops the ← annotation. Both rebuilds infer an event's position from the publishing command instead of reading its scope, which is the same mistake the principle above forbids.
3. Feature documents are keyed on domain and name, discarding their scope #38 - feature documents are keyed on domain/name, discarding the rest of their scope. Two features named happy-path about two different aggregates are rejected as duplicates today, even though their positions differ. That is the exact inverse of this issue: here, different kinds at the same position go unnoticed; there, the same kind at different positions gets merged.

On severity. The conclusion stands, though I would anchor it elsewhere. Your counter-example shows that a convention nobody enforces decays, which argues for enforcement as such rather than for Error over Warning - there was never a warning to ignore. The load-bearing argument is the one already in the issue: the notation is kind-free, so unambiguous resolution is a precondition. A violated precondition is a defect.

On documenting detection. Worth including, phrased differently. "A document you know exists does not appear in view" would send readers looking for the wrong thing, and defect 1 is why: at positions the view does not render, that symptom is permanent and has nothing to do with collisions. The accurate symptom is that esdm view <path> returns the wrong element - and once narrowing renders every match, the collision becomes visible directly instead of being inferred.

Your migration note is the most useful part for the checklist. Models that are green today go red on upgrade, and the checklist does not cover that. It goes in, together with the requirement that the diagnostic make the cause obvious on first read.

Two things for whoever implements the rule. It belongs in the rules package, not next to the resolver's existing duplicate-name check: rules only run when the model is otherwise error-free, so a collision reported by the resolver would silence every other rule - on a 175-document model you would see that one error and nothing else. And the composite keys tempt you into a naive cross-kind comparison, but event keys carry four segments where the others carry three: a free-standing event keys as domain/bc//name, an entity at the same position as domain/bc/name. That misses exactly the free-standing-event collisions on the checklist. The checklist also gains feature at the consistency-unit position once defect 3 is fixed, since a feature will then sit alongside commands and events.

On the offer. Yes, and there is something better suited than this issue: #36, the view completeness work. It is independent of #8, all the layout decisions are settled and written into the issue, and you have the one model shape that exercises it hardest. This issue stays queued behind #8 - the notation defines what a position is and which kinds are addressable, so the rule's surface can still move - and its category and diagnostic wording get decided here before implementation rather than in review.