Component Naming Forms

naming specs/naming/forms.kmd

Forms of reference for every Koder Stack component: type, display name, bare name, slug, path, and aliases array. Defines the regex per form, the prefix rule (Koder vs no-Koder), and global uniqueness. Registry lives at meta/docs/stack/registries/component-names.md and is CI-checked by `koder-spec-audit naming`.

When this spec applies

Primary triggers

Referenciar ou nomear um componente Koder

All triggers

Referenciar ou nomear um componente Koder em código, doc, conversa ou config
Criar um componente novo (produto, serviço, engine, meta, umbrella)
Adicionar ou renomear um alias coloquial (kflow, kdrafts, kterm…)
Decidir o nome de binário CLI / D-Bus ID / Android applicationId
Editar meta/docs/stack/registries/component-names.md

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/component-names.md.

1. The 6 forms

Form	Example (Flow)	Example (Koda)	Example (Drafts)	Example (Kdb umbrella)	Where it's used
type	`service`	`engine`	`meta`	`umbrella`	classification
display	`Koder Flow`	`Koder Koda`	`Drafts`	`Kdb`	UI, marketing, prose docs
bare	`Flow`	`Koda`	`Drafts`	`Kdb`	conversation where Koder context is implied
slug	`koder-flow`	`koda`	`drafts`	`kdb`	repo, path segment, package id
path	`services/foundation/flow`	`engines/lang/koda`	`meta/context/drafts`	`infra/data/kdb`	filesystem reference
aliases	`[kflow]`	`[]`	`[kdrafts]`	`[]`	CLI binary, D-Bus tail, oral speech

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).
R5.3 — Derived from the L1/L2/L3 taxonomy (meta/docs/stack/taxonomy.md).

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`)

#	Check	Severity
T1	Every registry entry has `type`, `display`, `bare`, `slug`, `path`. `aliases` field exists (may be `[]`).	hard
T2	`type` matches the enum (R1).	hard
T3	`display` is unique across the registry.	hard
T4	`slug` is unique across the registry.	hard
T5	Each `alias` is unique across the registry (cross-component, cross-type).	hard
T6	`slug` matches `^[a-z]+(-[a-z0-9]+)*$` (R4.4).	hard
T7	Each `alias` matches `^[a-z][a-z0-9]*$` (R6.3).	hard
T8	`path` exists in the monorepo (R5.2).	hard
T9	`display` follows the `Koder` prefix rule per `type` (R2.1, R2.2).	hard
T10	`slug` follows the `koder-` prefix rule per `type` + bare-initial (R4.1, R4.2, R4.3).	hard
T11	`len(aliases) ≤ 3` (R6.2). Each alias has a non-empty `aliases_reason` (R6.4).	hard

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: {}

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.

References

meta/docs/stack/specs/binaries-and-cli/naming.kmd
meta/docs/stack/specs/naming/brand-score.kmd
meta/docs/stack/policies/naming-aliases.kmd
meta/docs/stack/registries/component-names.md
meta/docs/stack/taxonomy.md
meta/docs/stack/vocabulary.md