Repository Operations for Business Logic Entry Points

Goal

Repository interfaces must expose a standard set of operations with clear naming, explicit intent, predictable return types, and a strict error model.

Each operation must make its purpose unambiguous. A caller reading the repository interface must know immediately whether it is creating a new entity, updating an existing one, retrieving zero-or-one by identity or unique key, retrieving zero-or-many by criteria, performing a dynamic listing, counting matches, asking whether something exists, or deleting by identity.

The operation set is organized in two families:

• Entity fetch family (findBy*, findManyBy*, search) — returns domain entities.
• Aggregation family (countBy*, existsBy*, existManyBy*) — returns scalars (number, boolean) computed over the same predicates.

Two cross-cutting rules apply to every operation:

• Domain outcomes are valid return values, never errors. Not found, empty list, zero count, false existence — all are valid results. Errors are reserved for infrastructure failures.
• save is forbidden. Always distinguish between create and update explicitly so the caller's intent is never ambiguous.

What Counts as In Scope