glossary: bootstrap AILang nomenclature ledger
Add design/glossary.md (25 entries) and wire it in via the paths.glossary profile slot, making it standing reading for every skill and agent role. Built by the glossary skill's bootstrap procedure: five read-only glossary-extractor agents swept the prose surface (design/contracts, design/models, design/INDEX.md, docs/PROSE_ROUNDTRIP.md, and the 60 docs/specs in three blocks), reporting recurring domain-concept terms and their competing synonyms with frequencies. docs/plans was excluded as a derived execution artefact that mirrors spec/contract vocabulary rather than originating it. Three apparently-contested clusters were resolved by record-reality against the authoritative current docs (CLAUDE.md + design/): the retired .ailx extension yields to .ail; Form-A wins over "Form A" (13:2); round-trip wins over roundtrip (15:10). The one genuine nomenclature choice -- the canonical term for the structured hashable form -- was decided by the user: JSON-AST is canonical, .ail.json is its on-disk file. The local conformance check caught and removed a Form-B / JSON-AST Avoid-list collision before write.
This commit is contained in:
@@ -0,0 +1,161 @@
|
||||
# Glossary
|
||||
|
||||
Canonical nomenclature for AILang. Use the **canonical term**; never
|
||||
use a term under **Avoid**. If you need a concept that is not listed
|
||||
here, reuse the closest existing term — do not silently coin a new
|
||||
one. New entries are added only to record nomenclature already in
|
||||
consistent use; see `~/dev/skills/docs/glossary-convention.md`.
|
||||
|
||||
This file is the source of truth for the project's nomenclature: where
|
||||
any other document (including the design ledger) names a concept
|
||||
differently, the canonical entry and its **Avoid** list win.
|
||||
|
||||
---
|
||||
|
||||
## Authoring forms and identity
|
||||
|
||||
### Form-A
|
||||
**Avoid:** Form A, authoring surface, authoring projection, surface syntax, .ailx
|
||||
The textual authoring projection an LLM author writes, stored in
|
||||
`.ail` files; it round-trips byte-isomorphically to its [[JSON-AST]].
|
||||
The retired `.ailx` extension named the same form.
|
||||
|
||||
### Form-B
|
||||
**Avoid:** Form B, prose projection, prose surface, display projection, human prose
|
||||
The lossy, human-readable prose projection of a module, for display
|
||||
only — there is no Form-B parser, so it is never an authoring surface.
|
||||
|
||||
### JSON-AST
|
||||
**Avoid:** canonical JSON, canonical JSON-AST
|
||||
The canonical, hashable, content-addressed structured form of a
|
||||
module, serialised on disk as `.ail.json`. Derived in-process from
|
||||
[[Form-A]] via `ailang_surface::parse`; the two forms are
|
||||
byte-isomorphic.
|
||||
|
||||
### round-trip
|
||||
**Avoid:** roundtrip
|
||||
The invariant that parsing [[Form-A]] and printing it back is the
|
||||
identity (`parse ∘ print = id`), which keeps [[Form-A]] and the
|
||||
[[JSON-AST]] byte-isomorphic.
|
||||
|
||||
### content-addressed
|
||||
**Avoid:** —
|
||||
Identified by the hash of the [[JSON-AST]], so a symbol can be verified
|
||||
without spending context window reading its body.
|
||||
|
||||
## Memory model
|
||||
|
||||
### RC
|
||||
**Avoid:** —
|
||||
Reference counting — the canonical and only production allocator (CLI
|
||||
default `--alloc=rc`). Pairs with [[uniqueness]] analysis to elide
|
||||
counts where ownership is provably unique.
|
||||
|
||||
### uniqueness
|
||||
**Avoid:** linearity, linear types
|
||||
The static, post-typecheck dataflow analysis proving a value is
|
||||
uniquely owned, so its [[RC]] operations can be elided and in-place
|
||||
reuse is safe.
|
||||
|
||||
### mode
|
||||
**Avoid:** ownership mode, uniqueness mode
|
||||
The `own`/`borrow` annotation on a function parameter position
|
||||
declaring how the function consumes that argument. Modes belong to
|
||||
parameter positions, not to types in general.
|
||||
|
||||
### clone
|
||||
**Avoid:** RC clone, RC inc
|
||||
The explicit source term (`(clone x)`) that duplicates ownership of a
|
||||
value by incrementing its [[RC]].
|
||||
|
||||
### drop
|
||||
**Avoid:** dec, RC dec
|
||||
The [[RC]] decrement emitted when a value leaves scope, plus the
|
||||
shallow-dec emitted before a tail call.
|
||||
|
||||
### escape analysis
|
||||
**Avoid:** —
|
||||
The per-function pre-pass that decides whether an allocation can live
|
||||
on the stack instead of the heap.
|
||||
|
||||
### frozen value layout
|
||||
**Avoid:** frozen layout, box layout
|
||||
The pinned in-memory layout of a frozen (immutable, shareable) value,
|
||||
held stable across the [[embedding ABI]].
|
||||
|
||||
### mut-local
|
||||
**Avoid:** mutable variable, mutable local binding, mut variable
|
||||
A mutable local binding (`mut`); mutation is confined to locals, with
|
||||
no mutable variables or assignment across binders.
|
||||
|
||||
## Types, classes, dispatch
|
||||
|
||||
### typeclass
|
||||
**Avoid:** type class, type-class
|
||||
The narrow, Haskell-lite class system (`ClassDef` / `InstanceDef`
|
||||
declarations) — the sole ad-hoc-polymorphism mechanism.
|
||||
|
||||
### monomorphisation
|
||||
**Avoid:** —
|
||||
The sole specialiser: every class method is resolved to a concrete
|
||||
instance body at compile time, so there is no runtime
|
||||
[[method dispatch]].
|
||||
|
||||
### method dispatch
|
||||
**Avoid:** virtual dispatch, dictionary passing, vtable
|
||||
Type-directed resolution of a class method to its instance body; in
|
||||
AILang it is resolved statically by [[monomorphisation]], never by
|
||||
runtime dictionaries or vtables.
|
||||
|
||||
### superclass
|
||||
**Avoid:** super-class, parent class
|
||||
A class constraint that another class requires of its instances.
|
||||
|
||||
## Effects
|
||||
|
||||
### effect set
|
||||
**Avoid:** effect row, effect annotation
|
||||
The explicit set of algebraic effects a function may perform, declared
|
||||
in its type. AILang has no effect-row variables, so the set is closed.
|
||||
|
||||
### effect-op
|
||||
**Avoid:** effect op, effect operation
|
||||
A single named operation of an effect (its perform site), whose
|
||||
signature may carry a `borrow`/`own` default.
|
||||
|
||||
## Kernel tier and codegen
|
||||
|
||||
### kernel-tier
|
||||
**Avoid:** kernel tier
|
||||
The privileged tier of modules (e.g. [[prelude]], `raw_buf`) that may
|
||||
carry [[intrinsic]] bodies and are auto-imported with bare-name
|
||||
visibility.
|
||||
|
||||
### prelude
|
||||
**Avoid:** —
|
||||
The [[kernel-tier]] standard module auto-imported into every module.
|
||||
|
||||
### intrinsic
|
||||
**Avoid:** compiler-supplied body
|
||||
A function whose body is marked `(intrinsic)` in a [[kernel-tier]]
|
||||
source and is emitted by a codegen [[intercept]] rather than written
|
||||
in AILang.
|
||||
|
||||
### intercept
|
||||
**Avoid:** —
|
||||
An entry in the codegen `INTERCEPTS` registry that supplies LLVM IR
|
||||
for an [[intrinsic]]-marked function; the registry and the
|
||||
`(intrinsic)` markers stand in a checked bijection.
|
||||
|
||||
### MIR
|
||||
**Avoid:** —
|
||||
The post-[[monomorphisation]] typed intermediate representation
|
||||
(`MirModule`) produced by `lower_to_mir`, sitting between
|
||||
type-checking and codegen.
|
||||
|
||||
## Embedding
|
||||
|
||||
### embedding ABI
|
||||
**Avoid:** embedding-ABI
|
||||
The stable C ABI for calling compiled AILang from a host language,
|
||||
shipped as a `staticlib`.
|
||||
Reference in New Issue
Block a user