refactor: resolve error number ownership architecture (realm vs app)

[pleberre]

Problem

There is an unresolved architectural decision about whether error numbers should belong to the realm or to the application level.

Locations

• src/main/java/io/err0/client/core/RealmPolicy.java:73

  // TODO: do error numbers belong to the realm or to the app

• src/main/java/io/err0/client/core/ProjectPolicy.java:173

  // TODO: do error numbers belong to realm or app

Context

This affects:

• API design and platform behavior
• How error codes are organized and managed
• Potential namespace collision handling
• Multi-project/multi-realm scenarios

Current Behavior

The code has TODOs but appears to work. Need to clarify the intended design.

Questions for Architecture Decision

1. Use Case: Can multiple apps share the same realm?
2. Scope: Should error numbers be globally unique across all realms, or unique per realm?
3. Isolation: Can different realms have overlapping error number ranges?
4. Migration: If we change this, what's the migration path?
5. API Impact: How does this affect the public API?

Recommended Approach

1. Document the current behavior
2. Define the intended behavior with examples
3. Update RealmPolicy.java and ProjectPolicy.java accordingly
4. Add tests validating the behavior
5. Update API documentation

Acceptance Criteria

• Architecture decision documented in docs/architecture/error-number-ownership.md
• TODOs removed from RealmPolicy.java and ProjectPolicy.java
• Code implements documented behavior
• Tests added validating the decision
• API documentation updated