One definition per concept

§1 — Why here, and why now

The imas-codex consistency census of 2026-10-12 (imas-codex:sn-catalog-consistency-census) measured 72 accepted entries re-deriving the flux-surface average, in five notations and with one wrong. 24 boundary entries call the plasma boundary the separatrix, and the WEST batch opens its documentation in four styles. The consumer plan imas-codex:sn-house-style authors a single house style to fix this. On 2026-10-12 the lead ruled that the house style lives in ISN now, released before the WEST re-cut, rather than in imas-codex first. A definition belongs with the grammar that names the thing defined, and every consumer of the standard should see it, not only the generator.

Existing guidance is the base, not a competitor. docs/guidelines.md states naming rules and the flux-surface-average tag. The shipped symbol definition policy requires every symbol to be defined by identity and name link. The locus registry already carries a definition per locus. The new layer adds what none of them hold: one canonical equation per concept, one symbol per quantity, and one opening template per name pattern.

Four existing owners are extended or referenced rather than restated. Per-token definitions live on the vocabulary entries (LocusEntry.definition, PhysicalBaseDef.definition, GeometryCarrierDef.definition in imas_standard_names/grammar/vocab_loaders.py). Alternate spellings live on their aliases and abbreviations. The writer's rubric (section order, the generic sign-convention form, equation and symbol rules) is entry_schema.fields.documentation.guidance in imas_standard_names/grammar/specification.yml, generated into field_schemas.py. The governed-term accessor is terms.py. imas-codex's cluster vocabulary (imas_codex/definitions/clusters/concepts.yaml) carries symbols for cluster labels; it is a consumer of this layer, recorded there rather than changed here.

§2 — The registry and its loader

Three files under imas_standard_names/grammar/vocabularies/conventions/:

• concepts.yml — one entry per shared concept, keyed by the operator, locus, coordinate or base token that carries it. Each entry holds a canonical phrase, exactly one canonical LaTeX equation, its symbol table, forbidden variants as patterns, and whether a name using it restates the equation or only names the concept. It carries a one-sentence definition only for a token whose vocabulary entry has none (operators have none today). Where the token's entry already defines it, the accessor returns that definition, and a lead ruling that changes it is made on the token's own entry, so there is one definition per token.
• notation.yml — one symbol per quantity or coordinate, keyed by base, subject, component or coordinate token, with its forbidden spellings. The loader refuses a forbidden spelling that equals one of the same token's registered aliases or abbreviations, so the two owners cannot disagree.
• templates.yml — one description opening and one documentation opening per name pattern. A pattern key is written in grammar segments (a base and the segment kinds the name fills), so it is selected from the parse. The section order and the generic sign-convention form stay in specification.yml, and a template references them rather than restating them. Whether an entry carries a sign-convention paragraph depends on its COCOS transformation type, an entry field the parse does not yield, so that rule is not in the registry: the consumer decides it where the entry is known (imas-codex's documentation gates). Per-pattern openings are not added to specification.yml, whose guidance is the generic rubric every entry's schema carries.

The models and loaders go into imas_standard_names/grammar/vocab_loaders.py beside the existing ones, reusing _load_yaml and the registries it already loads. For concepts.yml and notation.yml, which are keyed by tokens, the loader refuses any key that is not a real token in the current vocabularies, so the registry cannot drift from the grammar. templates.yml is keyed by patterns, so its rule is that every token and segment kind a pattern names exists in the current grammar. The public accessor goes into imas_standard_names/grammar/terms.py beside fetch_standard_terms: it takes a parsed name and returns exactly the entries that apply to it. No new loader module is added. Surface: one accessor and one refusal family (an unknown token key, or a forbidden spelling that equals a registered alias) are added. Nothing is retired, because no per-token equation, per-quantity symbol or per-pattern opening exists to merge with.

Done when: the loader validates all three files and refuses one deliberately malformed entry per file, plus one entry keyed by a token that does not exist, each failing by name. For flux_surface_averaged_argon_density_at_plasma_boundary, the accessor returns the flux-surface-average concept, the plasma-boundary entry, the density notation and the species-density template, and nothing else.

§3 — The entries the WEST batch needs

Content is authored by the coordinator under imas-codex:sn-house-style §3 and lands here. The lead's rulings of 2026-10-12 fix three entries before any other is written:

• The flux-surface average is defined by the surface form, \langle f\rangle = \oint f\,dS/|\nabla\psi| \,/\, \oint dS/|\nabla\psi|. The line form may be named as equivalent in prose and is never written as a second equation.
• The plasma boundary is "the last closed flux surface". The separatrix is named only where a quantity is defined for a diverted configuration.
• Every documentation entry opens with a defining noun phrase, the same shape as its description.

Done when: every concept, symbol and pattern used by the 220 names of the frozen WEST roster has an entry. The worklist is produced by running the §2 accessor over that roster and listing the tokens it finds with no entry, so the list is measured, not guessed. The run is shown able to report a gap: with one entry removed from a scratch copy of the registry, it lists that token as missing. The lead has read concepts.yml. This section is the landing of imas-codex:sn-house-style §3, where the coordinator authors the entries; it closes when that section does, and is not built separately.

§4 — Released before the WEST re-cut

imas-codex already consumes this repository as an editable path source, so the registry is usable there the moment it lands on main. The release is what makes it part of the published standard. Cut it with standard-names release before the WEST candidate is cut. In imas-codex, both imas-standard-names pin occurrences move together, and the graph's grammar snapshot is verified to carry the release rather than assumed, since a scoped run does not resync it.

Done when: the tag is published and installable from the package index. Both imas-codex pin lines name it. A read of the graph's grammar snapshot reports the released version.

§5 — Population, zone and aggregation tokens carry definitions

Three near-duplicate rulings carry a separating sentence (§7) that must render only on the names it describes. The registry cannot do that today. _vocabulary_definitions (imas_standard_names/grammar/vocab_loaders.py ~715) returns definitions only for locus, physical-base and geometry-carrier tokens. The population (populations.yml), zone (zones.yml) and aggregation (aggregations.yml) vocabularies are plain token lists, with any meaning in comments. The lead ruled on 2026-10-15 that the registry gains both mechanisms: definitions on these tokens (this section), and token conditions on templates (§6).

Each token in those three vocabularies may carry a definition, held in _vocabulary_definitions. Holding it is not enough. select_conventions (grammar/terms.py ~280) emits an applied definition only for a token keyed in concepts.yml, and uses the vocabulary text merely as fallback for such a key. So it must also emit an applied definition for a population, zone or aggregation token that carries one. AppliedConcept (terms.py ~116) requires phrase, equation and restates_equation, which a token definition does not have. Either make those fields optional for a definition-only entry, or add a sibling definition-only shape that renders beside concepts. Never invent a phrase or an equation to fill a required field. Say which you chose in the fragment. Change the files from lists to entries in the shape the locus registry and physical bases already use, so a token without a definition still loads. load_populations and load_aggregations return exactly the token sets they return today. load_zones returns exactly the same ordered tuple, because its order is the canonical intra-order rendering and validation rely on (vocab_loaders.py ~380). No consumer changes. Move the meanings now held in comments into definitions where a comment states one. Do not invent definitions for tokens whose meaning no comment records.

Done when:

• a test shows load_populations and load_aggregations return the same token sets at base and at head, and load_zones the same ordered tuple;
• _vocabulary_definitions returns a definition for a population, a zone and an aggregation token, and that definition appears in a rendered name carrying the token;
• a token without a definition loads and contributes nothing;
• each test fails with its mechanism removed, recorded with EXIT=;
• the grammar, vocabulary and template tests pass at head, judged by delta against base.

§6 — A template may require or exclude tokens

select_conventions (imas_standard_names/grammar/terms.py ~297) selects a template from conventions/templates.yml by the name's base and the segment kinds present, through a subset test. So a template reaches every name of its pattern. A sentence about cold neutrals reaches electron_temperature, and a sentence about the unqualified triangularity reaches upper_triangularity_of_plasma_boundary.

A template entry may carry optional conditions:

• required tokens per segment kind, for example population: [cold, hot] or aggregation: [total];
• excluded segment kinds, for example a template for the unqualified quantity that excludes zone.

select_conventions applies the conditions after its subset test. An entry with no conditions selects exactly as it does today. A template entry may also carry an optional note: one sentence rendered after the documentation opening of every name that selects the entry. TemplateEntry (vocab_loaders.py ~662) has no field for such a sentence today, because its description and documentation are the pattern's openings. §7 places the separating sentences in notes. No precedence among templates exists today: they are an unordered list returned in file order (vocab_loaders.py ~678). Define how a conditioned entry and an unconditioned sibling combine or take precedence when both match, state the rule in the fragment, and test it.

Done when:

• tests show a required-token condition admits only names carrying the token;
• an excluded segment kind admits only names without it;
• a note renders after the documentation opening on every name that selects its entry and on no other name;
• every existing template selects as before, shown over the names the existing template tests render;
• a test fixes the precedence rule: when a conditioned entry and an unconditioned sibling both match one name, the result is exactly what the stated rule says, and the test fails when the rule is reversed;
• each test fails with its mechanism removed, recorded with EXIT=;
• the grammar and template tests pass at head, judged by delta against base.

§7 — The sentences that keep near-duplicates apart

The coordinator ruled every near-duplicate overlap that touches the WEST roster as distinct (imas-codex docs/evidence/fragments/sn-catalog-grouping/scg-near-duplicate-rulings.json, 2026-10-13). Three of those rulings carry a template_sentence that separates two names which otherwise read alike. Use each sentence verbatim from that field:

• cold or hot neutral temperature against neutral temperature;
• unqualified triangularity against upper and lower triangularity;
• total electron density against thermal and fast electron density.

After §5 and §6, place each sentence with the mechanisms those sections built: token definitions and conditioned template notes. The placement is the worker's to choose, and the done-when below is the contract. Two constraints are known. A token definition carries only what the token means in every name it fills, so a neutral-temperature sentence cannot go on cold, which also fills cold_electron_density. And a name can fill several segment kinds at once, as total_thermal_electron_density does, so a sentence placed in more than one entry must still render once per name. Say in the fragment where each sentence went and why.

Done when: a test renders the documentation of every name in each family that the graph-free registry can name:

• temperature: electron_temperature, ion_temperature, neutral_temperature, and cold and hot neutral temperature;
• density: electron_density and each population and aggregation form of it the registry composes;
• triangularity: triangularity_of_plasma_boundary and its upper and lower forms.

The test asserts that each sentence appears exactly once on every name it describes, and on no other name in any of the three families, including names that fill more than one segment kind. It fails with any sentence removed, and fails when any sentence is duplicated so that some described name renders it twice. Both are recorded with EXIT=. For each sentence, a further control moves it to a placement that reaches a name it does not describe, and the test must then fail. Where no such placement exists for a sentence, say so in the fragment. The registry and template tests pass at head, judged by delta against base.

Render through one owner, not a test helper. Nothing in production yet reads AppliedTemplate.note. The only renderer is imas-codex, which inserts template.documentation alone (imas_codex/standard_names/workers.py ~9661 and imas_codex/standard_names/docs_gates.py ~983). Add one accessor beside select_conventions in imas_standard_names/grammar/terms.py. It returns, in order, the sentences that a name's selected templates contribute: each template's opening, then its note. The test asserts through that accessor. Switching the imas-codex writer and gate to it is a separate node in that repository. In tests/grammar/test_template_conditions.py, rename _legacy_selection and its docstring by what the oracle computes, a selection by the subset test alone with no conditions.

§8 — A base for a distance from the separatrix

A harmonize run in imas-codex (2026-10-18) exposed two registry defects through one WEST name, gap_at_outboard_midplane, and the lead ruled on both the same day. This section is the first; §9 is the second.

Three DD quantities are a measurement position's radial distance from the separatrix, mapped along flux surfaces to the outboard midplane, positive in the scrape-off layer: langmuir_probes/embedded/distance_separatrix_midplane, langmuir_probes/reciprocating/plunge/distance_separatrix_midplane and thomson_scattering/channel/distance_separatrix_midplane. The grammar cannot say "distance from the separatrix". Relational spellings (distance_from_separatrix_…) fail as unknown bases, and radial_separatrix_distance_at_outboard_midplane parses today only as a distance in the separatrix zone (zone=[separatrix], base distance), which says where the quantity sits, not what it is measured from. Add one physical base, separatrix_distance, beside decay_length and connection_length: the distance of a position from the magnetic separatrix, positive outside it. That spelling, an existing identity in imas-codex, then decomposes as what it means and can be revived there.

Done when: radial_separatrix_distance_at_outboard_midplane parses and round-trips with component radial, base separatrix_distance and position outboard_midplane, and a test fails with the base removed, recorded with EXIT=. Every other name in the grammar's fixtures keeps its parse; names that use separatrix as a zone or locus are tested explicitly. The grammar suite passes at head, judged by delta against base. The release in §4 carries this section with §7 and §9.

§9 — Locus definitions say what the concept registry says, and name no DD field

locus_registry.yml defines outboard_midplane as "follows the DD midplane_identifier (default option 'dr_dz_zero_sep': the outboard separatrix point where dr/dz = 0)". The imas-codex documentation gate copies a locus definition into every documentation that uses the locus, and its reviewer docks the DD field and option names as implementation leakage. So every outboard-midplane name loses points whichever way it is written. The gate requires whatever text the registry carries, so rewriting the registry changes what it requires; the two are not in conflict.

The physics is already settled in this repository. Commit 0e43cde (2026-10-14) removed the dR/dZ = 0 definition, which is undefined for a limited plasma with no separatrix and disagreed with poloidal_angle. conventions/concepts.yml now defines the outboard midplane as Z = Z_mid, R > R_axis, with Z_mid the midplane height the data's midplane identifier selects, or the magnetic-axis height when none is given. The locus definitions never followed.

Rewrite each locus_registry.yml definition that names a DD field, an IDS path or an option value so it states, in words, what its concepts.yml entry states. Do not reinstate dR/dZ = 0 or any definition a recorded decision removed. At least these carry DD references: outboard_midplane, inboard_midplane, outboard_midplane_separatrix, pedestal, pedestal_maximum, pedestal_top, separatrix and an at-limiter entry. A locus with no concepts.yml entry keeps its physics and loses only the DD reference, unless that physics is the dR/dZ = 0 point. outboard_midplane_separatrix is such a locus: today it is "the outboard separatrix point where dr/dz = 0". Redefine it from the midplane, as the point where the separatrix crosses the midplane height on the low-field side (R > R_axis), with no dR/dZ wording. Where the default midplane height is the one the data selects at the separatrix's outermost point, that is the same point, so no consumer's meaning moves. The one locus whose meaning is that point, dr_dz_zero_point, keeps its geometric definition (the outboard separatrix point where dR/dZ = 0) and loses every DD reference it carries: its IDS path, the midplane_identifier field and the option value; it and outboard_midplane_separatrix coincide under the default midplane height, which the fragment notes as a question for a later vocabulary ruling, not this section. Keep each pointer from one locus to a sibling, such as outboard_midplane to outboard_midplane_separatrix for a value at the intersection. List every definition changed, before and after, in the fragment.

Done when: a test asserts that no locus definition names a DD field, an IDS path or an option value, and that none of the midplane loci (outboard_midplane, inboard_midplane, outboard_midplane_separatrix) contains dR/dZ or dr/dz in any case. It fails on the old outboard_midplane text and on the old outboard_midplane_separatrix text, recorded with EXIT=. A second test asserts that the outboard_midplane and inboard_midplane definitions state both parts of their concepts.yml relation: the midplane height, with its magnetic-axis default, and the side of the magnetic axis (R greater or less than R_axis). It fails on a planted definition that drops either part. The grammar suite passes at head, judged by delta against base.

§10 — One outboard-midplane definition

Lead ruling, 2026-10-22. The catalog records one definition of the midplane loci and uses it in every name. The outboard midplane is the point on the low-field side where the flux surface in question reaches its maximum major radius. On the separatrix, that is its outboard maximum-R point. The inboard midplane is the corresponding point of minimum major radius on the high-field side.

This replaces the per-dataset wording of 0e43cde, where the data's midplane identifier selected the height, falling back to the magnetic-axis height. That wording is not one definition. It made the generic locus sentence contradict any name whose quantity is taken at a stated height: gap_at_outboard_midplane scored 0.50 to 0.56 in three reviews, each reviewer reading two heights. The ruling keeps both concerns 0e43cde answered:

• A limited plasma has no separatrix, but its last closed flux surface has a maximum-R point, so the definition holds without one.
• poloidal_angle keeps its zero on the horizontal plane through the magnetic axis, as the catalog's COCOS 17 convention requires. Its definition gains one sentence: that zero coincides with the outboard midplane only for up-down-symmetric equilibria.

Change. In imas_standard_names/grammar/vocabularies/conventions/concepts.yml, change outboard_midplane and inboard_midplane, their equations and symbols, and the poloidal_angle sentence. In imas_standard_names/grammar/vocabularies/locus_registry.yml, change the definitions of outboard_midplane, inboard_midplane and outboard_midplane_separatrix, and any other entry that restates the midplane height. Every definition stays physics-only: no DD field, IDS path or option value. The existing physics-only test keeps passing. Its relation test, which encodes the old midplane-height-with-magnetic-axis-default relation, is updated to the new relation and fails on the old text.

Done when, all of these:

• the changed definitions are committed;
• a test asserts the maximum-R and minimum-R relations and fails on the 0e43cde wording;
• the tests/grammar/ gate shows no added failures against its base.

The release and the downstream pin bump are separate nodes under grammar-release-and-downstream-pin.

/reckon-build concept-and-notation-registry §2