Fridai technology and service naming standard

• Status: Fridai-wide engineering standard
• Effective: 2026-07-31
• First application: Fridai Redline
• Owner: Fridai Engineering
• Review cadence: annually and whenever a product boundary, portfolio, or canonical namespace changes
• Nature: engineering standard, not corporate policy

Purpose

This standard defines how Fridai names the software estate it creates: products, bounded domains, repositories, applications, microservices, APIs, workers, functions, daemons, agents, jobs, schedulers, pipelines, command-line tools, libraries, packages, adapters, plugins, data stores, queues, topics, caches, infrastructure resources, endpoints, and future artifact types.

It applies regardless of programming language, repository layout, runtime, hosting provider, deployment model, or whether the artifact is public or internal.

Names are part of Fridai’s organizational memory. They must help humans and machines retrieve context, reconstruct decisions, understand ownership, and connect systems across time. A good name survives a framework migration. A good registry preserves the former name after a rename. Neither should depend on one person remembering what an acronym meant.

Strategic basis

This standard follows Fridai’s organizational-intelligence strategy:

• Organizations compound intelligence by preserving and applying context. Stable identifiers make that context discoverable and reusable.
• Fridai maintains architectural neutrality. Canonical names describe durable capabilities, not current vendors, models, frameworks, or deployment types.
• Reversible experiments precede institutional architecture. Experimental names remain semantic and provisional until evidence justifies promotion.
• Knowledge is refined, superseded, and retired rather than erased. Legacy names remain traceable aliases.
• Git and the knowledge graph provide cognitive control. Every registered artifact is a node with ownership, lifecycle, and relationship metadata—not merely a string in a cloud console.
• Measurement must serve organizational outcomes. Naming quality is evaluated through retrieval, collision, ownership, migration, and incident-response outcomes, not aesthetic uniformity alone.

Normative language

• MUST identifies the small set of requirements necessary for global uniqueness, traceability, security, and operability.
• SHOULD identifies the default that teams follow unless a documented constraint makes another choice more practical.
• MAY identifies an optional convention.

Exceptions are expected in a long-lived estate. An exception is compliant when its reason, owner, affected identifiers, compatibility impact, and review date are recorded in the registry or migration record.

The naming model

Fridai uses three separate layers. They must not be collapsed into one name.

1. Human product name — explains the capability to a person.
2. Canonical technical identifier — stable semantic identity used across repositories, catalogs, deployments, and telemetry.
3. Airport alias — optional memorable identity for a durable product or system boundary.

The canonical technical identifier is the operational source of truth. The airport alias is a discoverability layer. The human product name may evolve for communication, but its relationship to the canonical identifier must remain in the registry.

Canonical identifier grammar

The default grammar is:

<portfolio>-[<domain>-]<capability>[-<component>]

The domain segment distinguishes a capability that sits inside a broader bounded context — ingest, proc, iac, memory. It is omitted when the capability is itself a registered product boundary, as in fio-redline.

Examples:

fio-redline
fio-ingest-email
fio-proc-vector
fio-memory-retrieval-api
fio-memory-retrieval-worker

Portfolio

The portfolio identifies the enduring product or platform family.

• fio- identifies everything Fridai builds: products and their dedicated services, plus shared platform, corporate, estate, governance, and operational infrastructure. It is the sole portfolio prefix.
• A new portfolio prefix MUST be registered before use, and is warranted only by a genuinely separate brand or legal entity.

Changing cloud providers, programming languages, teams, or repositories does not change the portfolio.

Domain

The domain identifies the stable bounded context, such as kb, identity, memory, ingest, proc, graph, or billing. Teams SHOULD use an existing registered domain before creating a synonym.

Domains describe organizational capability, not org-chart ownership. A team reorganization must not force repository and endpoint renames.

Capability

The capability states what the artifact accomplishes: redline, email, vector, auth, search, archive, or decision-routing.

• Prefer specific nouns or noun phrases.
• Use monitor only for observation. An artifact that comments, commits, changes state, or merges is a review or collaboration capability.
• Avoid empty words such as service, system, engine, manager, new, next, misc, or utils unless they distinguish a real, documented concept.

Component

The component suffix is optional. Use it only when one canonical capability has multiple independently operated deployables or distributable artifacts:

fio-memory-retrieval-api
fio-memory-retrieval-worker
fio-memory-retrieval-cli

Do not append api, worker, or service when there is only one deployable and the suffix adds no distinguishing information. Deployment type belongs in registry metadata and can change without changing identity.

Organization-wide infrastructure as code

iac is the registered domain for repositories whose primary capability is declaring and controlling infrastructure through code. org is the registered scope qualifier for infrastructure shared across Fridai rather than owned by a single product or project. Scope follows the portfolio and precedes the domain so identifiers retain the same broad-to-specific hierarchy as their human names.

Organization-wide provider control repositories use:

<portfolio>-<scope>-iac-<provider-or-capability>

For example, fio-org-iac-cf means Fridai organization-wide infrastructure as code for Cloudflare resources. cf is registered as Cloudflare only within the iac domain; it must not be assumed to have that meaning elsewhere.

Provider names are permitted in this form because adapting and controlling that provider is the repository’s durable purpose. The implementation tool remains metadata: a repository named for iac may move between Terraform and OpenTofu without a rename. Product-specific infrastructure remains with its product boundary unless ownership, privileges, state lifecycle, or blast radius require a separate registered repository.

Rules by artifact type

New artifact types follow the same test: identify the durable capability first, then add the smallest qualifier required to distinguish the artifact.

Environment, region, and instance names

The canonical ID MUST NOT contain an environment, region, version, ordinal, language, or vendor. Those values belong to deployment instances.

Default environment suffixes are:

dev
test
stg
prod

Provider resources use:

<canonical-or-component>-<purpose>-<env>[-<region>][-<ordinal>]

Examples:

fio-redline-cache-prod
fio-ingest-email-dead-letter-prod-ca-central-1
fio-memory-retrieval-worker-stg-02

Production uses the bare airport hostname. Non-production hosts use a subdomain:

yqa.fio.sh
stg.yqa.fio.sh
dev.yqa.fio.sh

Ephemeral review environments MAY include a merge-request or short commit identifier, but must carry an expiry and must not be entered as permanent registry nodes.

Airport aliases and metaphor categories

Airport aliases are optional. They are reserved for durable product, platform, or system boundaries that benefit from a memorable internal identity. A microservice, queue, database, package, and Worker underneath one boundary do not each receive another airport code.

Categories are discovery tags, not architecture, security, criticality, or lifecycle controls.

An airport can contain an FBO; the airport itself is not an FBO. “Sanctuary” is a Fridai metaphor and must not be presented as an aviation classification.

Alias allocation rules

1. Verify the three-letter code using the official IATA code directory.
2. Reserve it in the global Fridai registry before using it in DNS, dashboards, secrets, or documentation.
3. Use uppercase in prose (YQA) and lowercase in DNS (yqa.fio.sh).
4. Allocate one code to one durable product/system boundary.
5. Never reuse a retired code. Preserve a tombstone with its former target.
6. Record the metaphor rationale, but do not use it as evidence for access, criticality, ownership, data residency, or architecture decisions.
7. Do not allocate codes to short-lived experiments. Evidence and ownership precede promotion.

Muskoka Airport uses IATA YQA and ICAO CYQA, not MKA.

Global technology registry

Every production artifact MUST resolve to a registry node. The authoritative Fridai registry may be implemented in the corporate knowledge graph or service catalog, but Git-controlled records remain the bootstrap and audit source.

The minimum record is:

Names alone do not establish trust. Authentication, authorization, data classification, network exposure, recovery objectives, and ownership MUST be explicit fields.

Naming lifecycle

Naming follows the same evidence-driven lifecycle as other Fridai knowledge.

Candidate

• Use a semantic working name.
• Record the DRI and intended capability.
• Do not reserve DNS or an airport alias merely for an idea.

Experiment

• Keep the name reversible and provider-neutral.
• Mark resources ephemeral and record expiry.
• Treat the proposed boundary as a hypothesis.

Release candidate

• Confirm the product boundary, owner, canonical ID, package namespace, endpoints, compatibility plan, and registry relationships.
• Allocate an airport alias only if the boundary is expected to persist.
• Record legacy identifiers before changing anything external.

Active

• Use the canonical ID consistently in telemetry, catalogs, CI/CD, runbooks, and incident management.
• Measure unresolved-name collisions, unknown telemetry identities, stale owners, and migration failures.

Deprecated and retired

• Deprecation redirects new adoption while preserving existing resolution for a defined support window.
• Retirement deactivates an artifact but does not delete its record.
• Preserve aliases, supersession relationships, final owner, and evidence.

Monorepos and distributed systems

• A monorepo uses the highest coherent product/system boundary as its repository name. Packages and deployables inside it retain distinct canonical components.
• Multiple repositories may implement one product, but each repository must state its parent boundary and responsibility.
• Do not split or merge repositories to make names aesthetically uniform.
• A product name, repository name, package name, deployable name, and endpoint are related identifiers, not necessarily identical strings.

Acronyms, abbreviations, and personal names

• Use an acronym only when it is registered, unambiguous inside Fridai, and more durable than its expansion. kb is permitted for knowledge base; iac means infrastructure as code; org means organization-wide scope when it follows the portfolio; and cf means Cloudflare only within the iac domain.
• Do not invent abbreviations solely to meet a preferred string length.
• Do not use employee names, initials, jokes, or temporary project codenames as canonical identifiers.
• Industry protocol and provider terms are allowed when they describe the contract being adapted, such as git, oauth, or astro.

Rename and compatibility standard

A rename is a knowledge-lifecycle event, not a search-and-replace exercise.

Before changing an external name, record:

• old and new canonical identities;
• rationale and evidence;
• affected repositories, packages, endpoints, OAuth callbacks, certificates, secrets, dashboards, alerts, integrations, caches, and consumers;
• compatibility mechanism and support window;
• rollback and ownership;
• supersedes and alias_of registry relationships.

Operational rules:

• Never unpublish a released package to obtain a cleaner name.
• Keep released artifacts retrievable and publish a migration path.
• Do not create an unprotected legacy hostname for compatibility.
• Avoid redirects for authenticated or mutating APIs unless methods, bodies, cookies, CORS, and OAuth behavior are proven.
• Serve both hostnames from the same protected deployment when a bounded API transition genuinely requires both.
• Product, package, schema, and API versions remain independent. A rename does not require changing /v1.
• Preserve stable machine identifiers when renaming them produces no user or operational value.
• Consumer repositories are changed only through their own authorization and review process.

Governance that people will follow

This standard intentionally avoids a central naming committee.

For a new canonical ID or alias:

1. The DRI searches the registry for existing domains, synonyms, and collisions.
2. The DRI adds or updates the registry record in the same merge request that creates the artifact.
3. One maintainer reviews semantic clarity, ownership, uniqueness, IATA validity when applicable, and migration impact.
4. Automation validates syntax, collisions, required metadata, and forbidden environment/version suffixes. Automation does not judge metaphor quality.
5. The artifact is promoted only when its lifecycle evidence supports it.

Teams SHOULD fix noncompliant names when touching the affected boundary or when the name creates measurable risk. They SHOULD NOT fund broad rename programs for aesthetics alone.

Adoption across the existing estate

This standard applies immediately to new artifacts. It does not require an estate-wide rename.

For existing artifacts:

1. Inventory the name exactly as it exists before normalizing anything.
2. Create a registry node with its current owner, lifecycle, and relationships.
3. Mark a nonconforming but operational name as legacy and record its intended canonical mapping.
4. Rename only when the artifact is already undergoing a boundary change, the old name causes measurable operational risk, or migration value exceeds its cost.
5. Preserve package, DNS, API, telemetry, and consumer compatibility according to a migration record.

An old name is not technical debt merely because it predates this standard. An unknown owner, ambiguous capability, collision, unsafe endpoint, or broken traceability is technical and organizational debt.

Operational measurements

Fridai SHOULD measure whether the standard improves organizational cognition:

• percentage of production artifacts mapped to registry nodes;
• percentage of logs, metrics, and traces carrying a known canonical ID;
• percentage of active nodes with a current owner, DRI, runbook, and review date;
• unresolved canonical-ID and airport-alias collisions;
• duplicate domain synonyms requiring human interpretation;
• median time for an engineer or agent to locate owner, source, runbook, dependencies, and data classification from a name;
• expired experimental resources and overdue legacy-alias retirement reviews;
• incidents in which naming ambiguity delayed diagnosis, authorization, or recovery.

These measurements diagnose the knowledge system. They are not a vanity score and should not incentivize low-value renames.

Conformance checklist

A new production artifact is conformant when:

• its durable capability and parent boundary are clear;
• its canonical ID follows the grammar or has a documented exception;
• its repository, package, deployment, and telemetry names are mapped;
• environment and provider details are outside the canonical ID;
• owner, DRI, exposure, classification, criticality, and lifecycle exist;
• dependencies and knowledge-graph relationships are recorded;
• any airport alias is verified, unique, and allocated at the correct level;
• legacy identifiers and migration commitments are preserved;
• runbook and decision evidence are linked;
• a human can understand the capability without knowing the metaphor.

Reference examples

Candidate examples do not reserve aliases. The global registry, not illustrative prose, determines allocation.