Concept 6
Structural locality
A semantic area can span many files. Its semantic authority cannot.
In plain language
Structural locality is the idea that everything a feature owns — its state, its behaviour, its contracts, its tests — should be findable together, and that the single place deciding each of its rules should be obvious.
That is two claims, and separating them matters. A feature spread across thirteen files can still have exactly one place that decides whether an entry may be split. A feature packed into one 900-line file can easily have three.
Precisely
- A semantic area is a coherent feature or concern whose behaviour belongs together. It may span several files.
- A semantic authority is the single representation that decides a fact or rule. One per fact.
- A responsibility cluster is a human-scale grouping inside an area — transitions, validation, capabilities, projections. A cluster is not automatically an authority.
Status: this is an adopted contract, classified REQUIRED as a contract — and its predicted benefits are explicitly EXPERIMENTAL (CL-014). No controlled comparison of a monolithic against a decomposed treatment exists. Physical splitting can make navigation worse and can duplicate rules. This site does not claim otherwise.
What two independent builds actually did
Two agents, same requirements, no contact. Both produced 22 and 22Source files in each of two independent builds — an identical count, which is the least meaningful part of the comparison, and the comparison document says so explicitly.
Underneath that identical number, the file organisation genuinely differs. One build split its application layer into five files by semantic area; the other used two. One had three port files where the other had one. One threaded a pre-computed timestamp through function parameters; the other threaded a clock port object. Both achieved pure, testable domain functions by two different shapes of dependency injection.
Both builds also produced exactly 1,421 lines of test code, from six files and twelve files respectively. The comparison reports that as almost certainly coincidence and explicitly declines to use it as evidence for anything — which is the right call, and worth noticing as a piece of research conduct rather than a result.
Line count is a signal, not a truth
Ordo treats file size as a configurable review prompt rather than a rule (CL-017). The reason is precise: line count cannot detect duplicated authority, which is the thing it is usually used as a proxy for. A large file with one authority is fine. Three small files each deciding the same rule are not, and no line-count threshold will tell you which you have.
What an agent should do differently
- Before adding a rule, find where that rule is already decided. Add it there, or establish that no authority exists and create one.
- Do not split a file merely because it is long. Split it when it holds two things that change for different reasons.
- When a change requires touching several areas, say so. An unexpectedly wide change is information about the architecture, not just about the task.
How this is most often got wrong
Locality read as file-count minimalism. Consolidating everything into one module is not locality; it is the absence of structure, which happens to look tidy.
Treating a cluster as an authority. Splitting validation into its own file and then letting it decide a rule the transition also decides creates exactly the duplication the split was supposed to prevent.