The Charter

A machine is one of Shoddy's standard libraries: a file of related words, where a word is Shoddy's name for a function. The mathematical machines — alg, eng, ephemeris, fin, geo, julian, lin, math, matrix, neural, random, sparse and their neighbours — grew one at a time. Each new one copied the last one's discipline. This page writes the shared discipline down. Nothing here is new: every clause was lifted from a shipped machine's header, and its origin is named, so each rule reads as observed practice rather than invented policy. A new mathematical machine states its position on each clause in its own header. An existing one is edited only when other work touches it anyway.

The eleven clauses

1. Pure throughout, and impure edges are named. Pure means a word computes its answer and changes nothing else. Every word answers a value. A machine with an unavoidable effect names that effect and isolates it. SpShow in sparse, neural's two random edges, and random's whole surface are those edges — each documented as the exception it is.
2. The surface is closed and prefixed. The surface is the set of names a machine makes public. Every word, type, variant and field in it carries the machine's prefix. eng and fin state this rule. geo proves it on fields, because an accessor — the word that reads one field out of a record — loses every naming contest. math, seq, str and matrix are the grandfathered base vocabulary: they shipped before the rule and keep their bare names. The grandfathering is a boundary, not a licence — no new bare name anywhere.
3. Solvers refuse rather than mislead (eng, lin, fin). A solver is a word that hunts for a numeric answer. A bracket — the interval known to contain the answer — is checked before descending. A singular system — one with no single solution — stops. A plausible number for an impossible question is the worst failure available.
4. Never compare computed values with =. A computed value carries tiny rounding errors, so = on it can lie. A machine owning a computed type offers the one honest comparison — EngCNear, GeoNear, AlgEqual — and its header says why. julian is the counter-case that proves the rule: dates are whole-number arithmetic, so = is honest there, and the header says that instead.
5. Angle policy is stated, per machine. Radians and degrees are the two ways to measure an angle, and radians are the mathematician's unit. Radians serve the mathematics (the builtins, eng). Degrees serve where the world writes degrees (geo, and ephemeris after it). The rule is not one policy. The rule is that the header states the policy and the reason, and conversions live at the machine boundary, never mid-formula.
6. Coefficients are highest power first (eng, lin). A coefficient is a number standing in front of one power in a polynomial — a formula built from powers of x. Highest power first is the one convention a caller gets backwards silently.
7. Ceilings are stated where they bite (eng, alg, lin, fin). A ceiling is a built-in limit: 2⁵³ — the largest whole number the Number type holds exactly — overflow bounds, iteration limits, dimension limits. A ceiling that produces a plausible wrong answer is documented at the word, not the header alone.
8. Scale is stated honestly. “Classroom-sized” (fin, neural, lin) is a design point, not an apology. Saying it up front is what stops a caller discovering it under load.
9. A public word exists once. A builtin — a word built into the language itself — is documented in exactly one machine; math and random split Seed from Rnd this way. A capability the tree needs twice becomes a shared machine; julian is the calendar that fin and geo each briefly carried. A private three-line helper duplicated inside another machine's body is that machine's business — fin's bisection, geo's list vectors, the two suns — but it is tested where it can drift, never merely trusted.
10. Includes point down the layer map, and every edge is stated in the header. An include is how one machine pulls another machine's words into itself. Sideways composition uses builtin types as the bridge: alg and eng compose through quotations — pieces of code passed around as values — with no dependency either way. The graph is acyclic — no machine's includes ever loop back to it — and shallow.
11. Refusal classification is bool's three-way split, family-wide. A bug in the caller aborts via Error, naming the word. External input answers Result with a 1-based position — counting from one, not zero. Absence answers Option. A word that aborts has its total twin defined under it; a total word always answers instead of aborting. GeoAt sits over GeoTryAt, and JulOf over JulTryOf — one set of rules, not two.

The layer map

Includes point downward. A machine slots into the map. It does not reshape it.

Physics does not appear in the table, on purpose. The family is the physics library, and the atlas maps the curriculum onto it rather than adding a machine that would re-own words a dozen machines already publish.

One public vector spelling

A vector — a row of numbers treated as one quantity, like a direction in space — crossing a public surface is an Array Of Number. matrix owns the element arithmetic (Dot, VAdd). lin owns the geometry (LinCross, LinNorm). A subject machine reuses those rather than growing public twins. The one grandfathered exception is GeoEcef, which answers a List Of Number and stays — repairing it would break a shipped surface to gain no capability. It is recorded here so it is a boundary, not a precedent.