Apupiwe

Why and how: the design rationale§

These are the project's working notes, kept for whoever works on the language next, which is often an AI assistant. They are dense, but the reasons for everything are here.

Written 2026-10-10 so a later session (or person) can understand why each part of Apupiwe is the way it is, rebuild it, and change it safely.

How this differs from the other docs. the reference says what the language is now. changelog records decisions in the order they happened, including dead ends. This file is organised by topic and gives, for each part of the design: the decision, why (with its source: the author, evidence, or Claude), how it was made (method, tool, parameters), and how to change it (which file, what else moves, the trigger that should make you change it). Where this file and language.md disagree, language.md wins and this file is out of date.

Source labels used below: [author] a ruling by the author; [evidence] research in research/; [Claude] Claude's own proposal, accepted by the author. Claude-sourced parts are the ones most worth questioning (the author's rule: Claude's own requirements are the most dangerous, because they sound reasoned).


1. Foundations§

1.1 What the project is§

Part Source Why
A universal human language for modern Earth, designed from first principles, as a thought experiment [author] 2026-10-08 The author's goal. A fantasy/D&D use was dropped: designing for fantasy and for modern Earth are different tasks. A signed surface was dropped: text is the wrong medium to design signs.
Imagined as a native language that children grow up speaking, not an auxiliary language for adults [Claude, adopted] Removes every adoption question (which killed every real auxlang; see the conlang report) and leaves only human constraints: mouth, ear, memory, attention, child acquisition. Consequence: "easy for adult X-speakers" is not a criterion; what learners and native speakers do to a design is.
Goal and priorities (2026-10-11): a thought experiment in the best human language, built from what the world's languages share, for people who would grow up speaking it, and a real language its creator can learn, enjoy and share. Conflicts resolve as clarity > predictability > economy > reach; adult learnability is a gate [author] Replaces the original north star ("faithful transmission of thought, at a cost speakers will actually pay"). "Learnability" was split in two: predictability (no arbitrary memorisation) serves natives and learners alike and ranks high; explicitness for adults conflicts with fluent use and stays only a gate. The split comes from 2026-10-10: every native-first economy choice was backed by tests, and the one rejected rule (word kinds as a requirement) failed on arbitrariness, not difficulty.
The yardstick: Reach, Economy, Clarity, Restraint, Gate [author] 2026-10-10, built blind in the author's private notes Makes "best" checkable. Its layer 5 adds what the north star lacked: let context take over whenever it's available. Restraint: design only what speakers can't easily fix themselves. Gate: an adult can learn it well enough to raise a native speaker. Since 2026-10-10 recent changes (omission, topic-based pronouns, usage bans removed) come from applying it.
Premise 2: legacy conventions are void, base included [author] 2026-10-08; amended 2026-10-09 Amendment [author]: "in reality, base 10 will functionally remain the default". The language is base 10 with today's calendar and units; senary is a topic it can talk about (§7).
Owned by Claude, the author along for the ride and learning [author] Claude drives and explains. The author's pushback is real review, not a request for reassurance.

1.2 How decisions get made§

These are the working methods; reuse them to keep changes consistent.


2. Sounds§

Decision Why How it was made To change it
Vowels a e i o u [evidence] the most common and most dispersed 5-vowel system (vowel dispersion, Liljencrants & Lindblom 1972) — Any vowel change rebuilds all words (build.py build), breaking the freeze.
13 consonants p b t d k g m n f s l w y; places: lips, tongue tip, tongue body (y), back [evidence] Miller & Nicely 1955: place of articulation is the cue noise destroys first; voicing and nasality survive to −12 dB Inventory compared at a 3,000-root scale (build.py scale): the inventory must leave room for that many distinct two-syllable words build.py FULL.
/v/ and /z/ deleted [evidence] rare worldwide (PHOIBLE: 27% and 30%), /v/ confusable with /b/ and drifting toward /w/, /s/–/z/ merging; founders' sounds win (Hebrew) so rare sounds are at risk build.py scale: removing /z/ cost almost nothing at 3,000 roots Re-add in FULL; rebuild.
Syllables (C)V(n); vowel-only syllables only word-initially; n the only coda [evidence] CV is universal and robust; one coda keeps words short without clusters — Inventory in build.py.
No tones [Claude] Leaves pitch for intonation and emotion; tones are hard for adult learners (Gate) —
Stress on the first syllable of every content word; grammar words unstressed; stress is higher pitch, not length [evidence] fixed initial stress marks word beginnings (Finnish, Hungarian); listeners hear lengthening as word ends. The author asked to weigh drift; the drift risk of initial stress (later syllables eroding) is handled by drift-proofing (§3.3) Challenged by the author ("should stress be fixed?"), kept after research (research/notes/stress-and-sound-change.md) —
Declination: stressed peaks step down across a phrase, reset at a comma or full stop [author's reading test] runs of two-syllable words made the voice "bounce" Specified from how nearly all languages already behave —
Harmless variants declared in advance (k/g → ch/j before i/e, nasal vowels, soft middle consonants) [evidence] Gurevich 2004: 92% of 230 lenitions merged nothing The vocabulary is built so these never merge two words (§3.3) —

3. How word forms are chosen§

This is the language's most distinctive machinery. Root sounds are arbitrary on purpose; logic lives in how words combine (§5).

3.1 Why arbitrary roots§

[evidence + Claude] Languages whose sounds encode meaning (Wilkins 1668: Tida redness / Tide greenness; Ro; Solresol's mirror-image opposites) turn one misheard sound into a plausible neighbouring meaning that context can't catch, and their categories go stale. Learning studies (Monaghan, Christiansen et al.) find arbitrary forms help learning individual words. So similar and opposite meanings get forms that sound as different as possible.

3.2 The mishearing model (tools/confusion.py)§

3.3 Drift-proofing (docs/drift.md, build.py)§

[author asked to weigh drift heavily; evidence] A native language changes; the fast-changing layer is the one-syllable grammar words, which carry most of the precision machinery. - Content words must stay distinct after predicted changes: later-syllable e/i and o/u merge, middle p/t/k voice, final -n is lost, s/z merge. Implemented as Inventory.content_key: two words with the same key can't coexist. - Grammar words that can fill the same slot start with different consonants (GROUPS_STRICT in build.py), so vowel reduction can't merge them; words in the same wider position stay distinct after drift (GROUPS_WIDE, grammar_key). - No two grammar words differ only by a final -n (it's the first thing to go).

3.4 Juncture (tools/juncture.py)§

[Claude, idea from senary] Written tests can't hear word boundaries. Rules: no content word begins with a one-syllable digit's syllable (so "digit + grammar word" can't sound like a content word); no -n pairs; no grammar word ending in -n before a vowel-initial word that would be heard as another word. Run after any addition.

3.5 The optimiser (tools/words.py add-content)§

For a new root it tries every two-syllable form not taken (after drift keys) and minimises: - confusion with every existing two-syllable word, weighted by meaning: ×30 antonyms (--antonym, recorded in data/antonyms.tsv), ×10 number words, ×3 same semantic field, ×1 other; - weighted by frequency (TIER_FREQ tiers 1–5) in both directions; - plus a length penalty (EFFORT = 0.02) so frequent words stay short.

It excludes digit-initial syllables and offensive matches (§3.6). Forms are never hand-picked. add-grammar does the same for one-syllable words but doesn't enforce the same-slot rule; only build.py build does (and a full rebuild breaks the freeze).

3.6 Offensive-word filter (tools/offensive.py, data/offensive.tsv)§

[author] 2026-10-09: no word should sound like an offensive word, or clash in a taboo topic, in major languages. - Data: Wiktionary via kaikki.org extracts for 34 of the most spoken languages: entries tagged vulgar/offensive/slur/derogatory, plus taboo meanings (sex, genitals, excrement, urine, death) read from glosses. 32,910 pronunciations, each mapped into our sounds with the names.py mapping. - Matching: exact; near (voicing and e/i, o/u merged); prefix. Ranking: only words whose first sense is offensive and that are common (wordfreq Zipf ≥ 2.5) block a form. Run tools with ps.wordfreq, or every listed word counts as common. - Review is by hand. Most raw hits are noise; one-syllable grammar words match something in 34 languages almost always. Six words moved (lanu→lenu, nega→lasu, pisan→tisan, webo→yawu, ku→nun, ano→ago); lon/pi/go kept because no free one-syllable form exists. - Refresh with python offensive.py fetch (a few minutes, ~1 GB streamed); review with check.


4. Grammar§

4.1 Principles (language.md section 1; principle 7, "a precise way always exists; it need not always be used", is the author's rule)§

Principle Source Why
1. The common case costs nothing [evidence] Zipf's law of abbreviation; research round 1 Statements, ordinary belief, unknown source, the topic and unspecified time are unmarked; only departures cost a word.
2. Heads first; position carries role (SVO, modifiers after) [Claude + evidence] A listener who loses a word still knows who did what; fixed order is among the most stable features (Dediu & Cysouw 2013). Native Esperanto, Hebrew and creoles all moved to SVO without inflection. Since omission (rule 11), the guarantee holds only for what is said.
3. Operators cover what follows [Claude] One scope rule for NOT, confidence, source, ONLY, degree.
4. Heavy goes last [evidence] processing (end weight) Relative clauses have no end marker, so nothing may follow them in their phrase.
5. Doubling widens or strengthens [Claude] A built-in renewal path: when a word wears down, its double takes over (mu mu, nun nun) inside the system.
6. Every social pressure gets its own outlet [evidence] drift items 1–2 Emphasis (ba, bi) and politeness (nun) have their own words so they don't wear down the precision words. Since the Restraint review this is a design plus a prediction, not a usage ban.

4.2 The grammar-word layer§

4.3 Speech acts, confidence, source§

4.4 Reference§

4.5 Omission (language.md 4.5)§

[author, yardstick layer 5] Anything context supplies may be left out, including verbs; fragments are grammatical (as in Mandarin, Japanese, Korean). Economy test 01: the language was ~1.5× English's syllables; the four fixes (tan/ben alone, bu topic, wan/yi topic, omission) cut 12% with meaning 44/44 on retest.

4.6 Smaller rules worth knowing the reason for§

4.7 Politeness (research/notes/politeness.md)§

[evidence] Politeness creeps into hedges and questions and erodes them; polite pronouns cycle every 150–300 years. So: one particle nun with no truth meaning, repeatable; no polite pronouns or speech levels (address words can be replaced, pronouns can't); yo yo emergency suspends it. The crew-resource pattern "problem, act, what we need" is the model. Routines optional.


5. Words and vocabulary§

5.1 Word building (tests/wordbuilding-ab-01)§

Four markers no (doer), ge (thing done/made), du (tool), pu (place) [evidence: the most widespread derivations; analytic languages all grow such heads from nouns]. Blind A/B: markers 71/76 vs generic heads 69/76; kept because shorter, and generic heads erode into markers anyway. Patient person = ewo man gun + verb (ge was read as a thing). Noun bases link with pi or a verb, never a bare relation phrase (rule 8 would attach it to the verb). Bare noun+noun leaves the relation to guesswork (Štekauer; the blind test), so only for gender and listed compounds.

5.2 How a new word is made (vocabulary-method.md section 5)§

Say it with words you have → a new root only when earned (convergent basic concept, frequent modern concept, or a phrase failing a blind test) → the tools choose the sound → frequent phrases may be clipped later → names and technical words are adapted, not coined → offensive filter.

5.3 Which concepts get roots (docs/vocabulary-method.md, vocabulary-plan.md)§

Two layers [author + Claude, 2026-10-08]: - Deep layer (base human experience): convergence of independent signals: area-balanced lineage coverage in CLICS4 (tools/concepts.py; New Guinea and the Americas would dominate raw counts), children's early vocabulary (Wordbank), time-stability as a check (Holman 2008, Pagel 2007). The author rejected weighting by speaker numbers: weight by lineage. Only the top ~300 CLICS concepts are data-backed; the seed stopped there plus NSM primes. - World layer (modern need): measured by blind tests on modern urban texts; built words by default. Prompted by the author noticing the lists' bias toward low-technology life. - Stop condition: two tests in a row losing <1 point to missing words (met at test 05, 445 roots).

5.4 Where boundaries go: lump or split§

In order: (1) a formal efficiency model where one exists (colour, kinship); (2) action-relevant same-slot alternatives get two roots (left/right, buy/sell); (3) family-balanced lump rate from CLICS4 (tools/clics_rates.awk): ≥50% one root, 20–50% one built from the other, <20% two roots; (4) a shared English word is not evidence; (5) never derive along a link only one family uses. The 50/20 cut points are arbitrary [Claude's research agent]; refine only on test evidence. Example: apu = word and language (50.2%); dunan = moon and month (69.6%). - Colour: six roots (black, white, red, yellow, green, blue) from colour-naming data, not eye physiology; blue/green split rests on modern need. Kinship: mother, father, child, sibling, spouse; the rest composed (410 systems among 487 languages, too varied to copy). - Observation, not theory [author's question, 2026-10-08]: basic words name what's experienced ("the sun appears", illness by symptoms); theory-laden concepts are composed so they can be rebuilt. - English leaks fixed (2026-10-10): concepts had been matched to roots by English gloss, merging fly (insect)/fly (move) and three senses of "light", and muyi counted occasions. Now: gekon the insect fly, gimu occasion, pale = mu buda ("light, not heavy" was already gamun). Ambiguous glosses carry a second gloss (Kit advice), and the lump/split rule says a shared English word is not evidence (vocabulary-method §3.4).

5.5 Names, loans, borrowing (tools/names.py, tests/names-01)§


6. Writing (research/notes, human test 01)§


7. Numbers, time, measurement§


8. The name§

apu pi we "everyone's language" [Claude proposed, author approved]: any language is apu pi + whose it is, and this one belongs to no people or place. Required apu to cover "language" (CLICS4: 50.2% of families lump word/language). Rejected: apu pi ewo (reads as "human language" in general), an invented name (wouldn't follow the grammar).


9. Rebuilding or tweaking it§

9.1 Environment§

Python with numpy, from the repo flake (nix develop, or direnv via .envrc), run from tools/:

python words.py add-content GLOSS FIELD TIER [--antonym GLOSS]

wordfreq is needed for the offensive filter's frequency ranking. clics_rates.awk needs the CLICS4 CLDF tables (download from Zenodo/clld; not kept in the repo).

9.2 What is generated vs hand-made§

Artefact Made by Rebuildable?
grammar.tsv, lexicon.tsv forms build.py build (once, 2026-10-08), then words.py additions and logged moves Yes, but a rebuild re-assigns every form; never do it on the frozen core. To reproduce today's forms, replay the additions in design-log.md order.
Concept list and tiers concepts.py ranking + judgement (tiers are English intuition) Partly; data/concepts.tsv has the evidence line per concept
numbers.tsv digits 0–5 from the base-6 optimiser (build.py numbers3); 6–9 and place words via words.py Yes
offensive.tsv offensive.py fetch Yes (Wiktionary changes over time)
Rules, principles by hand, in language.md —
Tests fresh blind agents; prompts and scoring rules in each tests/*/ folder Re-run with new agents; never reuse a reader who has seen the docs

9.3 Common changes and what they touch§

9.4 Tests that exist§

Back-translation 01–04 (fidelity, politeness, nesting), grammar coverage, word-building A/B, names, vocabulary 01–05, economy 01 (context), human reading 01 (the author aloud). Listening 01 was built but stopped: no available synthesiser (Piper, Kokoro, MBROLA in four voices) produced a reliable word-initial g before u, and the author stopped testing (2026-10-10). Its lesson for a rerun: use a human reader, or a cloud TTS that accepts IPA, with a carrier phrase.


10. The interpersonal layer, culture and text§

Decision rule for all of these [author]: where unrelated languages converge on a function, provide it; where they split on the form, choose the cheapest form, optional rather than obligatory, carried in words rather than intonation (so speech and writing carry the same thing). Evidence: multilanguage test 01 (tests/multilang-01/).

Part Why Rejected / add-back
Address position (first or last, with a pause) 5 of 7 translators had to guess; calling someone is universal —
lanno, gender-neutral title, also before role and kin words Respect for people named is near-universal; its own word stops "old"/"leader" being pressed into titles (senior → sir, señor); Hindi lost all 10 respect markers without it Graded "you": 136 of 207 languages lack it (WALS 45). Add back if speakers can't avoid sounding rude
Focus o ("Tomas took it", "I did pay") 10 of 11 languages mark contrast; stress doesn't survive writing; moving words breaks fixed order —
fe also, wi even, nedin almost, mesun each Missing operators the tests needed; one-syllable forms by measured frequency (grammar rebuild) —
Stance position at sentence end; a, buni, donon All 11 languages flagged stance; without seeds, min/kon/ba get pressed into it (principle 6) Add more seeds if that happens anyway
Topic opener pi X, Every language can make the thing acted on the topic; only 162 of 373 have a passive (WALS 107) Passive, result complements, articles: add back if a round trip loses meaning to them
manni habitual; gan momu on purpose Flagged by 5 and 6 languages; built or short words, no endings —
tan/ben alone for events; bu/wan/yi by topic; omission (language.md 4.5) Economy test 01: casual talk needs them; topic-based reference and dropping what context supplies are how Mandarin, Japanese, Korean and Algonquian work Mechanical reference: add back if listeners lose track
Clock: both 12- and 24-hour Speakers live in existing cultures; the two systems can coexist —
Weekdays ISO 8601 Cultures' numbering conflicts (Monday = 1 or 2); tie-breaker: when conventions conflict, follow the international standard Named weekdays: the 7-day week is itself one culture's
Names keep their owner's spelling Adapted names collided and became unrecognisable; most Latin-script languages keep spelling —
Loans in their international form; brands keep spelling; computer words mostly everyday roots Major non-English languages build interface words from everyday words (搜索, buscar); English loans were an English-centred default —
Confidence in sixths 7 values match the bands forecasters can use; almost every value one syllable Tenths (familiarity)
Writing: notation passes through, ? and ! allowed, capitals harmless Text and computer use; usage bans became predictions (Restraint) —
Commas droppable in chat Comma test: 0 of 67 lines lost meaning without them; a precise way must exist, not always be used [author] Targeted test if names at the end or topic openers get misread

Clear forms by meaning, not word kind [author, 2026-10-11]. The last row of the interpersonal table here first became a rule (each root has a default kind; a quality after a noun describes it, an action after a subject is its verb), then a convention. Under the priority order it failed predictability: about 50 borderline words had an arbitrary kind. Now the speaker picks the form by what they mean: gun for a state, an aspect word for an event, man for a description. It works for any word, with nothing to memorise. Bare noun + word is left to context. Mandarin works the same way (很, 了/在, 的). The kind column was removed; add it back as a dictionary hint if learners keep asking how a word is typically used.

11. Known weaknesses (what a successor should doubt first)§

  1. Validated mostly by its own instruments: the confusion model is scored against itself; blind readers are AI agents with world knowledge. One human has read it aloud; none has listened.
  2. English-centred: listener data, test texts, readers, English glosses (ambiguous ones pinned with a second gloss since 2026-10-10), technical loans. "Universal" is a goal, not a result.
  3. The full one-syllable space: every future grammar word costs two syllables.
  4. The watch list (drift.md): confidence collapsing or used for emphasis, politeness taking over hedges, topic-based pronouns needing a mechanical fallback, aspect words unused.
  5. Frequency tiers and lump/split thresholds are judgement, not data.

Also: changelog · senary measurement