ADR-128: A Symbol Is Named by the Compiler — the Prefix Is the Package’s, or One Line in [build], and No Declaration Renames Itself

Status: Superseded by ADR-284 — its D1-D2 are D13 there, together with ADR-125 D10 Date: September 19, 2026 Target Version: Nikaia 0.0.9 Related: ADR-125 D10 (the naming rule), ADR-047 (a package is a directory), ADR-100 (the ledger’s hash)

1. Context

ADR-125 D10 names every exported symbol <package>_<name>, and left open whether a declaration may say otherwise. The case for a per-function override is a real one and a small one: a library that replaces an existing C library and must keep its symbol names; a company convention that wants hc_ where the package is called hyper-core. The case against is the header: the moment a symbol’s name is written by hand, the header stops being a projection of the ledger, and the reader of hc_do_thing cannot find the function it belongs to by its name.

2. Decisions

D1 — The prefix is the package’s name, or the one symbol-prefix the build sets.

[build]
artifact = "c-library"
symbol-prefix = "hc"        # default: the package name, `-` written `_`

Every exported symbol and every constant of the header uses that prefix and nothing else: hc_greet, hc_Session_send, HC_OK, HC_E_TIMEOUT. A package named hyper-core with no symbol-prefix exports hyper_core_greet. The prefix is a C identifier or the build refuses it, naming the character.

One line, in the place where the artifact is named, so that the prefix and the artifact are read together and the header is still generated from the ledger and one setting — which is what lets ADR-125 D9’s hash stand for the ABI.

D2 — No declaration renames its own symbol.

There is no as "name" on an entry point, no attribute, no second word. A function is exported under the name it has in the language, prefixed, and a method under its type’s name and its own. What a program wants to call differently outside, it renames inside: the name in the header is the name in the source, or the header is not documentation. A collision after prefixing is refused at the declaration, as D10 already says.

The one case that wanted the override — replacing an existing library symbol for symbol — is served by the prefix when that library’s names were prefixed consistently, which is the case for every C library that has aged well; a library whose names were not is not one this compiler should be asked to imitate one function at a time.

3. Consequences

• The header stays a projection of the ledger: every name in it is a name in the source, prefixed by one rule.
• A convention is one line in the build, not a word on every declaration.
• What it costs: one key in [build], read into the header generator and the emitter’s #[no_mangle] names.

4. What this does not decide

• A versioned symbol (hc_greet_v2), which a library keeps beside the old one across a breaking change; today that is a second function with a second name, written by hand, and it is enough until it is not.
• A symbol map for the linker (.def, version script); only the exported names are visible (ADR-125 D10), and how the platform hides the rest is the emitter’s, not the language’s.

5. What is built

Nothing. The order of work:

1. symbol-prefix in the manifest, with the identifier check and the --to-_ default;
2. the header generator and the emitter reading it.

#109 carries it, with ADR-125’s steps.

This site is open source. Improve this page.