ORA

Doctrine

ORA-2026-0044 — Names carry contracts; borrow idioms, not mechanism

ID
ORA-2026-0044
Date
2026-04-24
Status
ratified
Maturity
M2
Source
docs/entries/doctrines/ORA-2026-0044_naming-carries-contract.md

code-qualitynamingnaming-conventionidioms

ORA-2026-0044 — Names carry contracts; borrow idioms, not mechanism

Rule

When a directory, module, table, or type hosts a cohort of interchangeable things (same input, same output shape, scorable head-to-head), the collective noun the codebase uses for them MUST describe the SHAPE (what they all are), not the MECHANISM (how they happen to work).

Prefer names borrowed from established idioms across disciplines — ledger, docket, bench, harness, zoo, dossier, cascade, warden, sieve, oracle, manifest, beat, tile. These carry their contracts across files, PRs, tickets, seats, and future readers because the discipline they come from has already done the work of making them mean something specific.

Avoid suffix-mechanism names on cohort members: -runner, -assembler, -executor, -processor, -resolver, -helper. Avoid generic umbrellas that describe nothing: utils, common, core, configs, services.

Rationale

Naming is load-bearing in an LLM-mediated codebase at fleet scale. A well-chosen noun seeds coherence across dozens of seats who never speak to each other. The "classifier zoo" coinage (2026-04-24T03:04:52Z) propagated across 20+ fleet seats within hours and reshaped how the fleet reasoned about the cohort — from "ad-hoc files" to "benchmark cohort with head-to-head Brier scoring." The word did work that a long doc could not.

A 15-Opus scan of the camber codebase (ORA-2026-0045) found the same pattern repeating across 15 independent slices. Four nouns — ledger, docket, bench, dossier — converged as the right answer for unrelated cohorts:

  • belief_claims migration filename already says "ledger"; zero tables carry it
  • event_audit has 11 schema ALTERs fighting the "audit" framing — the shape is a docket
  • audit-attribution-reviewer + decision-auditor + review-swarm-runner + shadow-replay + audit-regress-runner are one grader bench
  • morning-manifest-{ui,site,d3} + morning-brief are one dossier with four lenses

The metaphors were already in the team's head — in commit messages, file headers, and migration filenames — but had not landed in the artifacts themselves. This doctrine closes that gap.

When the doctrine fires

Any of the following triggers a naming-review obligation:

1. Creating a new directory that hosts ≥3 files sharing a shape → name the directory for the shape, not for one member or for mechanism. 2. Creating a new table/type/view with invariants (append-only, idempotent, bitemporal, verdict-shaped, queue-shaped) → use the discipline's word for those invariants, not a generic _log, _audit, _config. 3. Noticing a -runner/-assembler/-executor suffix on a file that belongs to a cohort → flag it: the shape name is missing. 4. Noticing a shared prefix (gmail-, financial_, morning-) whose members have divergent shapes → split the prefix or add a shape token to each member. 5. Noticing a name that lies* about its contract (e.g., ai-router that routes nothing, triage-telemetry that does no triage) → this is HIGHER priority than simple missed-opportunity renames. Lying names mislead; missing names only slow down.

How to apply

  • New work: when you're about to create a cohort, pause and ask: "what discipline has done this work before?" (accounting → ledger; law → docket; ML → bench/zoo/oracle; theatre → ensemble; cartography → atlas; plumbing → cascade/sieve; ops → runbook/rite; music → beat). Pick the closest borrow.
  • Existing work: when renaming surfaces would carry contract (per the triggers above), file a SEPARATE ticket per rename. Do NOT bundle renames — ORA-2026-0021 applies. Each rename is a contract-change ticket with its own evidence + blast-radius analysis.
  • Anti-patterns first: if a lying name and a missing name compete for attention, do the lying one first.
  • Schemas are expensive: database renames carry migration cost; weigh blast radius against the naming win. For schemas, the doctrine prefers landing the shape name on the NEXT new object rather than a big-bang rename, unless the drift is diagnostic (e.g., repeated ALTERs fighting the name).

Enforcement

  • Code review of new directories/modules/tables: if the name is mechanism-suffixed or generic-umbrella-under-a-cohort, reviewer asks "what discipline has a word for this shape?" before approving.
  • When filing a rename ticket, include the idiom borrowed (which discipline, why it fits) and the contract it carries (one sentence a future reader would derive from the name alone).
  • New ORA patterns that name a recurring fleet behavior should themselves be tested against this doctrine — does the pattern's name carry its contract?

Exceptions

  • Product/brand nouns (camber, orbit, heartwood, ora, redline) are identity tokens, not contract-carriers. They don't follow this doctrine.
  • Vendor-mirror names (bt_* mirroring BuilderTrend, Google API mirrors) should stay honest to the external vocabulary.
  • Trivial utilities (a 20-line file called escape_sql_like.ts) don't need shape names — the function name IS the contract.

Operator note

Chad 2026-04-24T~18:45Z (on seeing the 15-Opus scan): "do it" — affirming the doctrine should be filed. The doctrine inherits its authority from that directive + the evidence-density of the scan itself (zero of 15 slices returned ZERO FINDINGS).

See also