The loft ontology

Status: hand-authored around generated splice regions (the errors.ts / CATEGORIES.md lifecycle, v0.3 session 1): §3 generates from the value-type enum in /packages/lang/src/schema/valuetypes.ts and §6 from the keyword registries in /packages/lang/src/parser/keywords.ts — edit the code and run pnpm gen:taxonomy; CI pins each marked region to its renderer. Per-category datum inventories stay in the category catalog — this file owns the axes; that file owns the per-category instances. (Folding CATEGORIES.md in was considered and kept separate, 2026-08-12: different readers — reference card while writing loft vs. constitution while writing the spec — and different ownership. The splice machinery now exists, so merging CATEGORIES as one more generated section is cheap and the question stays open as pure taste.) This file answers one question wherever it arises: what kinds of things exist in loft, and along which axes is each thing classified? When a spec section, error message, or design conversation needs a word for one of these, it uses this file’s word.

1. The identity ladder

Every placeable thing in a model resolves through the same four layers:

Layer	loft	What it is	Revit
Category	`door`, `wall`, `grid`…	The interface: a closed, spec-owned keyword set. Owns the required parameter core and the required datum projection.	Category
Component	(v0.4-era grammar)	The implementation: geometry recipes + internal logic behind an export membrane. System components (walls, floors, roofs) are compiler-built; authored components ship as `.loft` source — including the generic library.	Family (loadable ≈ authored; system ≈ system)
Type	`doortype 3070 …`	The partial application: a named parameter set that fixes some of the component’s parameters and delegates the rest.	Type
Instance	`door 3070 D1 in wall.W1 at 4'`	The call: a placement supplying whatever the type delegated.	Instance

component = function · type = partial application · instance = the call.
Every v0.3 type is a type of the built-in generic component (scaffolding with a designed retirement — SPEC-v0.3 §7 P2).
Declaration order is category → type → [id] → placement (decision 38); each category requires at least one of the two leading name slots.

Beside the ladder, not on it:

Declared datums (grid, level, future refplane): pure reference geometry — carriers with no recipe. Id required (being referenced is their entire job); type slot absent today, arrivable additively.
opening: the type-less, filler-less cutter. Id optional (an element, not a datum); no type, ever — a product-shaped hole is a component’s cutter, which is a recipe role, never an element.
Projected datums (wall.W1.end, door.D1.jamb): not declared things at all — the datum surface every element exports, per the category’s projection rule. Inventory: the category catalog.
Placement is a how-to, not ontology: Placing elements walks the methods — a plane, a line, a point, a wall host, a loop — with the slots each one takes.

2. Parameter axes

Every parameter is classified along five independent axes. The first two exist in v0.3; the rest are settled direction with reserved arrival points.

Axis	Values (v0.3 in bold)	Notes
Vocabulary	spec (bare: `width`) · user (`u-` prefix)	The prefix is provenance, visible in every schedule and diff.
Binding	type-fixed · instance-authored (delegated via `instance`)	The category requires; the type chooses; the instance is checked.
Value source	authored text · model-derived (future)	Model-derived = Revit reporting parameters (host wall thickness, height from base/top levels). `boundAt` records the source.
Visibility	(all public in v0.3) · exported · internal (component era)	Exported = API, breaking-change-tracked; internal = implementation, renameable.
Mutability	authored · computed (component era)	Computed exports (formwork area, concrete volume) are read-only query targets.

Requiredness is a per-parameter fact governed by the requiredness ratchet (decision 45): authority descends category → component → type → placement, and each rung may tighten optional → required for what it governs, never loosen. The category holds the core (every door has width, height); a type may demand a delegated u- parameter of every placement (u-hardware instance text required — omission is D0515); the future param statement (project-profile rung) demands at project scope; components join with their own vocabulary — including the category’s optional words (a door’s sill, a part number), which stay spec-typed even when unenforced — in their era.

3. Value types

The closed set is the type system. Fixed parameters infer their value type from the literal; the unification rule (“one name, one value type, per component” — SPEC-v0.3 §6.3, rendered per category while types apply the built-in generics) makes that inference safe. Both facts require the literal grammar to be a closed, enumerated list: an unenumerated value type is undefined behavior, so this table is normative — and generated from the enum the parser enforces (/packages/lang/src/schema/valuetypes.ts).

v0.3 ships

Type	Literal	Example	In the dimensional algebra?
length	imperial literal, unquoted	`3'-0"`, `3/4"`	Yes (decision 20)
boolean	`true` / `false`, unquoted	`true`	No
text	quoted, always	`"BHMA set 3"`	No

The lexical law (why length never confuses with text)

Text is always quoted. No exceptions, no bare words.
Unquoted values must lex as exactly one non-text literal form (length, number, boolean). 3'-6" is a length; "3'-6in" is text that mentions one — strings have no escape sequences (the tokenizer ends text at the next "), so a length inside text uses the word-suffix spelling (in/ft), which is already first-class.
Nothing ever falls back to text. An unquoted token matching no literal form is an error with a did-you-mean — never a guessed string. (The YAML cautionary tale: unquoted-scalar guessing turns no into false. loft never guesses.)
Delegated declarations state the type by name (instance text) because there is no literal to infer from; the stated name must be a row in this table.

The growth law

The set grows by versioned addition, and a new value type may only claim literal spellings that were previously errors — never reinterpret a spelling that already means something. (Adding 45deg is legal: it lexes as nothing today. Making bare words mean text is illegal forever: it would reinterpret every typo.)

Reserved roadmap (each with its motivating case)

Type	Motivating case	Arrival
area	computed formwork sqft; algebra product length × length	falls out of the dimensional algebra with computed params
volume	computed concrete CY; area × length	same
angle	future non-orthogonal work, sketch grammar	curves/profiles era
number	counts and durations, each with its unit (`90 min`, `2 hr`); struck 2026-09-17 because no literal may spell a bare number	the `duration` / count era
datum reference	column `base`/`top` (a level, a plane)	component era
material reference	a layertype’s material slot; the material vocabulary is closed and keyed by MasterFormat number (PARKINGLOT wall-assembly entry, 2026-08-17)	layers/registry era
component reference	sub-components (hardware sets)	registry era

Reference-valued parameters store the reference plus the resolved target (principle 3), and ride the shared resolution chain.

4. The governance ladders

Two ladders, often conflated because both get called “the ladder.” They answer different questions.

4a. The declaration ladder — where does a definition live? (3 rungs)

Every nameable definition (profile, type, eventually component) climbs the same three rungs, each migration a mechanical “extract and name”:

Inline — sketched anonymously in the using declaration (a rectangular profile implied by width 3' height 7'). Local, zero ceremony.
Project-declared — named at project scope (doortype 3070 …, profile ARCH-TOP …, the walltype pattern). Reusable, diffable, one source per model.
Registry — imported from a package (import { DBL-9070 } from "@registry/…"), version-pinned, vendor-owned.

Rung 1 → 2 is the extract-named-thing refactoring; rung 2 → 3 is publishing. Nothing about a definition’s meaning changes as it climbs — the rung is distribution, not semantics.

4b. The vocabulary governance ladder — who owns which words?

For parameters and datums alike (one ladder, two columns), authority descends, and each level may only add, never redefine:

Spec / category core — the format’s own law: every door has width, height, projects centerline · head · jamb. Closed, guaranteed, tools may assume it blind.
Project profile — additive-only project law (“every door on this job needs u-fire-rating”); the future param declaration statement. Liskov-governed: a profile may demand more, never less or different.
Component/type — author-added vocabulary (u- parameters, custom datums), binding level chosen here (fix vs delegate), exported-vs-internal chosen here (component era).
Instance — supplies values for whatever was delegated; declares nothing.

The u- prefix marks vocabulary owned below the spec rung, and its typing scope follows its owner: unification runs at the declaring component’s scope (“one name, one value type, per category” in v0.3, where every type applies the built-in category component) — which keeps rung-3 freedom type-safe without rung-2 ceremony. Rung 2 (param) is what grants a name one identity across categories: the shared-parameter tier, where a BIM manager pins the type and requiredness once and the cross-category schedule column becomes legitimate.

5. Datum kinds and selectors (pointer)

Datums classify by kind (plane, line, level — the decision-20 kind algebra, orientation-worded) and resolve through selectors in two families: geometric (resolved from the referencing statement’s own frame: bare jamb) and operational (resolved from the referent’s declaration: jamb.near, hinge). Per-category inventories, the required cores, and the projection rule live in the category catalog and SPEC-v0.2 §6.3 — this file only fixes the axis names.

6. The keyword registry

Generated from /packages/lang/src/parser/keywords.ts and the category catalog — the registries the parser enforces. A statement keyword is claimed (real grammar) or reserved (errors with a teaching message naming its future, never a generic syntax error). Reserved value words are contextual: legal only in the slots that define them, the reserved-word error everywhere else. Reserved parameter words are the catalog’s rows with an era (schema/categories/): clause words a statement refuses with a teaching message naming their future (D0274), at the rung the row names. Claimed statement keywords: project · units · level · grid · walltype · doortype · windowtype · wall · door · window · opening · room · roomline · viewtype · view

Reserved statement keywords

Word	Reserved for
`import`	imports and the package registry
`export`	exports
`const`	declared constants
`component`	component definitions — the family layer, where doors, windows, and furniture are authored as source and every type applies one
`refplane`	reference planes
`section`	section views — a view kind: view section S1 at grid.B to grid.A
`elevation`	elevation views — a view kind: view elevation E1 at grid.1 - 10’ to grid.3
`detail`	detail views
`sheet`	sheet generation
`schedule`	schedules
`floortype`	floor types
`rooftype`	roof types
`hatchtype`	hatch pattern types
`materialtype`	material types
`layertype`	assembly layer types
`floor`	floor elements
`roof`	roof elements
`ceiling`	ceiling elements
`stair`	stair elements
`ramp`	ramp elements
`railing`	railing elements
`curtainwall`	curtain walls
`mullion`	curtain-wall mullions
`shaft`	shaft openings
`column`	structural columns
`beam`	structural framing
`brace`	structural bracing
`foundation`	foundations
`slab`	structural slabs
`truss`	trusses
`duct`	ductwork
`pipe`	piping
`conduit`	electrical conduit
`cabletray`	cable trays
`sprinkler`	fire protection
`fixture`	fixtures
`equipment`	equipment placement
`furniture`	furniture placement
`casework`	casework
`site`	site elements
`topo`	topography
`parking`	parking elements
`planting`	planting elements
`area`	area schemes
`arealine`	area boundary lines
`zone`	zones
`space`	space elements
`mass`	massing studies
`group`	element groups
`assembly`	assemblies
`part`	parts
`tag`	tags
`dimension`	dimensions
`annotation`	annotations

Reserved value words

Word	Meaning
`instance`	the delegation word in type declarations — the value comes from each placement
`required`	the requiredness marker on delegated type parameters — every placement must supply the pair

Reserved parameter words

Word	On	Meaning	Waits for
`stack`	level	which sequence of levels this one belongs to — `above` then defaults within it	a real interleaved-sequence model (a garage’s 8’ levels beside the podium’s 10’ ones)
`label`	level, wall, opening, door, window	what the tag prints when it is not the id	a bubble or tag printing text other than the id — the grid’s bubble is the one that ships
`function`	wall	what the wall does in the building (Revit’s Function)	the wall worksheet’s second pass — decided at decision 65(e), not yet a clause
`structural-usage`	wall	whether the wall bears, shears, or neither (Revit’s Structural Usage)	the structure era
`room-bounding`	wall	whether the wall bounds rooms — today every wall does	the furred or decorative wall that must not bound a room; bounding is per story since decision 74
`phase`	wall, opening, door, window, room, roomline	the phase this element is created in	the phasing era — phases are an ordered list declared in their own file, and a view looks at the model as of one
`demolished`	wall, opening, door, window, room, roomline	the phase this element is demolished in	the phasing era — phases are an ordered list declared in their own file, and a view looks at the model as of one
`fire-rating`	doortype, windowtype	the assembly’s fire rating — drawn, not just scheduled (NCS ships nine fire-rating linetypes)	the `duration` value type (`90 min`, `2 hr`) — every parameter value carries units; until then the corpus spells it as text, `u-fire-rating "90"`
`hardware-set`	doortype, windowtype	the hardware set the leaf carries	the door worksheet — `u-` today, a built-in candidate then
`kind`	doortype, windowtype	which kind of leaf the type is — the category’s declaration lists them	a second kind of leaf — the door’s and the window’s declarations list what is coming (D0242)
`level`	room	the per-room level override — the walls’ `base` analog, for the room that differs from its file	a room that differs from its file’s level
`department`	room	identity data (Revit’s Department)	`roomtype`, or `u-` on categories
`occupancy`	room	identity data (Revit’s Occupancy)	`roomtype`, or `u-` on categories
`units`	viewtype	how derived quantities display on this sheet — units are presentation, never a fact about the model	the metric / areas era — a tier on the view ?? viewtype ?? project cascade
`phase`	view	the phase the query looks at the model as of	the phasing era — the phase filter, discipline’s twin (a filter on the query, never a kind)
`discipline`	view	the discipline the view reads the model as (structural, mechanical…) — a filter on the query, and the graphic standard’s cell beside scale	the views/filters era — phase’s twin (a filter on the query, never a kind); object styles stay one standard, the view’s discipline picks the resolver cell the way its scale does

Change protocol: hand-authored sections ride spec PRs; generated sections are edited only through their source modules and pnpm gen:taxonomy — same law as the category catalog. Never let this file and the code disagree silently.

Start here

Categories

Reference

Examples

The loft ontology

1. The identity ladder

2. Parameter axes

3. Value types

v0.3 ships

The lexical law (why length never confuses with text)

The growth law

Reserved roadmap (each with its motivating case)

4. The governance ladders

4a. The declaration ladder — where does a definition live? (3 rungs)

4b. The vocabulary governance ladder — who owns which words?

5. Datum kinds and selectors (pointer)

6. The keyword registry

Reserved statement keywords

Reserved value words

Reserved parameter words

​1. The identity ladder

​2. Parameter axes

​3. Value types

​v0.3 ships

​The lexical law (why length never confuses with text)

​The growth law

​Reserved roadmap (each with its motivating case)

​4. The governance ladders

​4a. The declaration ladder — where does a definition live? (3 rungs)

​4b. The vocabulary governance ladder — who owns which words?

​5. Datum kinds and selectors (pointer)

​6. The keyword registry

​Reserved statement keywords

​Reserved value words

​Reserved parameter words

1. The identity ladder

2. Parameter axes

3. Value types

v0.3 ships

The lexical law (why length never confuses with text)

The growth law

Reserved roadmap (each with its motivating case)

4. The governance ladders

4a. The declaration ladder — where does a definition live? (3 rungs)

4b. The vocabulary governance ladder — who owns which words?

5. Datum kinds and selectors (pointer)

6. The keyword registry

Reserved statement keywords

Reserved value words

Reserved parameter words