Decision records

A decision record is a short note written on the day something was settled. It says what the situation was, what was decided, what that costs — and which sensible alternative was rejected, and why.

That last part is the one worth having. A codebase shows you what was built. It never shows you the three things that were nearly built instead, so the next person to have the same good idea has to rediscover on their own why it does not work. The records are where that is kept.

Each one has a number, which is just its filename and the order it was written in. Nowhere else on this site will you be shown one, because four digits are a footnote to a document you have not opened. Here they are the subject, so here they are.

The trail is never edited

When Loom changes direction, the old record is not corrected. It is marked as replaced, its text left exactly as it was, and a new record explains what changed and why the earlier reasoning no longer holds.

So a record can be in one of a few states, and the wording in the table below is the record's own:

State	What it means
Accepted	In force. This is how Loom works today.
Accepted — partially superseded by …	Still in force, except for the one part a later record took over. A record that answered several questions can be replaced in part; retiring the whole thing would lose more than it clarified.
Superseded by …	Replaced. Worth reading anyway — the reasoning that stopped holding is usually the interesting bit.
Proposed	Written, not settled. Waiting on a person.

The list

Newest last. The table is read from the repository when this site builds, so it is the same list a checkout has.

217 records. 202 in force, 5 superseded in part, 2 replaced outright, 8 proposed and waiting on a person.

Every title below opens that record’s file in the repository, marked ↗. They are working notes rather than pages of this site, and they read like it.

#	What was decided	Status
0001	The tree and the delta are the unit of AI-authored change	Accepted
0002	The Gate is a pure function of two independent axes	Accepted
0003	AI drafts a change; the runtime names what it creates	Accepted
0004	The model-facing schema is a projection, not the AST	Superseded by 0014
0005	Model access is a narrow seam with an optional adapter	Accepted
0006	A refused proposal gets exactly one repair attempt, and both halves are recorded	Accepted
0007	Confidence is self-graded, trusted on purpose, and must be calibrated	Accepted
0008	The renderer is a total, pure projection of the tree	Accepted
0009	Primitives receive AI-authored props in a bag, never spread	Accepted
0010	Edit mode decorates; it never invents DOM	Accepted
0011	A primitive declares its props, and the render seam enforces them	Accepted
0012	Conformance is probed and reported, never enforced by registration	Accepted
0013	The registry is what the model is told it may build	Accepted
0014	The reply schema must fit a compiled-grammar budget	Accepted — supersedes 0004
0015	The registry is generated from the directory, and a module's name is its type	Accepted
0016	The log is the truth and the snapshot is a materialised view	Accepted
0017	Every write goes through one server-side path	Accepted
0018	The portal is a consumer, not an insider	Accepted
0019	The portal is a review queue, not a design tool	Accepted
0020	A store handle is the scope, and a listing is a keyset page	Accepted
0021	A held proposal stays server-side, and an answer names its id	Accepted
0022	The backing store is Postgres, reached by SQL	Accepted
0023	Telemetry narrows the event stream and never copies the log	Accepted
0024	Emission never does IO, and the host flushes once	Accepted
0025	A journal page is taken from an end, and names both of its ends	Accepted
0026	The revision log is read a page at a time, from either end	Accepted
0027	Identity is server-derived, and its absence fails closed	Accepted — partially superseded by 0029
0028	A tree is auditable only if its host can reproduce the seed	Accepted
0029	The approval belongs on the revision, not only in the journal	Accepted — partially supersedes 0027
0030	The package ships compiled output	Accepted
0031	Calibration is a reader, not a controller	Accepted
0032	An undo is a proposal, not a rewind	Accepted — partially superseded by 0035
0033	The policy is resolved per change, and named on the verdict	Accepted
0034	A sign-in that cannot be counted is refused	Accepted
0035	Discarded work is a stake, and only the runtime may declare it	Accepted — partially supersedes 0032
0036	A table Loom creates is locked when it is created	Accepted
0037	The journal may forget, and only a whole episode at a time	Accepted
0038	An id names one node, and a return is not a reuse	Accepted
0039	The attempt log is counted, never enumerated	Accepted
0040	A failure names the actor who must clear it	Accepted
0041	Authorship is derived from the log, not carried on a node	Accepted
0042	A sink observes, and the runtime contains it	Accepted
0043	A revision is a position a caller may name	Accepted
0044	A move relocates a subtree, and the analysis measures the subtree, not the phrasing	Accepted
0045	A telemetry field added later is optional, and never defaulted	Accepted
0046	A render test crosses no boundary the framework would not	Accepted
0047	A verdict belongs to the gate that reached it	Accepted
0048	A policy's name is checked by a fingerprint stored beside it	Accepted
0049	A theme is three registered ids, carried in the tree	Accepted
0050	The runtime's props are namespaced, and the root primitive mounts the theme	Accepted
0051	A slot is a region the primitive places, not content inline in its children	Accepted
0052	A repeated item is a node; a fixed field is a prop	Accepted
0053	A URL in the tree is checked against a scheme allowlist	Accepted
0054	A container is its child's name plus the arrangement it puts them in	Accepted — partially superseded by 0061
0055	Motion is a static stylesheet the primitive emits, never a prop in the tree	Accepted
0056	The demo is public, and shares nothing with the portal but the deployment	Accepted
0057	A demonstrated change is a deterministic interpreter, not a script beside the runtime	Accepted
0058	A binding is a question the tree asks, answered before the walk	Accepted
0059	A leaf whose whole content is one string takes it as a child	Accepted
0060	A primitive owns a string, and a deployment may replace it	Accepted — partially superseded by 0063
0061	A suffix that names the markup earns its place; a suffix that names the parent does not	Accepted — partially supersedes 0054
0062	A general arranger is named for the arrangement alone, and a named band wins where one exists	Accepted
0063	A declared string travels with the primitive; a dictionary is what a host adds	Accepted — partially supersedes 0060
0064	A primitive says whether it is a target, and the Gate derives the nesting	Accepted
0065	A submission names a destination, and never carries one	Accepted
0066	A card is the target when it is read; the control is the target when it is acted on	Accepted
0067	The four surfaces are one application, and a route group is a lane	Accepted
0068	A primitive is a target when the reader aims at the whole of it	Accepted
0069	A root-relative path is a destination a tree may name	Proposed — ARCHITECTURAL, needs review. It contradicts a clause
0070	The portal is a segment, and the marketing site is the front door	Accepted
0071	Moving a form's destination is a stake of its own	Accepted
0072	A page paints its ink and its canvas together, or neither	Accepted
0073	A form with nowhere to post renders disabled, and says so	Accepted
0074	A palette slot that carries text meets AA, and the palette moves rather than the bar	Accepted
0075	A primitive is audited under every shape its schema closes over	Accepted
0076	Loom offers a host the contrast bar and does not impose it	Accepted
0077	A palette is derived once and committed as literals	Accepted
0078	The front door speaks the visitor's language, and a test holds it there	Accepted
0079	A layout only CSS can express belongs in the stylesheet, width query and all	Accepted
0080	A doc comment in src/ is written to a stranger	Accepted
0081	The front door demonstrates statelessly, and the address is the whole of the state	Accepted
0082	A refusal says what became of the repair	Accepted
0083	A scoped request sends the scope, not the page it sits on	Accepted
0084	In a two-dimensional band, rows are nodes and columns are positions	Accepted
0085	A font pack declares a face when something reads it	Accepted
0086	A behaviour is a control the runtime builds and a primitive places	Accepted
0087	A primitive that posts declares it, and the audit checks the declaration against what it renders	Accepted
0088	A hold is a row, and taking it is one statement	Accepted
0089	The text ramp is held to four grounds, and a pairing is measured whether one primitive paints it or two compose it	Accepted
0090	A probe that declines says whether it got as far as calling the component	Accepted
0091	Motion stops in edit mode, and that is where a decorative duplicate belongs	Accepted
0092	A disclosure control owns its button and the primitive owns the region	Accepted
0093	A decorative copy is the same children without identity	Accepted
0094	A card's prose is a child when the card has a flow, and a prop when it does not	Accepted
0095	A frame carries its URL, and the deployment carries the origins	Accepted
0096	A behaviour publishes a value on the element the primitive placed it in	Accepted
0097	A hole in the decision numbering is reported, and a clash is fatal	Accepted
0098	An anchor is a reserved key the runtime checks and a primitive places	Accepted
0099	A record is amended in place when only the count moved	Accepted
0100	A same-origin path is not a scheme	Proposed — ARCHITECTURAL, needs review. It contradicts a clause
0101	The loom. namespace is the framework's, and the CLI will not write in it	Accepted
0102	A same-origin path is decided by resolving it, not by matching it	Proposed — ARCHITECTURAL, needs review. It shares
0103	A control carries a class, and its display is a custom property	Accepted
0104	The runtime publishes its fixtures and its contract suites	Accepted
0105	A render can hand back values instead of references	Accepted
0106	A band asks its own container for a width, not the window	Proposed — ARCHITECTURAL, needs review. It reverses a named
0107	A font pack may say where a face is, and the runtime never fetches it	Accepted
0108	A repair restates the request, and the runtime measures it rather than making it cheaper	Accepted
0109	An inverse in hand is proposable without a store, and the runtime never puts its own name on one it did not plan	Superseded by 0137
0110	An entrance the reader drives is a wrapper primitive, not a prop on every band	Accepted
0111	The revision an undo puts back is a field on provenance, because provenance is the part of a proposal a log keeps	Accepted
0112	A hold store lists what the handle can see, and its cursor is two columns because an instant is not a key	Accepted
0113	The pairings probe reports where it stops looking, rather than inventing a price	Accepted
0114	A primitive declares what part it plays, and the registry is what gets asked	Accepted
0115	Three fields of one shape are a list wearing three names	Proposed — ARCHITECTURAL — needs review
0116	A screenshot is taken by the repository, and Playwright is never a dependency	Accepted
0117	One harness, two subjects: a tree it renders and an address you serve	Accepted — partially superseded by 0191
0118	A citation is a claim, and only a link can be checked	Accepted
0119	The page a reader gets is the one pnpm verify reads last	Accepted
0120	A starting composition is a subtree a catalogue hands to the ordinary seam	Accepted
0121	Part of a tree is rendered by the seam, and the seam is what mounts the theme	Accepted
0122	A primitive says which of its props a reader reads, and empty is not silence	Accepted
0125	A geometric property is asserted over the page, not the primitive	Accepted
0130	Atmosphere is a wrapper primitive, and the paints are one shared vocabulary	Accepted
0131	What a palette cannot say about itself is measured from it, never declared on it	Accepted
0132	A type that mirrors a schema is derived from it	Accepted
0135	A same-origin frame is granted what its own document needs	Accepted — it changes no schema, no tree and no delta model, and
0136	A published page broadcasts reader signals when its host asks	Accepted
0137	An undo already computed is assembled by the runtime, and stamped by its caller	Accepted — supersedes 0109
0138	A queue can be told which of its holds are already dead, and a head it could not read is a third answer rather than an optimistic one	Accepted
0139	A shared ledger is union-merged, and a generated file is regenerated	Accepted
0140	A call into foreign code has a ceiling, and the runtime owns it	Accepted
0145	A light that marks one of several is a wrapper, and it is carried by distance rather than by colour	Accepted
0146	A reader signal stays anonymous, and a funnel is correlated inside one page view	Accepted
0147	A rollup is added to what is stored, and a distinct-view count is therefore approximate	Accepted
0150	A container that must aggregate over its children publishes a custom property, and the browser does the arithmetic	Accepted
0155	A container may only add to its children what they left unspoken, so a shared treatment lives in a class and never on the element	Accepted
0156	The two states a bound region is in are primitives, and not props on every container	Accepted
0157	The catalogue's public surface is the list and the lookup, not every band by name	Accepted
0158	Counting a window of reader signals and forgetting it are one operation	Accepted
0159	An instrument may reach a state, and may never assert one	Accepted
0160	Where a rendering depends on a fact about the content that no rule can observe, the tree declares the fact and never the layout	Accepted
0161	A public page writes to one application endpoint, and is counted by a key that outlives nothing	Accepted
0162	The catalogue is a phrasebook of designs, and the page is one derived path through it	Accepted
0163	A binding is weighed like a destination, and its params are half of it	Accepted
0164	A resolution that cannot answer is not a node that did not ask	Accepted
0165	An anchor belongs to the part, and uniqueness is asserted over the assembled page	Accepted
0166	A list that ranks is checked where it is written, and a level the scale cannot place is the heaviest one	Accepted for the first half (the completeness check), **Proposed for
0167	A delegated signal names the regions it happened inside, and a region is counted in views rather than in presses	Accepted
0168	A band links into the page it is assembled into, and the page is where that is checked	Accepted
0169	A declaration is what makes a value a missing word	Accepted
0170	A library is a set to choose from, and a vocabulary is priced per entry	Accepted
0171	A page part is earned by the region it occupies, not by the content it holds	Accepted
0172	What a deployment can offer a model is one value, and three more vocabularies go in it	Accepted
0173	A change may not add a node the deployment cannot draw	Accepted
0174	A band wears the treatment its own content earns, and adds to its ground rather than replacing it	Accepted
0175	A listing skips the row it cannot read and fails the one it cannot place, and a store that did not answer is a different word from a row that did not parse	Accepted
0176	A control may be answerable to another control, and the two agree through the DOM rather than through the seam	Accepted
0177	The specification is a page part, and it sits between the figure that persuades and the price	Accepted
0178	A ground is not always an ancestor, and bg-overlay is the fifth ground the text ramp is held to	Accepted
0179	What a primitive accepts is a vocabulary the write path is handed, not a field on a policy	Accepted
0180	A primitive that draws an answer declares the shape it can draw, and a row that came from a database is never a node	Accepted
0181	A primitive declares the binding names it reads, and saying nothing is not saying none	Accepted
0182	A shot may reach a state it does not photograph, and may name the document it reaches into	Accepted
0183	A page for another kind of business is the same sequence with different nodes in it	Accepted
0184	A primitive may read under whichever name a prop gives, and says so as a declaration rather than a name	Accepted
0185	A probe is handed answers the way it is handed props, and a specimen declares the reply rather than the source	Accepted
0186	A what's-on band occupies the come-back region, so it is a design of articles and not a twenty-third part	Accepted
0187	A frame with no picture in it does not take the picture's shape	Accepted
0188	A specimen may ask to be hydrated, and one function builds the page for both renders	Accepted
0189	A portrait with no photograph is the person's initials, and a portrait with nobody named is nothing	Accepted
0190	A route group may contribute a sitemap and may not contribute a robots.txt	Accepted
0191	The harness may start the application, because there is now only one	Accepted — partially supersedes 0117
0192	A region a primitive places is a region it may ground	Accepted
0193	A status line is data: its opener is a closed set, and a supersession is written at both ends	Accepted
0194	The framework is the package, and everything that uses it ships separately	Accepted
0195	A shot may say what the browser started with, and it says it as data	Accepted
0196	A paint is sized by the box it is given, and says so when it cannot be	Accepted
0197	A host may ask which way round a palette is, and a frame standing in for the page is handed both ends	Accepted
0198	A refusal records which rules it broke, and the rules' names are a closed vocabulary	Accepted
0199	The outline may render what it addresses, and a hand may yet move a node	Proposed
0200	The portal may place a lever beside the evidence, and a model may never pull one	Proposed
0201	A display line and a reading line are two measures	Accepted
0202	The harness measures the content a clip hides, and it is not scrollWidth	Accepted
0203	A props vocabulary is handed the props a primitive is handed	Accepted
0204	A rule with no fill beside it is measured in ΔE, not in contrast ratio	Accepted
0205	A line the library declares is measured against every ground it is drawn on	Accepted
0206	A primitive declares what it could not show, and the runtime decides whether to say so	Accepted
0207	A primitive that arranges only glyphs inherits its alignment	Accepted
0208	A question nothing reads is refused before it is written	Accepted
0209	What an adapter owes the runtime is a suite, not a sentence	Accepted
0210	A primitive may lock the page's scroll from the stylesheet, and only while its own region is open	Accepted
0211	A completion is a form the browser let go, and it carries the bands it was the end of	Accepted
0212	What a reader signal means is joined to the tree when it is read, and the tree is what makes silence a measurement	Accepted
0213	The harness reads a box, it prints the number, and the judgement stays in the report	Accepted
0214	Where readers are is a floored bucket counted at the door, and a page view says when it began	Accepted
0215	A stake rule either reads a policy or is fixed at its code, and only the first kind can be asked again	Accepted
0216	A published double derives whatever the runtime derives	Accepted
0217	Choosing a two-region primitive is itself an insert decision	Accepted
0218	What a counter means is published, and the browser pays for the number and not its name	Accepted
0219	A page view is counted once at the door, and the over-count in the node counters is a measurement	Accepted
0220	An app is a registry, a policy and a store — and Loom has one of each	Proposed
0221	Where reading stops is a fall between two siblings, and a ratio of two counts off one row set	Accepted
0222	A structured reason travels with the judgment, and the prose is for readers only	Accepted
0223	A prop is copy when a reader could quote it, and a glyph is not a quote	Accepted
0224	A before-and-after reading compares two shares, and a pair the change dissolved is an answer	Accepted
0225	A judgment is joined to a revision by a bounded lookup, and the lookup says what it did not reach	Accepted
0226	A primitive declares where its control rests, and the control publishes nothing until the reader moves it	Accepted
0227	An inline link is its own primitive, and its colour is the paragraph's	Accepted
0228	The tree as it was is a fold bounded at both ends, and the head is answered from the log	Accepted
0229	A share of readers is estimated against the appearances and bounded against the openings	Accepted
0230	A part was read when readers had time for its words, and only the skim is a safe claim	Accepted
0231	A funnel is three shares of the arrivals, and the straddle is the one error here that leans down	Accepted
0232	The shell mounts a theme and registers no primitives	Accepted
0233	A bound twin is earned by a system of record and a row shape the primitive can declare	Accepted
0234	A primitive may name a control from the tree, and its declared string is the floor	Accepted
0235	How much of a page gets read is a share of words that partition it, and the typical reader's figure is a ceiling	Accepted