Skip to content
Fera Docs

Search is only available in production builds. Try building and previewing the site to test it out locally.

The project's own renames never reached the design docs: nylon-ring vs fload, thefera vs the-fera, and a dangling LATTICE.md

Источник: dev/fera-research/docs/oc1/012-naming-renames-never-propagated.md (read-only; сгенерировано scripts/sync-docs.mjs)

The project’s own renames never reached the design docs: nylon-ring vs fload, thefera vs the-fera, and a dangling LATTICE.md

Section titled “The project’s own renames never reached the design docs: nylon-ring vs fload, thefera vs the-fera, and a dangling LATTICE.md”
  • kind: problem
  • area: modules
  • evidence:
    • The rename decision — NAMING-UX.md:42: “fload — the nylon-ring fork (module runtime, OQ-024 fork intent)”; NAMING-UX.md:46 lists fload as a repo name; OQ.md:528 gets the split right: “fload — nylon-ring fork (module runtime; OQ-024 fork intent)”.
    • The rename never happened in the corpus. nylon-ring appears 20+ times across normative text: ADR.md:19, :49, :135, :240; TECHSPEC.md:31-39, :187, :207, :267, :301, :461; QA.md:17, :130; RFC.md:65, :157; OQ.md:17, :746, :834, :874; FUTURE-CHECKS.md:116. fload appears in exactly two places, both of which are the naming records themselves (NAMING-UX.md:42,46 and OQ.md:528).
    • The rule that would prevent it is scoped but never defined. NAMING-UX.md:53-55: “short, poetic-sounding names in the Rust-ecosystem tradition (serde, tokio, hyper) preferred over literal/descriptive (rustcalltg-style)” — qualified “for anything intended to have its own identity”. That qualifier is never defined, so the same rule both mandates (mikkaj for the milli fork, grmrs for grammers) and exempts (intra-repo module names like storage-sanakirja) names.
    • Corpus violates it in both directions:
      • mikkaj (milli fork, NAMING-UX.md:40-41,47) vs corpus “milli” at ADR.md:366, TECHSPEC.md:23, :32, :145, and the directory /search-milli/ (TECHSPEC.md:32).
      • grmrs (grammers fork, NAMING-UX.md:44-45,47) vs grammers-client at TECHSPEC.md:50, TECHSPEC.md:20 — a maximally descriptive name, exactly what R2 disfavours.
      • A rejected name is one character away from a live one: rejected srch-milli (NAMING-UX.md:41) vs live /search-milli/ (TECHSPEC.md:32). Nothing forbids rejected names from reappearing.
    • Org name conflict. NAMING-UX.md:46 “Repo names in the thefera org”; OQ.md:523 “Org name: thefera” — vs README.md:4, :9, :36 which use the-fera (github.com/the-fera/fera, https://github.com/the-fera). Two spellings; the hyphenated one is in every working URL.
    • Dangling file reference. NAMING-UX.md:31 “spec draft lives at context/LATTICE.md” and OQ.md:437 “spec draft exists — context/LATTICE.md” — context/ contains 15 files and LATTICE.md does not exist. README.md:35-37 says the opposite (“Lattice’s container spec lives in its own repo … a standalone project”).
    • Same rule violation, structural variant: ADR.md:700 names the optional decoder ffmpeg-decoder; TECHSPEC.md:38 names the directory /media-decoder-ffmpeg/; TECHSPEC.md:186 calls it “an ffmpeg-next-backed decoder” — three names, and none matches the media-decoder-* sibling pattern at TECHSPEC.md:37.
    • NAMING-UX is a decision log, not a normative spec — so its rules do not bind. No ADR cites it (the single inbound hit, FUTURE-CHECKS.md:4, is a disclaimer). Every inbound reference points at a log entry (OQ.md:342, :917, :934), never at a rule. Its own status language is hedged: NAMING-UX.md:105 “direction chosen, no concrete artwork yet”; :132-141 “Still open”; :181-183 §3 is “Loose principles … that should inform UX decisions later”.
    • NAMING-UX.md:134 and :163-165 still describe “the three-axis modularity (Engine/Style/Feature)” and a “Style-module-per-OS concept (ADR-009)” — both superseded by ADR.md:227-231 / :282-285 (four axes; Style is data). See my finding 018.
    • Unsourced hard numbers presented as fact: NAMING-UX.md:16-22 (“52M+ downloads”) and :97-98 (“~75K YT / ~475K TT”) — no source, date or method.
  • severity: mid

Суть / Substance

Section titled “Суть / Substance”

NAMING-UX.md is where the project records what things are called, and the corpus has diverged from it everywhere — but because the doc has no normative force (nothing cites it as a rule), the divergence has never surfaced as an error. The concrete consequences are practical, not aesthetic:

  1. An implementer cannot tell which name to use. nylon-ring appears in every layout section, every ADR and every QA gate; fload appears only in the naming record. Any agent picking up “implement the module boundary” will use nylon-ring — the doc will tell them they got the name wrong, and they will have no way to know which artifact the name refers to (crate? repo? upstream project?). NAMING-UX.md:42 names the same thing two ways on one line.
  2. Fork repo names are already decided and already wrong. grmrs/mikkaj/fload are named in OQ.md:523-531 as the repos to create; TECHSPEC.md:20-32 writes /protocol/ — grammers wrapper and /search-milli/. My finding 011 shows the protocol fork is a mandated decision whose crate path is still upstream’s name — so the rename and the decision are un-applied together.
  3. A rejected name is live. srch-milli rejected, /search-milli/ shipped in the layout. With no rule against reuse, this recurs.
  4. The org name is ambiguous in URLs. thefera (2 docs) vs the-fera (README, i.e. the actual GitHub URLs). Anything scripted against the wrong one 404s.
  5. context/LATTICE.md does not exist but two docs point at it, while README.md:35-37 says the spec lives in another repo. Anyone implementing OQ-013’s container format follows a dead path.

The meta-defect: README.md:41-45 defines a resolution protocol for decisions (OQ → ADR, with a marker) but there is no equivalent for names, so renames never propagate. That is why the highest-visibility rename in the project (the module runtime) is invisible in 20+ places.

Варианты решения (tradeoffs)

Section titled “Варианты решения (tradeoffs)”
  • (A) Decide per-name: canonical name + layer, then apply corpus-wide. e.g. “fload = repo, nylon-ring = crate name, upstream project = nylon-ring; docs use the crate name; OQ.md:528’s split is canonical.” Cheap, mechanical, no new concepts.
  • (B) Rename the crate to match the repo (fload everywhere). Maximally consistent with R2; costs a rename across every ADR and QA gate for no functional gain, and “fload” is obscure outside the project.
  • (C) Retire NAMING-UX’s rule status — declare it a historical log and let ADR.md own all names. Cleanest logically, but loses the rules (R2/R3/R4 are genuinely useful) and leaves the fork names unowned.
  • (D) Leave it. Reject: 20+ sites of drift and a dead file reference.

Предлагаемое решение

Section titled “Предлагаемое решение”

(A), plus a mechanical guard.

  1. Publish a name table (in NAMING-UX.md §1, which already is the place names are recorded) with one row per thing and columns for concept / repo / crate / dir, so fload | nylon-ring | … is recorded as a deliberate mapping rather than a contradiction. Add explicit “rejected names — do not reuse” rows (srch-milli, nya-runtime).
  2. Apply the table to the 20+ nylon-ring sites (or, if the author prefers, rename the crate once in a single ADR addendum and let a follow-up sweep do the corpus). Same for /search-milli/ vs mikkaj and /protocol/ — grammers wrapper vs grmrs (see finding 011).
  3. Fix the org name — one spelling everywhere; the-fera (it is what the URLs use).
  4. Fix or delete the context/LATTICE.md references (NAMING-UX.md:31, OQ.md:437) — point at the lattice repo per README.md:35-37.
  5. Add the two missing rules so future renames propagate: (a) “ADR addenda supersede downstream sections of RFC/TECHSPEC/QA” (this is the class behind findings 001, 002, 008, 018 — the same fix keeps recurring); (b) “R2 applies to repos/products with their own identity, not to intra-repo module directory names” — which stops storage-sanakirja/calls-tgcalls from reading as violations.
  6. Cheap mechanical guard: a script that greps every name in the published table and fails on undocumented variants, plus a link-check for context/*.md intra-repo references (catches LATTICE.md).
  7. Low priority but cheap: source or date-stamp the 52M+ downloads / ~75K YT / ~475K TT figures (NAMING-UX.md:16-22, :97-98), and fix “power-consumment” (:98).