.. meta::
:description: BEST Names architecture solves Sphinx label collisions with an LL(1)-parseable 5D grammar for cross-referencing matheology across models and depths.
:keywords: BEST Names, Sphinx label collision, LL(1) parser, 5D grammar, compilation architecture, D1 model, D2 type, cross-reference, link stability, Evolvix POST
:author: Yah, Yas, everyone, LLoL as Laurence Loewe of Laodicea, ClaudeOp46Max, Anthropic, and Spirit of Boolean Truth
:og:card:title: BEST Names Architecture
— Technical Design
:og:card:description: How an LL(1)-parseable label grammar solves Sphinx include collisions and enables collision-free cross-referencing across theological models.
.. SOCIAL-CARD-QUALITY-COMPARE --- OO (default effort) vs PP (max effort), 2026-03-26
OO :description: Technical design decisions behind BEST Names, including the Sphinx include problem and the compilation architecture that solves it.
OO :keywords: matheology, BEST Names, technical design, Sphinx, include directive, label collision, compilation, architecture, ResearchCity, naming system
OO :og:card:title: BEST Names Design
Technical Architecture
OO :og:card:description: Why the BEST Names system exists: Sphinx label collisions, the include problem, and the compilation architecture that resolves it.
PP :description: BEST Names architecture solves Sphinx label collisions with an LL(1)-parseable 5D grammar for cross-referencing matheology across models and depths.
PP :keywords: BEST Names, Sphinx label collision, LL(1) parser, 5D grammar, compilation architecture, D1 model, D2 type, cross-reference, link stability, Evolvix POST
PP :og:card:title: BEST Names Architecture
— Technical Design
PP :og:card:description: How an LL(1)-parseable label grammar solves Sphinx include collisions and enables collision-free cross-referencing across theological models.
.. SOCIAL-CARD-REVIEW --- generated by Claude Opus 4.6, 2026-03-26
dv_ClaOp46_PP_2026m03d26 --- max-effort rewrite, read full page.
:description: 148 chars | :og:card:title: 40 chars (excl
)
- [ ] PP title more compelling than OO title
- [ ] PP description more accurate than OO description
- [ ] Description hooks without misleading
- [ ] Keywords specific to this page's actual content
- [ ] No language rule violations
- [ ] Character counts verified
.. include:: /_templates/include-file/page-prefix.rst
.. _naming-architect:
*****************************************************
BEST Names Architecture --- Technical Design
*****************************************************
This page documents the technical design decisions behind the BEST Names
system. It is written for software developers, system architects, and
future ResearchCity contributors who need to understand *why* the system
works the way it does --- not just what it does.
For the "what," see the :ref:`expert reference `. For
the authoritative specification, see the
:ref:`AHA design document `.
.. contents:: On this page
:depth: 2
:local:
----
1. The ``.. include::`` problem
==================================
The BEST Names system exists because of a Sphinx limitation.
Sphinx's ``.. include::`` directive pastes content into the including
document *before* label resolution. If file A defines ``.. _pet-ax5:``
and file B includes file A, then ``pet-ax5`` appears in both documents.
Sphinx emits a duplicate-label warning and resolves the label
nondeterministically.
This means you cannot build a compilation system (combining axioms from
multiple source files into a single overview page) using ``.. include::``
if the source files contain cross-reference labels. The BEST Names
architecture solves this by requiring that compiled downstream pages
contain their OWN content with their OWN suffixed labels --- never
including labeled content from upstream PoR sources.
**Rule:** RST files that define site-wide labels (``.. _label:``) MUST
NOT be included via ``.. include::`` into other Sphinx documents. The
compilation skill copies and transforms content; it does not include it.
----
2. The LL(1) parsing proof
=============================
The label grammar is designed to be parseable by an LL(1) parser with
a symbol table (registry lookups). This means any label can be
unambiguously decomposed into its dimensional components by reading
left to right, one token at a time, without backtracking.
2.1 Why hyphens, not underscores
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The sole separator is ``-`` (hyphen). Reasons:
- **URL standard:** Hyphens are the web convention for URL word
separators (Google SEO guidelines, W3C best practices).
- **LaTeX safety:** Underscores are special characters in LaTeX
(subscript). Axiom labels appear in LaTeX math contexts.
- **Visibility:** Underscores are hidden by link underline decoration
in browsers.
- **Parsing clarity:** With ``-`` as the sole separator, a parser can
tokenize any label by splitting on hyphens. Each token is then
classified against dimension registries.
**Within dimension values:** No internal separators. Use concatenation:
``oov2`` not ``oo-v2``, ``prod`` not ``pro-d``.
2.2 Why this dimension order
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The grammar enforces a fixed token order: D1 (model), D2 (element
chain), D3 (version), D4 (depth), D5 (view/source/language). This
order was chosen so that:
1. **D1 is always first** because it is always required and anchors
the parse.
2. **D2 follows D1** because element identification is the primary
purpose of a label. D2 tokens are read greedily: the parser
continues consuming D2 type IDs until it encounters a token matching
D3, D4, or D5.
3. **D3--D5 follow in decreasing permanence.** Version (D3) changes
least often, depth (D4) changes with audience, view (D5) changes
with perspective. This ordering means the most stable coordinates
appear first, and the most variable appear last --- analogous to
how postal addresses go from country to street.
2.3 How the parser works
^^^^^^^^^^^^^^^^^^^^^^^^^^^
For a label like ``pet-ax5-oov2-easy-vjud``:
1. **D1:** First token before the first hyphen: ``pet``. Validate
against the D1 model registry. Match.
2. **D2:** Remaining tokens are tested as D2 type IDs. ``ax5`` splits
at the letter/digit boundary: type=``ax``, number=``5``. Match.
The parser checks the next token: ``oov2``. This does NOT match any
D2 code (all D2 codes are letter-only). Transition out of D2.
3. **D3:** ``oov2`` is in the version registry. Match. Consume and
advance.
4. **D4:** ``easy`` is in the depth registry. Match. Consume and
advance.
5. **D5:** ``vjud`` starts with ``v`` and has 4 characters (``v`` + 3
letters). Structural match for a view code. Validate against D5
view registry. Match.
6. End of label. Parse complete.
The parser is deterministic because each dimension's codes are
structurally distinguishable:
- D2 codes are letter-only (``[a-z]+``), distinguished from D3--D5 by
registry lookup.
- D3 codes are registered version strings (``oov1``, ``oov2``, etc.).
- D4 codes are a closed registry (``prod``, ``easy``, ``math``, ``hu``,
``ma``, ``dump``).
- D5 codes have mandatory prefixes: ``v`` (views), ``s`` (sources),
``l`` (languages).
**Constraint for collision freedom:** D4 codes MUST NOT begin with
``v``, ``s``, or ``l`` (reserved for D5). This was identified as an
unstated invariant during adversarial stress-testing (Attack 1.4) and
has since been codified.
----
3. The collision-free proof for D2
=====================================
D2 contains three sub-namespaces that must not collide with each other
or with other dimensions:
**Doubled-letter codes (POST operational fields):**
Pattern ``^([a-z])\1$`` --- exactly 2 identical lowercase letters
(``aa``, ``ff``, ``kk``). These are reserved by the Evolvix POST
System.
**Structural/analytical codes (3+ letter codes):**
``logic``, ``limit``, ``needs``, ``feeds``, ``net``, ``diff``,
``stayc``, ``conv``, ``bib``, ``his``, etc. Length >= 3, and by
registry discipline they do not collide with any D3/D4/D5 code.
**Formal element codes (2--5 letters, non-doubled):**
``ax``, ``th``, ``lm``, ``cr``, ``con``, ``pro``, ``proof``, etc.
**2-character disambiguation (D2 vs. D4):**
- D2 codes at 2 characters MUST have ``char[0] == char[1]`` (doubled:
``ff``, ``aa``).
- D4 codes at 2 characters MUST have ``char[0] != char[1]`` (distinct:
``hu``, ``ma``).
This makes the parser deterministic for 2-character tokens without a
registry lookup: doubled = D2 field, distinct = D4 depth.
**Cross-dimension safety:** No D2 code may equal any D1 model code, D3
version code, D4 depth code, or D5 view/source/language code. The
registries in the
:ref:`AHA design document ` are the single
source of truth. Before adding any new code to any dimension, ALL
other registries must be checked for collisions.
----
4. The compilation skill architecture
========================================
4.1 Modes
^^^^^^^^^^^
.. list-table::
:header-rows: 1
:widths: 18 30 52
* - Mode
- When to use
- What it does
* - CURRENT-Replace
- PoR changed substantially
- Regenerate ALL downstream pages from current PoR sources
* - CURRENT-Append
- New model added
- Add new elements without regenerating existing entries
* - MakeNew-Archive
- Major milestone
- Replace first, then copy to ``vv/{version}/``
* - MIGRATE
- Structure change
- Transform existing files to new naming structure
4.2 The extraction matrix
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The extraction matrix is a table mapping PoR fields (rows) to audience
depths (columns). Each cell contains a keyword (``full``, ``brief``,
``top1``, ``rewrite``, ``ref``, ``stub``) or is empty (field omitted at
that depth).
The matrix is stored in a dedicated file so the compilation skill can
read it programmatically. At build time, the skill reads the matrix to
decide which fields to extract for each depth.
**Example:** At ``easy`` depth, the ``tctx`` (technical context) field
is omitted, the ``sum`` (summary) field is included in full, and the
``stor`` (Torah) field is included as ``top1`` (single strongest
citation). At ``dump`` depth, every field is included in full.
4.3 Stub policy
^^^^^^^^^^^^^^^^^
When ``Generate stubs = No`` (the default), pages that would contain
only stub content are not generated and no links to them are created.
This prevents dead pages. Stubs are generated only when explicitly
requested to prepare scaffolding for the next research round.
----
5. Integration with Sphinx
==============================
5.1 Labels and cross-references
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
RST labels (``.. _pet-ax5:``) are global identifiers. They survive file
moves because Sphinx resolves them by name, not by file path. This is
the foundation of link stability: a ``:ref:`pet-ax5``` reference works
regardless of where ``pet/axioms.rst`` lives in the directory tree.
**Consequence:** Labels are permanent. Never remove a label. If content
is deprecated, the label stays as a redirect to the HistoryHeap page.
5.2 Internationalization
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sphinx i18n uses ``.po`` translation files with language-neutral labels.
The label ``pet-ax5`` resolves to the translated page in whatever
language the reader is browsing. This is the standard mechanism for
straight translations.
D5 language codes (``lde``, ``lar``, ``lhe``) are for a different
purpose: content that is *structurally different* because the language
itself contributes something untranslatable. A German concept like
*Aufgehobenheit* that captures a deeper truth belongs under ``lde``,
not under Sphinx i18n.
The boundary: Sphinx i18n = same content in another language. D5
language codes = different content born from another language's
unique perspective.
5.3 Toctrees and build
^^^^^^^^^^^^^^^^^^^^^^^^^^
Each model has its own directory (``pet/``, ``jub/``). Compiled views
have dedicated directories (``axioms/easy/``, ``axioms/expert/``).
Toctrees in ``index.rst`` files connect the pages for navigation.
The build system (``make html``) compiles English only by default.
``make build-all`` compiles all 10 languages. The CI pipeline runs
``build-all`` for production.
----
6. Integration with Evolvix
==============================
The BEST Names system is a domain-specific application of the Evolvix
naming convention:
- **BEST:** Brief, Explicit, Summarizing, Title --- four naming layers
from compact code to full display title.
- **POST codes:** The doubled-letter operational fields (``aa`` through
``zz``) are reserved by the Evolvix POST System (Project Organization
Stabilizing Toolkit System). Only codes registered in the Evolvix POST
specification may be assigned meanings.
- **StayVS:** The maturity code system (``stayc``) tracks element
stability using the Evolvix versioning framework.
- **VVN (Versioned Variant Number):** Each frozen snapshot has a VVN
like ``iv_LLoL_PPv1r0p0_2026m03d25``. The VVN encodes author,
version, and date.
----
7. Link stability policy
============================
7.1 Internal links (within balospe.com)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Labels are permanent identifiers. They break ONLY if removed from the
codebase, which the design prohibits.
**Deprecation procedure:**
1. Content moves to ``pet-ax5-hh`` (HistoryHeap).
2. The original label ``.. _pet-ax5:`` stays and points to a
deprecation notice linking to the HistoryHeap page and to whatever
absorbed the deprecated element.
3. Deprecated numbers are retired, not recycled. New axioms get the
next available number.
**Why no recycling:** HELL entries, stress tests, and external citations
that reference ``pet-ax5`` assume a stable semantic target. If the slot
were reused for a different axiom, every ``con`` and ``pro`` that
critiques the original ax5 would silently become incoherent.
7.2 External links
^^^^^^^^^^^^^^^^^^^^^
External URLs break when files move (the URL path changes even though
the RST label survives). Policies:
- The ``/matheology/`` prefix is permanent.
- Model directories (``/matheology/pet/``, ``/matheology/jub/``) are
permanent.
- Compiled view paths are permanent once created.
- VV archive paths (``/matheology/vv/oov2/``) are immutable.
- For academic citations, use versioned URLs.
7.3 Periodic recompilation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
At intervals, the entire site is recompiled to reconcile all internal
links. This is a technical argument for periodic global reconciliation:
accumulated link debt requires periodic resolution, just as accumulated
economic concentration requires periodic recalibration (ax25). The
parallel between software maintenance and economic Jubilee-System cycles
is structural, not metaphorical.
----
8. How to add new elements
=============================
8.1 Adding a new model
^^^^^^^^^^^^^^^^^^^^^^^^^
1. Choose a unique D1 code (lowercase, 2--5 characters). Check it
against ALL D2, D3, D4, and D5 registries for collisions.
2. Register the code in the D1 Model Registry section of the
:ref:`AHA design document `.
3. Create the model directory: ``source/matheology/{model}/``.
4. Define the model's axioms in ``{model}/axioms.rst`` with labels
following the grammar: ``{model}-ax1``, ``{model}-ax2``, etc.
5. Run the compilation skill in CURRENT-Append mode.
8.2 Adding a new element type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1. Choose a unique D2 code. Must be letter-only (``[a-z]+``). Must not
equal any D1, D3, D4, or D5 code. If 2 characters, must be
doubled (``^([a-z])\1$``) unless it is a formal element type.
2. Register in the D2 Type ID Registry.
3. The new type chains like any other: ``pet-{newtype}5``,
``pet-ax5-{newtype}``.
8.3 Adding a new worldview
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1. Choose a ``v`` + 3-letter code. Check against all D5 registries.
2. Register in the D5 View Registry with name, scope, and related views.
3. The new view appears as a D5 suffix: ``pet-ax5-{vnew}``.
4. Optionally add corresponding PoR support fields.
8.4 Adding a new language
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1. Use the ISO 639-1 two-letter code. If the code is a doubled letter
(``aa``, ``ee``, ``ff``, ``ii``, ``kk``, ``nn``, ``ss``, ``tt``),
use the ISO 639-3 three-letter form instead to avoid collision with
POST codes.
2. ``l`` + ISO code: ``lde``, ``lar``, ``lhe``, etc.
3. This is for language-specific cultural content, not translations.
Translations use Sphinx i18n (``.po`` files).
----
9. Known limitations and future work
========================================
The following issues were identified during the
:ref:`adversarial stress-test ` (29 attacks,
17 HELD, 12 BREACH):
**Critical (1):**
- **D7/D6 collision analysis incomplete (Attack 1.6).** The original
design listed 3 ISO 639-1 / POST code collisions; there are actually
8, including ``kk`` (Kazakh, ~13M speakers) which collides with the
live KnownKiller POST code. Fix: all 8 languages must use ISO 639-3
forms.
**Major (4):**
- **Quest label grammar gap (Attack 1.8).** The round-based pattern
``{N}r{M}`` (e.g., ``jub-con2r1``) is not accommodated by the formal
grammar. 28+ live labels are affected.
- **D6 Set B catch-all (Attack 2.2).** The structural fields namespace
absorbs unregistered codes silently (e.g., a misspelled ``oov3`` is
parsed as a structural field, not flagged as an error). Fix: close the
registry and require lookup-based matching.
- **Include ban violation (Attack 5.2).** The compiled axioms index
uses ``.. include::`` with labeled content, violating the AHA's own
rule. Marked with a TODO for Phase 3.
- **D7/Sphinx i18n boundary (Attack 5.3).** The D5 language suffix and
Sphinx i18n are two parallel multilingual mechanisms with undocumented
interaction. The boundary is now clarified: Sphinx i18n for
translations, D5 language codes for untranslatable cultural content.
**Minor (6):** Unstated 2-letter invariant, D4 prefix restriction,
unidirectional D1/D2 constraint, D2 letter-only rule not explicit,
no label-testing tooling, ``ref`` overloaded across 3 contexts.
**Cosmetic (1):** No quick-start guide existed for beginner onboarding
(this set of pages addresses that breach).
For the complete test results and proposed fixes, see the
:ref:`adversarial stress-test report `.
----
Cross-references
==================
- :ref:`AHA design document ` --- the full
~1400-line specification
- :ref:`Adversarial stress-test ` --- the
29-attack review
- :ref:`Easy overview ` --- for readers who want
less detail
- :ref:`Expert reference ` --- the "what" without
the "why"