%unimsg 0 vocab/vocabularies/v0 -- The index of this directory, written in the documentation vocabulary and -- rendered to vocab/README.md by tools/readme. documentation @vocab/vocabularies/v0 { conforms -> @vocab/documentation/v0 title "The vocabularies" intro [ "A vocabulary says what a document's fields MEAN, so that a reader and a tool agree about a document neither of them wrote. Each one here is immutable: its hash names it, and a change is a new document that may declare this one its predecessor.", "A VOCABULARY IS NAMED BY ITS IDENTIFIER AND NOT BY ITS PATH. Documents in other repositories declare `@vocab/design/v0` and `@vocab/provenance/v0` today; moving a file into a subdirectory here does not touch them, and renaming an identifier would. The directories below are for people reading the list.", ] sections [ { heading "shapes — the shape of a whole document" body "What fields a document of this kind carries, and which are required. A gate reads these to refuse a document that asserts a field the renderer never implemented — which is the failure the documentation vocabulary was written after meeting." table [ | vocabulary identifier holds | "`shapes/documentation-v0.umsg`" "@vocab/documentation/v0" "a title, an introduction, and ordered sections" | "`shapes/design-v0.umsg`" "@vocab/design/v0" "an argument, with a spine a reader can trust" | "`shapes/issue-v0.umsg`" "@vocab/issue/v0" "a defect written so somebody else can disprove it" | "`shapes/provenance-v0.umsg`" "@vocab/provenance/v0" "what was vendored, from where, and what it hashes to" | "`shapes/vocabulary-v0.umsg`" "@vocab/vocabulary/v0" "the shape a vocabulary itself takes, so its consumers agree — tables bind, prose argues" ] }, { heading "libraries — decompositions over a vocabulary's kernel" body "NOT A VOCABULARY. A library declares element types as derivations over a kernel that already exists, so it adds nothing a generator must implement: expand the body, or substitute a native control whose tree matches the expansion. It is listed here because @vocab/ui/v0 rests its entire case for a small closed kernel on a library existing — `the kernel is what implementers owe; the library is what authors use` — and for as long as none did, a consumer met sixty primitives and concluded, reasonably, that the vocabulary could not express a real interface." table [ | document identifier holds | "`libraries/ui-lib-v0.umsg`" "@library/ui/v0" "the widgets a modern interface expects, decomposed into @vocab/ui/v0's kernel — a card, a chip, a rating, an icon-button, a date range, a drawer and twenty-odd more" ] after "A DOCUMENT REACHES A LIBRARY THROUGH `uses`, and the tool supplies the bytes — `uigen DOC.umsg -lib LIBRARY.umsg`. See docs/29-ui-capability-audit.umsg for what was missing before this existed, which was more than the library itself." }, { heading "qualifiers — annotations that qualify a statement" body "Not a document shape: a word written in front of a value, which the format already calls a qualifier and which can be nothing else. These compose with any document of any shape." table [ | vocabulary identifier holds | "`qualifiers/conformance-v0.umsg`" "@vocab/conformance/v0" "which sentences bind an implementer, and which are the reasoning around them" | "`qualifiers/units-v0.umsg`" "@vocab/units/v0" "what a quantity is measured in, written as the word in front of it" ] after "The units vocabulary is where F19 landed, and it shows the division these two directories are for: the SHAPE of a unit is normative in the specification, because a shape can be fixed once and checked everywhere, while the SET of units is a choice a document makes and lives here. F22 went the other way entirely — a time of day turned out to be a hole in the lexer, and no vocabulary can fill a hole in the lexer." }, { heading "policies — how a vocabulary's documents merge" body "Not a vocabulary: one @vocab/merge-policy/v0 document per vocabulary, saying which of its sequences merge per member and by what identity, which of its values are derived, and which of its texts merge by hunk. The three-way merge (policy/three-way-merge/v0, docs/merge-policy-v0.umsg) reads them and infers nothing a policy does not say. docs/merge-identity-audit.umsg says what each vocabulary lawfully identifies and what applications must allocate when they author." table [ | policy identifier governs | "`policies/genealogy-merge-v0.umsg`" "@policy/merge/genealogy/v0" "@vocab/genealogy/v0" | "`policies/rich-document-merge-v0.umsg`" "@policy/merge/rich-document/v0" "@vocab/rich-document/v0" | "`policies/spreadsheet-merge-v0.umsg`" "@policy/merge/spreadsheet/v0" "@vocab/spreadsheet/v0" | "`policies/graphic-merge-v0.umsg`" "@policy/merge/graphic/v0" "@vocab/graphic/v0" ] }, { heading "subjects — describing something in the world" body "Neither the shape of a document nor a qualifier on a statement: the vocabulary of a subject, for documents that describe one." table [ | vocabulary identifier holds | "`subjects/language-v0.umsg`" "@vocab/language/v0" "a whole grammar, with the categories declared rather than assumed" | "`subjects/program-v0.umsg`" "@vocab/program/v0" "experimental executable instruction trees and linked source modules; text parser, canonical formatter, binary codec and state-machine examples generated into Python, JavaScript, Java 17 and Dart" | "`subjects/workflow-v0.umsg`" "@vocab/workflow/v0" "reusable structured processes with carried executable semantics, human tasks, forks, waits, actions and pinned subworkflows; Python and JavaScript conformance" | "`subjects/workflow-instance-v0.umsg`" "@vocab/workflow-instance/v0" "one pinned execution, activation scopes, task receipts and durable pending requests" | "`subjects/workflow-event-v0.umsg`" "@vocab/workflow-event/v0" "accepted observations and exact input/result identities for replay" | "`subjects/workflow-host-v0.umsg`" "@vocab/workflow-host/v0" "explicit local persistence, identity membership, validation and document delivery bindings" | "`subjects/workflow-inspection-v0.umsg`" "@vocab/workflow-inspection/v0" "engine-derived active work, instructions, required roles and blockers" | "`subjects/linguistic-comparison-v0.umsg`" "@vocab/linguistic-comparison/v0" "executable segment-distance rules with declared tokenisation, variant coverage, exact costs and edit traces" | "`subjects/phonological-features-v0.umsg`" "@vocab/phonological-features/v0" "shared segment descriptions: the feature system two phonologies are compared in, declared once so a distance rule reads both the same way" | "`subjects/lexicon-v0.umsg`" "@vocab/lexicon/v0" "a word, its meanings, and the paradigm that inflects it" | "`subjects/ui-v0.umsg`" "@vocab/ui/v0" "one user interface, described so precisely that a generator can build it" | "`subjects/diagram-v0.umsg`" "@vocab/diagram/v0" "one diagram, stored exactly, with the proposition it makes attached to the marks that make it" | "`subjects/graphic-v0.umsg`" "@vocab/graphic/v0" "artwork stored exactly, with nothing required to mean anything" | "`subjects/ruleset-v0.umsg`" "@vocab/ruleset/v0" "the rules of a game, written so a machine can play them and carrying the positions that prove it" | "`subjects/board-presentation-v0.umsg`" "@vocab/board-presentation/v0" "the binding between a ruleset's squares and a picture, read in both directions" | "`subjects/rich-document-v0.umsg`" "@vocab/rich-document/v0" "one formatted document — its structure, its type, its fonts, its tables, its navigation and its fields — stored so the formatting is a fact rather than a rendering" | "`subjects/work-v0.umsg`" "@vocab/work/v0" "many documents read as one — a pinned spine, the counters that run through it, and the navigation derived over all of them" | "`subjects/spatial-v0.umsg`" "@vocab/spatial/v0" "a scene in three dimensions — a declared frame graph every coordinate names, the geometry and bodies placed against it, and the precision the whole thing is recorded to" | "`subjects/building-v0.umsg`" "@vocab/building/v0" "draft physical building semantics — spaces, shared boundaries, fabric and representations; Atria is a prospective consumer, not the model's limit" | "`subjects/body-envelope-v0.umsg`" "@vocab/body-envelope/v0" "oriented geometric boxes with explicit reference points, directional margins and exact placement; no collision or person-model claim" | "`subjects/indoor-navigation-v0.umsg`" "@vocab/indoor-navigation/v0" "draft directed passages, destinations and anchors over pinned buildings, with scoped fact assessment rather than accessibility claims" | "`subjects/access-policy-v0.umsg`" "@vocab/access-policy/v0" "scoped class permissions, timed windows and deny precedence with executable portable decisions; no identity or unlocking claim" | "`subjects/motion-v0.umsg`" "@vocab/motion/v0" "where a scene's frames were, instant by instant, in a block beside the scene rather than a second file" | "`subjects/animation-v0.umsg`" "@vocab/animation/v0" "what a graphic looked like tick by tick, in a block beside the artwork rather than a second file — one sample per tick, so nothing between two samples is ever computed" | "`subjects/choreography-v0.umsg`" "@vocab/choreography/v0" "what artwork was ASKED to do and when — an authored timeline of verbs over named performers, declaring no rate, which lowers to a take at whatever rate a consumer chooses. Every ease is a polynomial, so the bake is reproducible rather than merely close" | "`subjects/sound-v0.umsg`" "@vocab/sound/v0" "a sampled signal stored as its samples — typed arrays of frames by channels at a whole-number rate, with tiers of labelled spans addressed by frame, so an alignment is an integer and never a rounded time. It may place itself on a film's clock" | "`subjects/encyclopaedia-v0.umsg`" "@vocab/encyclopaedia/v0" "one entry about one subject — the facets it is classified on, the sourced and dated claims that make it comparable, and the prose that explains them" | "`subjects/measurement-v0.umsg`" "@vocab/measurement/v0" "measured data on named axes — typed arrays checked against the axes they are laid out on, a unit per variable as one word, an uncertainty in one of five forms, and the source the numbers came from" | "`subjects/chemistry-v0.umsg`" "@vocab/chemistry/v0" "chemical entities, structures, samples, spectra, reactions and calculations — explicit models and evidence, with a pinned CML inventory and separate retention and native-projection contracts" | "`subjects/git-repository-v0.umsg`" "@vocab/git-repository/v0" "one git repository at one instant — the object database as parsed objects that re-serialise to their own names, the refs over it, the index, the config and the reflogs" | "`subjects/patch-v0.umsg`" "@vocab/patch/v0" "one change to one document — the base and the result both pinned by digest, and every operation carrying the value it displaced so that the change inverts" | "`subjects/merge-v0.umsg`" "@vocab/merge/v0" "a three-way merge in review — base, ours and theirs pinned by digest, the conflicts left to decide with all three operands and a structured location, and the choices made so far; never the merged document" | "`subjects/merge-policy-v0.umsg`" "@vocab/merge-policy/v0" "how one vocabulary's documents merge — which sequences have members with a lasting identity and what it is, which values are recalculated rather than chosen, and which texts merge by hunk" | "`subjects/archive-v0.umsg`" "@vocab/archive/v0" "files, their attributes and their history in one document — objects named by their own encoding, and the ownership, permission bits and empty directories git structurally cannot record" | "`subjects/genealogy-v0.umsg`" "@vocab/genealogy/v0" "what the records say, what the researcher concluded, and the argument between them — a persona per record, a search that found nothing, and a basis on every parentage" | "`subjects/presentation-v0.umsg`" "@vocab/presentation/v0" "how a document of some OTHER vocabulary is displayed — a view bound to it, emitting an interface, a picture or a document, and inheriting that codomain's equality rather than declaring one" | "`subjects/spreadsheet-v0.umsg`" "@vocab/spreadsheet/v0" "a workbook — named columns and named cells, a formula as a closed tree rather than a string, the value every formula resolved to carried beside it and refused when the two disagree, and a chart placed on the grid as a presentation view" | "`subjects/information-model-v0.umsg`" "@vocab/information-model/v0" "what a body of data is — entities whose attributes are record rows, identity, binary relationships with a role and a multiplicity at each end, specialisation and sample rows checked against all of it — stated once so every diagram, dialect's DDL and language's code is a projection of it" | "`subjects/time-zones-v0.umsg`" "@vocab/time-zones/v0" "a time zone database — each zone's local time types, the UTC instants it switched between them, and the POSIX rule that continues after the last, with every name for a zone on its row" | "`subjects/sql-recording-v0.umsg`" "@vocab/sql-recording/v0" "what a SQL server replied to each statement of a script — rows as text, errors as SQLSTATE and fields, notices in the order they came — kept as an oracle another implementation replays" ] after "THE TWO ARE OPPOSITES ON THEIR CENTRAL DECISION, and the reason is worth carrying here rather than in either document. The language vocabulary fixes no inventory, because its reader is a linguist who can meet a declared category and think about it. The interface vocabulary fixes a closed kernel, because its reader is a code generator, which cannot — and which silently drops the control it does not recognise. Same repository, same mechanisms, opposite answer, and the difference is entirely in who is reading. THE INTERFACE VOCABULARY ALSO EXPECTS COMPANION DOCUMENTS: a target profile per toolkit, saying what that build has and what it resolves the appearance tokens to. Two are in `profiles/` — `ui-target-web-v0.umsg`, `ui-target-flutter-v0.umsg` and `ui-target-lvgl-v0.umsg`. They are not vocabularies; they describe a tool rather than a document, and they will earn a directory of their own when there are three. AND `profiles/` NOW HOLDS A SECOND KIND OF COMPANION, worth naming because the two are easy to confuse. A TARGET profile describes a RENDERER — what that build can do, what it resolves tokens to. An AUTHORING profile describes a DOCUMENT — a declared subset the document claims to stay inside. `rd-profile-prose-v0.umsg` is the first of the second kind: the rich-document tree with the measurement layer refused, for documents whose author has no opinion about type. It exists because the ask that produced that vocabulary asked for embedded fonts, a font implies a size, and everything downhill of that is right for a word processor and wrong for the enhanced markdown the same ask was also reaching for. One vocabulary, one shape, two ways to write in it. AND A THIRD KIND ARRIVED WITH THE GENEALOGY VOCABULARY: `gen-target-usrah-v0.umsg`, which describes a CONSUMER rather than a renderer. It says, per construct, whether that build reads, authors, preserves or cannot represent it — and states the alternative wherever it cannot, because the vocabulary's semantic rules forbid dropping a construct silently. It answers the question a user of any genealogy program has never been able to ask: what did this thing do with the part of my document it does not understand. See also `mappings/genealogy/`, which maps the two formats that build already holds: `gedcom-v0.umsg` for its corpus, and `uncertainties-v0.umsg` for a record matcher's scored candidates and the human verdicts on them — a file that arrives already shaped like the identification layer, from a tool written against none of this. THE LAST TWO ARE A PAIR, and the split between them is the same one this directory keeps making. A ruleset says what is LEGAL and never what it looks like; a graphic is a resolved picture and cannot change when a piece moves. board-presentation is the function between them — a square size, two fills, a glyph per piece kind — and it is a third document rather than a section of either, because a rule that changed when somebody restyled a board would be the wrong kind of thing. THE DIAGRAM VOCABULARY IS A SIBLING OF THE INTERFACE ONE AND NOT A PART OF IT, which is worth saying here because the obvious guess is wrong. An interface's equality deliberately EXCLUDES appearance; a diagram's content IS appearance. The load-bearing decision inverts, so a diagram is referenced from an interface — through `:image` and its `:source`, needing no change to either — rather than carved out of it. Its gate and its invariants are checked by `tools/dgcheck`, which draws nothing: every rule in it is arithmetic over exact decimals, so it runs in a build. THE GRAPHIC VOCABULARY IS A THIRD SIBLING, for artwork that asserts nothing: same drawing kernel, no semantic layer, and the compressions a 2 MB file needs — ramps, a style table, transforms and a flat path encoding. `tools/gcheck` gates it and `tools/svg2umsg` imports SVG into it. What that conversion measured — about size, speed and exactness, and about a quadratic in this repository own lexer — is docs/26. THE RICH DOCUMENT VOCABULARY IS THE FOURTH IN THAT FAMILY, and it is a sibling of the INTERFACE one on the decision that vocabulary is built on. @vocab/ui/v0 refuses measurement because there is no one screen, and it is right; a page is 210 by 297 millimetres, so this one requires measurement. Everything else is borrowed rather than rebuilt — a figure reaches @vocab/graphic/v0, a form field IS a @vocab/ui/v0 element, a length is a @vocab/units/v0 qualifier, and an anchor is the format's own identifier, so in-document navigation needed no key at all. Its argument is docs/36, and docs/37 audits it against twelve document formats. @vocab/work/v0 IS THE FIFTH AND IT HOLDS NO CONTENT. It came out of that audit's largest finding: one document is one file, and a book, a manual and a journal issue are all several. So a work is a RELATION between documents — a spine pinned by hashes, the counters that continue across it, and one navigation over all of it — which is the same answer @vocab/board-presentation/v0 gives about a ruleset and a picture. A work may not change a member, because a member is named by its hash. Its argument is docs/38. THE LAST TWO ARE A THIRD PAIR OF THE SAME KIND, in three dimensions. @vocab/spatial/v0 says what exists and where it may articulate; @vocab/motion/v0 says where it actually was — as a BLOCK BESIDE IT in the same document, so a converted character is one file as its source was, with the pinned separate-document form kept for the clip that must outlive one scene. ITS SPINE IS ONE DECLARED FRAME GRAPH doing five jobs at once: a scene graph, a skeleton, a kinematic chain, a sensor rig and a georeference. Its argument is docs/41, and docs/42 is the falsification, run against five formats BEFORE the vocabulary was written rather than after. That audit found the thing neither document expected: exact decimals are not enough in three dimensions, because a rotation leaves them — so a spatial document must declare the PRECISION it records to, and the transcript is rounded onto it. That closes a question docs/26 parked for artwork. @vocab/encyclopaedia/v0 IS THE NEWEST AND ITS SUBJECT IS ANYTHING AT ALL, which no other vocabulary here can say. One document is one entry, and an encyclopaedia is a @vocab/work/v0 over many of them — the answer docs/38 already gave about books. ITS LOAD-BEARING DECISION IS THAT THE FACTS AND THE PROSE ARE ONE DOCUMENT UNDER ONE GATE. Twelve formats were read and not one carries a sourced, dated value beside the paragraph that explains it: Wikipedia has the prose and a template, Wikidata has the statement and no prose, and the two are free to disagree with nothing able to represent the disagreement. So a claim here is refused without a source and a temporal property is refused without a date, and where sources disagree the entry carries both values and declares neither of them the winner. ITS CLASSIFICATION IS TWO AXES AND NOT ONE TREE, which is Ranganathan's finding of 1933 and is repeatedly un-learned: :kind says what the subject IS and :branches says what field it belongs to, because what a thing is does not determine what studies it. Nine branches and eighty-seven fields are closed in the vocabulary and the level below them is declared per document — the same division @vocab/language/v0 makes for features and @vocab/lexicon/v0 for semantic domains. Its argument is docs/45, and the risk that document carries is that no checker exists yet for the eighteen rules its gate states. @vocab/git-repository/v0 IS THE ONLY ONE HERE WHOSE SUBJECT CAN CHECK THE CONVERSION. Every other vocabulary in this directory asks to be believed about its fidelity — a person compares two pictures, or a checker written by the vocabulary's own author agrees with it. Git names every object by the hash of its own bytes, so a document holding a repository is checkable by anybody, against names the document did not choose, with no access to the original store. That is why it stores PARSED objects rather than opaque ones: the parse is free because the parse is checked. ITS COST IS MEASURED RATHER THAN ESTIMATED. This repository, whole, is 3,935 objects and 92.1 MiB packed; the document holding them is 182.2 MiB encoded, of which the structure — every key, table, hash and block — is 940,125 bytes. The rest is the objects, uncompressed and undeltified — and measurably right to be: an ordinary xz over that document is 69.8 MiB, a quarter SMALLER than the delta-compressed store it describes, so the delta grammar a pack needs would buy a loss. Its argument is docs/55, and the tools are `git2umsg` and `repocheck`. @vocab/patch/v0 IS THE PAIR TO IT AND WAS FOUND THE SAME WAY. A repository document answers what a store HOLDS; a patch answers what one change DID, and docs/56 found four separate needs asking for the same artefact — an editor's undo stack, a history asked by part rather than by line, a merge, and an edit that knows its own intent. ITS LOAD-BEARING DECISION IS THAT EVERY OPERATION CARRIES WHAT IT DISPLACED, so one field is both the precondition and the inverse: a patch cannot be applied to a document that drifted, and undo is the same list read backwards. It carries the digest of the document it produces, which caught a real ordering bug in its own emitter on the first run rather than by review. Its argument is docs/57, and the tools are `umsgdiff -patch` and `umsgpatch`. @vocab/presentation/v0 IS THE NEWEST AND IT IS THE ONLY ONE WHOSE SUBJECT IS ANOTHER DOCUMENT OF THIS DIRECTORY. It says how a document of some other vocabulary is DISPLAYED — a repository as a file tree and a commit list, a measurement as a chart, an entry's claims as a table beside its prose — and it is the generalisation of @vocab/board-presentation/v0, which is this idea at n=1 and says in its own words that it does not generalise. IT ADDS EXACTLY ONE THING TO THE VOCABULARIES IT DRAWS INTO: a third reference root, @subject, resolving into the bound document. Everything else was already in @vocab/ui/v0 — repetition, expressions, guards, a projection two generators agree on. It declares no elements, and it declares no EQUALITY: two consumers must agree under the codomain's own rule, which is why an interface's equality can exclude appearance while a graphic's is nothing else. One rule, two subjects: a document is compared on what it asserts. ITS THREE PLACEMENTS ARE THE POINT. A view inside a VOCABULARY is what a document of that kind looks like when nobody said otherwise; a view beside the DATA overrides it; a view pinned by hash outlives both. And a document may already carry its own vocabulary, so a document carrying both can be checked and displayed by a reader that has never heard of either — which is the question no other vocabulary here answers: what happens when a document outlives its registry. IT WAS READ OFF THREE TRIALS RUN BEFORE IT WAS WRITTEN, and each found something the design had not said: the scale residue and the bake onto a declared quantum, a commit order that is total and topologically wrong until it is both, and a join no reference can spell because a path segment cannot be computed. Its argument is docs/61. WHAT IT DECLINES is a hierarchy with several destination slots — an entry's prose body — because that needs a rule per source node kind, which is a MAPPING, and one already exists for that exact subject. Whether mappings should have a vocabulary and a coverage gate is docs/62." }, { heading "Why three directories and not one" body "Six documents in a flat directory is a list; twenty is a pile. The cut is by what a vocabulary GOVERNS — a whole document, a statement inside one, or a subject in the world — because that is the question somebody adding the seventh will be asking." }, ] }