Identity comparison alongside structural equals()

[btravers]

Problem

equals() compares the whole projected data structurally — acme.equals(renamed) is false after a rename (pinned in the specs). That is a coherent semantic, but it is not the one the library's target audience expects by default: in DDD, entity equality is conventionally identity equality — same id means same entity, whatever the attribute values. The current name is a semantic trap for exactly the people the package targets.

Proposal

Add one identity-based comparison next to the structural one, e.g.:

class Organization extends Entity("Organization")(
  { id: OrgId, slug: Slug, name: Name },
  { identity: ["id"] }, // or infer from a convention — to be designed
) {}

acme.sameIdentityAs(renamed); // true  — same id
acme.equals(renamed);         // false — attributes differ (unchanged)

Open questions:

• Declaration: an identity: [...] option vs a fixed id convention vs reusing immutable. An explicit option fits the existing generated/immutable style and keeps the package convention-free.
• Cross-class behaviour: presumably mirrors equals — two different Entity(...) classes are never the same identity.
• Naming: sameIdentityAs states the semantic; is is shorter but overloadable in the wrong way. One concept, one name.

Docs impact: the equality and identity distinction deserves a paragraph in the explanation pages either way — today equals's structural semantic is documented but never contrasted with the DDD convention.