Status: accepted, 2026-09-23 (OPIK-8485)
All logic for one entity or write operation lives in that entity’s or operation’s namespace. A package root holds only protocols, base classes, registries and generic mechanisms. That includes tables: per-entity OQL fields, sort fields, URI patterns and link builders belong with the entity, reached through a hook on its handler.
If a change for one entity has to touch the root, the framework is missing a hook. Add the hook, and say so in the PR.
A root module that knows every entity changes in every PR, however narrow the PR is. A root that only dispatches rarely changes, so it is easy to extend and to review. Raised in review of #186 and #187.
tests/read_list/test_modular.py: no entity module at the root, no
entity imports another, the registry is only a table, dispatchers name no
entity, and no new entity name at the root.tests/writes/test_dispatch_stays_generic.py: the dispatcher names no
operation, hooks come from writes/operations/, and no new operation name
at the root.tests/repo/ratchets.json. The lists only shrink. A change that needs a root table adds the missing hook
(filter and sort fields, schema notes, URI patterns, write models) instead.entities/, one namespace each (#187).