Spec: Component Naming Forms

Defines the forms of reference every component of the Koder Stack must declare. Each component has up to 6 forms: a structural type, a prosaic display name, a contextual bare name, a canonical slug, a filesystem path, and an optional array of aliases for compact/colloquial reference.

Applies to every entry in meta/docs/stack/registries/stack-manifest.kmd.

1. The 6 forms

The "Where it's used" column is a summary. The exhaustive, normative surface→form mapping (which surface uses display vs bare vs slug) lives in §7.

2. Rules

R1 — type is required (enum)

type ∈ { product, service, engine, meta, umbrella }

• product — user-facing app/CLI (products/**)
• service — API-consumed backend (services/**)
• engine — embeddable runtime/lib (engines/**)
• meta — reference material, not deployable (meta/**)
• umbrella — Sector grouping 2+ deployable components (e.g. infra/data/kdb grouping kdb-kv/kdb-ts/kdb-vec). Has a name but no binary/CLI.

R2 — display is required and globally unique

• R2.1 — type ∈ {product, service, engine} must prefix with Koder (e.g. Koder Flow, Koder Koda).
• R2.2 — type ∈ {meta, umbrella} must not prefix with Koder (e.g. Drafts, Kdb).
• R2.3 — Title Case with single spaces. ASCII only.

R3 — bare is required

Equals display minus the Koder prefix (when present). Title Case.

R4 — slug is required, kebab-case lowercase, globally unique

• R4.1 — type ∈ {product, service, engine} with bare not starting with K: slug = koder-<bare-lowercase> (e.g. koder-flow).
• R4.2 — type ∈ {product, service, engine} with bare starting with K: slug = <bare-lowercase> (e.g. koda, kortex, kompass).
• R4.3 — type ∈ {meta, umbrella}: slug = <bare-lowercase> (no koder- prefix; e.g. drafts, kdb).
• R4.4 — slug matches ^[a-z]+(-[a-z0-9]+)*$.
• R4.5 — Proximity is not collision. Uniqueness (R2/R4/R6, enforced by T3–T5) is exact-match only. Phonetic or orthographic similarity between names is explicitly allowed and is not grounds for audit failure — koda (engine), koru (product) and kora (product) may all coexist. The "distinctive" notes in the registry rationale column and in policies/naming-aliases.kmd are advisory branding guidance, never a hard gate.

R5 — path is required and must exist

• R5.1 — Absolute from monorepo root (e.g. services/foundation/flow).
• R5.2 — Path exists at audit time (CI verifies), unless the entry is status: planned (R5.4).
• R5.3 — Derived from the L1/L2/L3 taxonomy (meta/docs/stack/taxonomy.md).
• R5.4 — status (optional) reserves a planned name. An entry MAY carry an optional status form, expressed as an 8th registry column. Values:
  • active (default; also the meaning of an absent/empty cell) — a shipping component; path must exist (R5.2 / T8).
  • planned — a name reserved for a component that is part of a ratified architecture (e.g. an RFC-prescribed suite member) but not yet coded. A planned entry is exempt from T8 (its path legitimately does not exist yet) but still subject to every other rule (unique display/slug/aliases, prefix rules, regexes). When the component is built, drop the status cell (it becomes active) and T8 then enforces the path. This prevents the anti-pattern of either (a) deleting a real, ratified name reservation just to pass an incomplete schema, or (b) registering a fake path. Sections without any planned member keep the 7-column layout; only a section that has one adds the status column. Example: services/crypto/cipher (Krypt-suite member, krypt-RFC #060) reserved before code exists.

R6 — aliases is required (may be [])

• R6.1 — Array of strings, each globally unique across the entire registry (including cross-component, cross-type).
• R6.2 — Maximum 3 aliases per component.
• R6.3 — Each alias matches ^[a-z][a-z0-9]*$ (compact only, no hyphens — alias is the compact form by design).
• R6.4 — Each alias requires a 1-line aliases_reason in the registry entry.
• R6.5 — type = umbrella defaults to aliases: [] and never associates a binary/CLI. Aliases on umbrella entries are advisory only (for oral/written reference).
• R6.6 — Aliases have no rigid prefix rule. Convention is k<bare> compacted (kflow, kdrafts) when the bare name is a common English word, but flux, flowy etc. are valid if registered. See policies/naming-aliases.kmd for when to create an alias.

3. Test cases (run by koder-spec-audit naming)

All severity is hard. Failure blocks PR merge via .gitea/workflows/audit-naming.yml.

4. Relationship to other specs

• specs/binaries-and-cli/naming.kmd consumes this spec. The binary name for a component is aliases[0] if present, else slug. Updates §1, §3, §11 to reflect the new derivation.
• specs/naming/brand-score.kmd is orthogonal: it scores candidate names for branding fitness; this spec governs how an already-chosen name appears in its 6 forms.
• docs/stack/taxonomy.md defines where the component lives (L1/L2/L3); this spec defines how to name it.
• docs/stack/vocabulary.md defines the conceptual category (componente/documento/módulo/artefato/variante); this spec defines the surface forms.

5. Examples — full registry entries

product / bare-non-K

type: product
display: Koder Hub
bare: Hub
slug: koder-hub
path: products/dev/hub
aliases: [khub]
aliases_reason:
  khub: "'hub' is a common English word; CLI binary already named khub"

engine / bare-K

type: engine
display: Koder Koda
bare: Koda
slug: koda
path: engines/lang/koda
aliases: []
aliases_reason: {}

meta

type: meta
display: Drafts
bare: Drafts
slug: drafts
path: meta/context/drafts
aliases: [kdrafts]
aliases_reason:
  kdrafts: "'drafts' is a common English word; k-prefix signals meta-Koder context"

umbrella

type: umbrella
display: Kdb
bare: Kdb
slug: kdb
path: infra/data/kdb
aliases: []
aliases_reason: {}
note: "Groups kdb-kv, kdb-ts, kdb-vec, kdb-search, kdb-stream"

6. Migration

The current specs/binaries-and-cli/naming.kmd §1 rule (binary = k<slug>) is superseded by this spec. New derivation: binary = aliases[0] || slug. See specs/binaries-and-cli/naming.kmd for the updated derivation rules.

Existing components keep their current binary names. The registry's seed entries reflect the current state — no renames forced by this spec.

7. Form per surface — which form appears where

§1's "Where it's used" column is coarse. This section is the normative, exhaustive mapping from rendering surface to form. It binds the surfaces that the consuming specs left only structurally described ("nome do produto") to a concrete form, closing the bare-vs-display ambiguity. Consuming specs (landing-pages/products.kmd, landing-pages/packages.kmd, desktop-apps/title-bar.kmd, koder-app/behaviors.kmd) reference this section instead of re-stating the rule.

Surface → form

Rules

• R7.1 — display is the identity-anchor form. The surfaces that anchor the product's identity — page <title>, OG/Twitter title, navbar/.nav-brand, desktop window title bar, in-app primary wordmark, Hub package-page heading / catalog name — must use display (Koder <Bare>). These are the surfaces that establish which product this is; they are never bare, slug, or alias.
• R7.2 — bare/distinctive is for surfaces where display is already anchored on-screen. Once R7.1 puts display on the page/screen, a secondary surface may use bare (<Bare>) — or a deliberate distinctive brand form — as expression. This covers (a) the landing hero <h1>, whose fleet convention is the Meet <Bare> template (e.g. Meet Jet, Meet Cron) or a distinctive lowercase brand (kicon, Kodix), since the navbar + <title> already anchor display on the same page; and (b) dense, repetitive in-app chrome where repeating "Koder" is noise — breadcrumbs, tab labels, compact secondary headers, in-product nav items. display itself remains valid on these surfaces (e.g. a hero reading Koder Mediant is fine) — R7.2 permits bare, it does not forbid display.
• R7.3 — slug/aliases are never a human brand label. slug and aliases never appear as the visible name of the product in UI or marketing copy. Their surfaces are machine/address/CLI only (URLs, package ids, subdomains, binaries, IPC, deep links). The Hub OG fallback ({slug} — Koder Hub, packages.kmd §2.4) is the lone exception and fires only on a catalog data-integrity failure, never on the happy path.
• R7.4 — meta/umbrella collapse. type ∈ {meta, umbrella} carry no Koder prefix (R2.2), so their display == bare (Drafts, Kdb); R7.1/R7.2 reduce to the single form.

Test cases

T1–T11 are global-registry checks under koder-spec-audit naming. T12–T13 are surface checks owned by the consuming landing/app audits — this section is their normative source.