# WeaveLang Reference Version 0.3 ## 1. What WeaveLang Is WeaveLang is a human-authorable and machine-readable language for expressing meaning at any degree of nuance. A weave is a nested world of meanings. Each depth is complete enough to explore on its own. Going deeper reveals worlds inside worlds, and the deepest depth is the material itself — the verbatim paragraph, the exact clause, the working code. The reader asks for a resolution; the weave answers at that resolution and stops. Nothing that was skipped was load-bearing. ### 1.1 A Corpus That Is Compressed Where It Can Be The central property: **a weave may be written out in some places and described in others, and the two live in the same structure.** A file can be spelled out line by line, except for the part that is conventional, which is one sentence instead. A struct can name three fields exactly and describe the rest. A function can have its hard branch written and its error path described. A book can carry three chapters verbatim and summarise the other thirty. Nothing marks the difference except whether material is present. A unit whose material is written is written; a unit whose material is only described is described. Both are units, both sit in the same tree, and a reader moving down the tree passes from one to the other without noticing a seam. That is what makes a weave a **corpus compressed where compression is harmless**. It is also what makes an unfinished weave buildable: everything described rather than written is a brief, and the depths above it are the constraints that brief must satisfy. ### 1.2 Self-Contained By Default When each part is written out, the file holds everything: - A book weave contains the book. The top is one sentence about what the book is finally about; the bottom is the author's own paragraphs, in order. - A software weave contains the software. The top is what the system does; the bottom is source that compiles. - A specification weave contains the specification. The top is the contract; the bottom is the normative text. Read downward and a weave explains. Read upward from the material and it justifies. A tool that already stores the material — a code host, an archive, a corpus — may name it instead of embedding it (§4.5). The semantics are identical; only the storage differs. ### 1.3 The Design Razor Among designs that decide the observed cases exactly, WeaveLang takes the **weakest** — the one committing least beyond the data (Bennett, arXiv:2301.12987). Generality is a property of a design's extension, not its form. ### Commitments and capabilities are opposite things The razor maximises extension. So it deletes **commitments** — an enum, a fixed ladder, a rule keyed to one vocabulary — because a commitment rules out material the author never saw. It says nothing about deleting **capabilities**, and a capability deleted shrinks extension exactly as a commitment added does. The two are told apart by one question: **does this construct foreclose anything?** - A `layers` block asserting that depth 3 means the same in every branch forecloses every document whose branches differ. It is a commitment. Delete it. - A `relation` forecloses nothing. It offers an expression some material will need. It is a capability. That no weave has yet used one is not an argument. **Coverage is forced by the purpose; shape is forced by the data.** WeaveLang exists to express any subject — a book, a program, a standard, an argument. That purpose forces coverage of material nobody has woven yet, so *"there is no example yet"* is never grounds for removing an expression. It is only ever grounds for holding the expression in its weakest form until real material shapes it. ### The four rules - **Weaken by deleting commitments.** A construct that decides something the material does not force adds form and shrinks extension. - **Never delete a capability for want of an example.** Ask instead whether it is in its weakest form. - **A new expression starts in the open mechanisms.** `kind`, `props` and `meta` cost the core nothing and cannot be wrongly shaped. An expression is promoted to core grammar only when real material has shaped it — because speculative machinery is rarely wrong to exist, and frequently wrong in its shape, and a wrongly-shaped core field is paid for by every tool forever. - **Boundedness lives at the edge.** Open-ended dimensions — domain vocabulary, material formats, locators — stay strings resolved by convention. Real protocol facts, like a line range or a revision hash, are explicit and validated. The cost that does scale is the **conformance surface**: every construct the core names is one every tool must handle. That is the argument for holding expressions in `meta` — never the argument for making them inexpressible. ## 2. The Five Constructs ```weave weave the file: one bounded subject unit any meaningful thing; nests to any depth; may hold material content a literal part of a unit's material relation a connection between units that is not containment source a pinned origin, for material that is named rather than embedded ``` Everything domain-specific — a Kubernetes pod, a character arc, a normative MUST, a Go struct field — is a `kind` string on a unit or relation, given meaning by a convention (§6). The core never learns what any of them are. ### 2.1 weave ```weave weave [kind ] { ... } ``` Recommended fields: `title`, `summary`, `created_by`, `created_at`, `model`, `version`, `license`. A weave holds one or more root units, plus any relations and sources. ### 2.2 unit A unit is any meaningful thing: a capability, a chapter, a requirement, an actor, a function, a struct field, a paragraph. It stands alone at its own resolution, sits inside parent context, and holds either more units, material, or both. ```weave unit [kind ] "Title" { summary "What it means at this depth." ... } ``` | Field | Job | | --- | --- | | `summary` | What the unit means when it is the active world. | | `collapsed_summary` | What neighbours need to know when it is only context. | | `preview_summary` | What the inside promises before it is entered. | | `name` | The unit's handle: one to three words, for when space cannot carry the title (§2.2.1). | | `ref` | The unit's own name in its source's numbering. Verbatim, opaque (§2.3). | | `content` | A literal part of its material (§4). | | `reveals` | Children that are not lexically nested (§3.2). | | `cites` | Other units whose material supports this one. | | `confidence` | 0–1. Low confidence must not render as fact. | | `props` | Typed scalar attributes (§5). | | `meta` | Repeatable free-kind annotations (§5). | The three summaries do three different jobs and are not abbreviations of each other. A reader uses them at three different moments: `preview_summary` decides whether to enter, `collapsed_summary` decides whether to ignore, and `summary` is what the unit means once inside it. ### 2.2.1 name — the handle A `title` addresses the unit's subject directly, in two to five words — "Getting Into Production", "The five-dollar day" — never a sentence. The CLAIM lives in the summary; a sentence-title makes every box, crumb, and menu pay for a clause its space cannot carry, and a claim cut mid-way is garbage. The title is the unit at its longest text rung, and it descends by substitution: a direct child's box carries the title where it fits whole; a grandchild carries the 1–2 word `name`; below that, the icon (§6.5). Every rung is authored; no rung is a truncation of the one above. `name` is the handle: what the unit is *called*, in one to three words — and the fewer the better. One or two words carry best: a name earns its keep in the smallest boxes a renderer draws, where a third word is usually the first thing that wraps. Three is the ceiling, not the target, and a name never spends a word the unit's own vocabulary does not need ("The broom", not "The broom anecdote"). Below the name sits one more rung, by convention rather than core field: a single-glyph `meta icon` (§6.5) for the box too small to carry even the name — a renderer shows the glyph or, absent one, its own mark, and never a truncated word. A name cut to three letters and an ellipsis says nothing and is drawn nowhere. ```weave unit wl.depth kind document.mechanism "Depth and its invariants" { name "Depth" meta icon "🪆" ... } ``` It completes the display ladder. Each rung is a shorter **authored** field, so a renderer demotes by substitution and never by shrinking or truncating: ```txt summary → collapsed_summary → preview_summary → title → name → a mark ``` `name` is optional. Where it is absent a renderer falls back to `title` and may truncate it at a word boundary — the fallback is legal, and it is exactly the degradation `name` exists to prevent. ### 2.3 ref — the unit's name in its own source ```weave unit req.idempotency kind document.requirement "Idempotent methods" { ref "9.2.2" summary "A client may repeat GET, PUT, or DELETE without additional effect." } ``` `ref` is the name the material already has: a section number, a file path and symbol, an act and scene, a clause. It is copied verbatim and is **opaque to every tool** — displayed, matched as a whole string, embedded in permalinks and citations, but never parsed, never sorted by, never validated for shape. ```weave ref "9.2.2" ref "§5.3(b)(ii)" ref "src/retry.go:RequestDirectives" ref "Act II, sc. 3" ref "Art. 6(1)(f)" ref "Table 4" ``` Two things earn it a place in the core. **It is the only string in a weave that cannot be wrong.** Every summary is an interpretation and can misdescribe what it covers. A `ref` is a copy. A reader misled by a summary can still find the clause, cite it, and check it. **Experienced readers navigate their genre by prediction.** Someone who knows standards knows roughly where conformance language lives; someone who knows a codebase navigates by path. Carrying the source's own names preserves that at no cost. `ref` is optional. Material with no native numbering has none, and every tool works without it. ### 2.4 relation A connection that nesting cannot express: causation, dependency, support, rebuttal, sequence, a call across a boundary. ```weave relation [kind ] { from to label "short phrase at this depth" } ``` | Field | Job | | --- | --- | | `from`, `to` | The endpoints. Direction is `from` → `to`; nothing else encodes direction. | | `kind` | What sort of connection. Convention vocabulary. | | `label` | The short phrase a reader sees on the edge. | | `summary` | The complete meaning of the connection at its own depth. | | `preview_summary` | What the deeper explanation promises. | | `reveals` | A unit that explains this relation in more detail. | | `cites` | Units whose material supports the connection. | | `confidence` | 0–1. | | `props`, `meta` | Everything else. | Shorthand, when a relation needs no id and no body: ```weave edge api -> db kind software.reads "reads user records" ``` More than two participants ride `props`: ```weave relation incident_cause kind causal { from event.deploy to incident.invoice_delay label "a halved fleet could not drain the backlog" confidence 0.64 cites [sig.queue] props { through "service.billing" condition "backlog exceeded 10 minutes" } } ``` Arrow shapes, endpoint markers, and layout are renderer concerns fed by `kind` (§6.4). The core does not describe pictures. ### 2.5 source A pinned origin, needed only when material is named rather than embedded. ```weave source [kind ] { uri "https://github.com/acme/app" title "Original item" author "Author" revision "abc123def" captured_at "2026-06-25T10:00:00Z" } ``` One source per origin, pinned once. Repeating a revision on every leaf invites leaves that disagree about which revision they read. ## 3. Depth ### 3.1 Depth Is Nesting A unit declares its children inside its own block. Its depth is the number of units it sits inside, plus one. There is no layer index and no annotation to keep in sync. ```weave unit thesis kind book.theme "Freedom requires self-knowledge" { summary "The novel ties freedom to painful self-recognition." unit part.one kind book.part "Part One" { summary "Raskolnikov reasons his way to the murder." unit ch.one kind book.chapter "Chapter I" { summary "The rehearsal walk. He tests the route, the bell, and himself." } } } ``` Three properties follow: - **Depth is unbounded.** Nothing caps the structure. A dense chapter may run nine deep while the acknowledgements stop at two, and a single function may nest as deeply as a whole repository. - **Depth is local.** Completeness belongs to a branch, not to the document. A weave is not incomplete because one branch is shallower than another; it is incomplete when a depth is not a whole world. - **Depth is relative.** Lift a subtree out, embed it elsewhere, render it alone — every statement inside stays true, because nothing in a unit refers to its absolute position. There is no naming of depths. A global depth-to-name table would assert that depth 3 means the same thing in every branch, which is the uniformity local depth exists to remove. Each unit's `kind` says what it is, and a renderer that wants to label a level reads the kinds it finds there. ### 3.2 reveals `reveals` names children that are **not** lexically nested: a child declared elsewhere, or one shared by more than one parent. ```weave unit motif.mirror kind book.motif "The mirror motif" { summary "Mirror scenes mark each failure of self-deception." reveals [scene.stairs, scene.ch34] // both already have parents in the plot tree } ``` A renderer treats lexical and revealed children identically: both are previews, and both become the next active world. The distinction exists only so a shared child need not be duplicated. Ids are globally unique within a weave and independent of nesting. Nesting is structure, not a namespace: a deeply nested `fn.mint` is addressable by that id from anywhere. ### 3.3 The Two Invariants **Every depth must be useful by itself.** ```txt Bad: "Auth module." Semantically empty. The reader must go deeper to learn anything, so this depth was never a world — only a table of contents. Good: "Auth module: email/password login issues signed JWTs and protects tenant-scoped API routes." A whole answer at this resolution. The next depth refines; it does not rescue. ``` **Every depth must be true of the material below it.** A summary that does not describe what its subtree contains is not a summary; it is a different claim wearing a summary's clothes. Material makes this checkable: a validator can hold a unit's summary against its own subtree and ask whether one describes the other. ## 4. Material A unit's **material** is what it is finally about. Material is built from **parts**, in the order they are written: literal `content` blocks, and child units. A child contributes its own material, recursively. This one rule is what lets a single file, a single class, or a single function carry layers inside it. ### 4.1 Literal Material A `content` keyword alone on its line opens a verbatim block ending at a line whose only text is `end content`, at the same indentation as the opening keyword. ```weave unit scene.opening kind book.scene "The opening walk" { summary "He leaves the garret and rehearses the route." content On an exceptionally hot evening early in July a young man came out of the garret in which he lodged in S. Place and walked slowly, as though in hesitation, towards K. bridge. end content } ``` An optional word after `content` names the material's form. The word is free — conventions give it meaning, renderers use it for styling, and the core has no list of valid values. Three conventions ride on the form word, all invisible to the core: - **Shape names.** Published conventions name common shapes so tools can render them expressively: `markdown` (prose, bullets, tables), `txt` (verbatim text), `diagram` (monospace drawing), `svg` (an inline picture), `timeline` (rows of ` — `, one per line), `pairs` (rows of ` — ` — a labeled mapping, rendered with the timeline's own component: the lead in the accent column, the rest in reading type; prefer it over an ASCII drawing wherever the claim is label-to-fact rather than genuine geometry). An unknown form still parses, validates, and renders verbatim. - **The `face` role.** A form may carry a role before its shape, dotted like a sub-symbol word: `face`, `face.bullets`, `face.table`, `face.diagram`, `face.timeline`. A face block is the unit's **collapsed reading** — what a tool may show when the unit is seen from outside, in place of prose summaries — and it is not part of the page the unit shows when it is open (the open page's account is the summary and the ordinary material; showing the face there too would render one statement twice). A tool that knows nothing about roles renders a face block as ordinary material, which degrades to honest. See §13 G6 for what makes a good face block. - **Unit links.** In a prose-form block, a standard markdown link whose target is `#` followed by a unit id — `[the moving line](#ch5)` — names that unit. A tool that can navigate treats it as a door: activating it goes there, and it may show the unit's collapsed reading as a preview on approach. Two limits keep the device honest. It appears only in AUTHORED blocks — gists, bullets, faces — never in verbatim material, because material is never edited. And a link whose id does not resolve renders as its plain text: a door that opens nowhere is not drawn as a door. Block rules, in full: - The block starts on the line after the `content` line and ends at the first line whose trimmed text is exactly `end content` **at the opening indentation**. - Every line between is verbatim. There are no escapes and no delimiters, so a block can contain quotes, braces, backticks, or any other syntax without collision — including this language's own. Matching the indentation is what lets a block contain an example of itself. - Indentation is removed **per unit, not per block**: all of a unit's literal blocks are dedented together, by the smallest indentation any of them used. That is what lets the parts of a struct or a function body keep their indentation relative to each other when they are reassembled. Material is never a summary, a paraphrase, or a quotation *about* the thing. It is the thing. A tool must never tidy, reflow, or rewrap it. ### 4.2 Composed Material A unit may write some of its material and delegate the rest to children. Parts compose **in the order they appear**: ```weave unit directives kind go.struct "RequestDirectives" { ref "common/request.go:RequestDirectives" summary "Every knob a caller may set for one request. The zero value is the service default, so an unset field is never an error." content go type RequestDirectives struct { end content unit d.retry kind go.fields "Retry knobs" { summary "Attempt count, backoff base, and whether jitter is applied. Json tags match the config file's naming so a directive can be set either way." } content go ReadTimeout time.Duration `json:"readTimeout"` WriteTimeout time.Duration `json:"writeTimeout"` end content unit d.integrity kind go.fields "Integrity knobs" { summary "The checksum algorithm to verify with, and whether a mismatch fails the request or only records a warning." } content go } end content } ``` Read at the top, this is one sentence about what the struct is for. Read one level down, it is four ideas: the declaration, the retry knobs, the timeouts, the integrity knobs. Read fully, it is the struct — except that two of its four parts are described rather than written. `d.retry` and `d.integrity` are **described**: they have a summary and no material of their own. They occupy a real position in the struct, they are addressable, they can carry relations and citations, and a reader can see exactly where they belong. What they do not have is bytes. ### 4.3 Written And Described The only difference between a written part and a described part is whether material is present. | | written | described | | --- | --- | --- | | has `summary` | usually | always | | has material | yes | no | | occupies a position | yes | yes | | addressable, citable, relatable | yes | yes | | a renderer shows | the material | the summary, in its place | | a generator may | render it | write it, from the summary and its surroundings | A described unit is not an omission and not an error. It is a statement that this part of the material is conventional, uninteresting at this depth, not yet written, or deliberately left to the reader. The same mechanism covers cases that look unrelated: ```weave // A file whose imports are not worth reading unit imports kind go.imports "The usual imports" { summary "Standard library time and errors, the project's config package, and the vendored json library." } // A function with one interesting branch and one boring one unit fn.verify kind software.function "verifyMagicLink" { summary "Check the signature, reject an expired link, then start a session." content typescript export async function verifyMagicLink(token: string): Promise { const claims = verifySignature(token, MAGIC_LINK_SECRET) end content unit expiry kind software.branch "The expiry check" { summary "Reject when issuedAt is more than ten minutes old, measured against the server clock, and consume the token so it cannot be replayed." } content typescript return startSession(claims.subject) } end content } // A book read closely in one chapter and loosely everywhere else unit ch.thirty kind book.chapter "Chapter XXX" { summary "The confession, delivered flatly and immediately retracted." } ``` ### 4.4 Compression Is A Reading, Not A Format Because material composes from parts, the same weave answers at every resolution without storing several versions of itself: ```txt depth 1 the unit's summary depth 2 its children's summaries, in order depth n literal parts verbatim, described parts as their summaries full literal parts verbatim; described parts still described ``` A renderer chooses a depth. A generator chooses a depth and then writes what is still described. Neither needs a mode, and the file does not change. ### 4.5 Named Material When material already lives somewhere, the same construct names it instead of embedding it. ```weave unit fn.verify kind software.function "verifyMagicLink" { summary "Check the signature, reject an expired link, then start a session." content typescript in pr.head { at "auth/magic.ts" region lines 42..78 sha256 "9f2c1a…" } } ``` | Field | Job | | --- | --- | | `in ` | Which source (§2.5). | | `at ""` | Path, fragment, chapter, or other stable locator. | | `region ` | Which part. The selector word is free. | | `sha256` | Pins the exact bytes, so a later read detects drift. | | `outline { … }` | The structural region tree of the material (§4.6). | | `props`, `meta` | Rendering and folding preferences. | Region examples — the selector is an open word, not one of a fixed set: ```weave region lines 40..92 region page 221 region section "9.2.2" region time "2026-06-25T10:00:00Z" .. "2026-06-25T11:00:00Z" ``` A weave with named material is not self-contained: it needs its source to be readable. That is a trade a tool may make, never a default the language prefers. ### 4.6 Outline An `outline` inside named material carries its structural region tree, distilled from the real source. It lets a renderer show material that reads *complete* — a block's opening line, its telling middle, its closing bracket — while folding everything less significant into a one-line gloss. ```weave content go in pr.head { at "common/request.go" region lines 109..140 props { significance 87 role "defines the request directives contract" } outline { region lines 1..780 file name "common/request.go" region lines 1..14 imports rank 5 region lines 109..540 struct name "RequestDirectives" rank 90 region lines 117..538 run gist "remaining directive fields, with json tags" rank 20 region lines 545..690 func name "ApplyDirectiveDefaults" gist "copy each non-nil default onto r.directives" rank 70 } } ``` ```txt region lines .. [name ""] [gist ""] [rank <0-100>] ``` - **Boundaries are real lines, never invented.** 1-based inclusive; `start` is the opening line and `end` the last. A region that does not correspond to real material is fabrication. - **Nesting is containment.** A region inside another is its child; parents sort first. A fold must land on region boundaries and never cut a block mid-way. - `kind` names the structural unit and is a **free word** — `file`, `struct`, `func`, `imports`, `run` for an undeclared stretch, `section` or `paragraph` for prose, or anything a new material form needs. - `gist` is the one-line gloss shown when the region is folded: what the hidden material *does*, in the source's own vocabulary. It must describe exactly the lines it hides. - `rank` (0–100) orders significance relative to the citing unit; higher ranks open at shallower depth. The outline supplies facts, the renderer supplies policy. ## 5. props And meta The core admits only ground truth: what a thing is, how things connect, what material it holds. Everything subjective, interpretive, or renderer-facing rides exactly two open mechanisms, and the core has **no opinion about any key or kind** inside them. ```weave unit pool kind software.component "TransportPool" { summary "Process-global transport cache keyed by upstream." props { language "Go" public true score 0.91 } // typed scalars meta point "lazy creation on first call" // repeatable, free kind meta point "mutex-protected map" meta attention "process-global singleton" meta risk "medium" // a judgment, so meta } ``` `props` carries typed scalars; `meta` carries repeatable annotations. Fields like `risk`, `severity`, `status`, `time`, `value`, `actor`, and `condition` are not core language — they are opinions, workflow state, or domain facts, and they live here under whatever convention applies. A renderer that knows the convention may style them; one that does not ignores them. An event is `unit kind event { props { time "…" } }`. A desired state is `unit kind state { props { value "3 replicas" } }`. The core stays out of both. ### 5.1 Authorial intent An author of an unfinished weave needs to say things about the parts that are not yet written: who may write them, what they must not become, how firmly the existing words are meant. These are expressions the purpose requires, so they must have a home. They are not core grammar, because no real material has shaped them yet, and a wrongly-shaped core field is paid for by every tool forever. They are conventions on `meta` and `props`, and the core has no opinion about any of them. ```weave unit cap.serve kind software.capability "Serving a slug" { summary "A request for a retired slug redirects permanently to its successor." meta infer "allowed" // may a generator write this described part? // allowed · ask · forbidden · stub · convention meta avoid "slug reuse" // negative space: what it must NOT become. meta avoid "redirect chains" // repeatable, because a brief has many edges. meta intent "strict" // how firmly the words are meant. // strict · normal · loose · exploratory meta hand "human" // who wrote this: human · model · importer. props { locked true } // do not regenerate, whatever else is asked. } ``` **Negative space is the one of these that cannot be inferred.** A summary states what a part is; nothing in it states what the part must not become. An author who knows that a plausible, conventional, wrong answer exists — social login, a redirect chain, a retry on a non-idempotent method — has no other way to rule it out, and a generator will produce it. ### 5.2 Provenance Where a producer can track which span of a unit's material a summary phrase came from, recording it lets a reader step from an interpretation to the material behind it in one action. ```weave props { derived_from "summary 7..44 → content 210..268" } ``` The form is deliberately a string under a convention rather than core grammar. The capability is required — a summary that cannot be checked against its own material is the format's central risk — but no real corpus has yet shaped the offsets, and guessing the shape now is how a core field comes out wrong. A tool offers the step-down where the convention is present and does not where it is absent. ## 6. Conventions A convention is a named vocabulary a community converges on: kinds for units, verbs for relations, form words for material, selector words for regions. It adds no syntax, and **nothing in the language enforces it**. ```weave weave "Example" { use profile weave.software use profile weave.security } ``` `use profile` is a declaration of intent, not an import that can fail. A weave that never declares one and invents every kind it needs is a valid weave. ### 6.1 Kinds Are Strings, Not An Enum The core validates that `kind` is a well-formed identifier and nothing more. A weave using `kind acme.sla_tier` parses, validates, and renders — generically if the term is unknown, specifically if it is known. Unknown terms are preserved verbatim, never dropped, never rejected. Domain vocabulary is open-ended by nature. Any closed list of kinds would be wrong the first time someone weaves material its author never imagined. A language that refuses an unfamiliar noun has decided in advance which subjects may exist. ### 6.2 Why Converge Anyway Agreement is what lets a tool do something *specific* instead of something generic. When enough people call a deployable process `software.service` and a data dependency `software.reads`, a tool can act on that without the language ever knowing what a service is. - **Explorers** render a known kind expressively — a cylinder for a database, a diff surface for a changed function — and fall back to a plain card otherwise. - **Analyzers** answer questions that are meaningless in general and obvious inside a convention: which services read this table, which requirements have no implementing unit, which described units still need writing. - **Compilers** treat a known kind as a target. `software.function` with material is a file to write; `go.fields` that is described is a declaration to generate. - **Search and merge** work because two teams that both say `software.endpoint` have made their weaves comparable without coordinating. The trade is deliberate: the core stays weak enough to describe anything, and the convention layer stays rich enough to be useful. A convention that guesses wrong costs one renderer a fallback. A core that guesses wrong costs the language a subject it can never express. ### 6.3 Published Conventions `weave.core`, `weave.software`, `weave.cloud`, `weave.security`, `weave.book`, `weave.document`, `weave.news`, `weave.history`, `weave.llm_response`, `weave.argument`. Each publishes its terms at a stable URI; the registry, not this document, is the list. Representative core kinds: ```txt units thing concept entity actor system boundary process event state claim question risk decision requirement metric location collection relations relates_to part_of depends_on causes prevents enables blocks supports contradicts qualifies summarizes refines reveals cites derived_from attributed_to located_in before after during overlaps ``` Representative domain kinds: ```txt software system domain capability service module component class function api endpoint database table queue worker test config deployment book work part chapter scene paragraph character theme motif turning_point document spec clause definition requirement mechanism field error ambiguity history arc period event actor cause consequence interpretation document ``` `weave.book` also publishes the **fully woven** property: a book weave is fully woven when the union of its leaf units' literal material reproduces the work verbatim — normalized only for typesetting artifacts such as hard line-wraps — so the deepest layer *is* the book, and fidelity is checkable by hashing the concatenated leaves against the source text. Chapters resolve into passages and passages into written paragraphs; every interior unit still owes the complete account §13 demands. A book weave that is not fully woven says so in its top unit rather than letting sparse leaves imply a whole text. ### 6.4 Sub-Symbol Conventions Because material composes from parts, a convention may name the parts of a single symbol. `weave.software` publishes these for the common languages: ```txt declaration the opening line of a type, class, or function fields a run of struct or class members branch one arm of a conditional loop a loop body guard an early return or precondition check error_path the handling of a failure case imports an import or include block body the remainder of a symbol's implementation ``` They are ordinary kinds and carry no special meaning to the core. Their value is that a tool reading `kind go.fields` on a described unit knows it is being asked for struct members rather than prose, and can offer to write them. ### 6.5 Rendering Hints A convention may suggest an icon, a colour, a shape, an edge marker, or a layout preference for a kind. Renderers may ignore them and must preserve them when round-tripping. The semantic model stays useful with every visual hint stripped, which is why none of them are core fields. ```weave kind software.database { icon "database" shape cylinder color "#0f766e" } relation_kind blocks { head_marker bar } ``` A single unit may also carry its own icon, as meta: ```weave unit ch5.p4 kind book.passage "The magneto line halves and halves again" { name "The magneto line" meta icon "⚙" ... } ``` `meta icon` holds ONE glyph — an emoji or a single character — and it is the display ladder's floor, one rung below `name`: the reading a box gives when it cannot even hold two small words. A renderer that reaches that size shows the glyph alone; a unit without one falls back to the renderer's own mark (a dot). Never words, never two glyphs, and never a glyph that repeats among siblings where one more pixel of width would have carried the name — the icon is a last resort, chosen so that siblings stay tellable apart at the smallest size they can be drawn. A unit-level icon outranks its kind's suggested icon. A whole weave may declare its own look — a book is allowed to feel like itself. Theme tokens ride as meta on the weave header, in the `theme.` namespace: ```weave weave "my-life-and-work" kind book { title "My Life and Work" meta theme.mode "dark" meta theme.bg "#17130e" meta theme.paper "#221c13" meta theme.ink "#eae1d1" meta theme.accent "#e08a4c" ... } ``` The convention publishes the common slots — `mode` (dark or light), `bg` (the stage behind the paper), `paper` (card and page surfaces), `ink` (text), `accent`, `muted`, `frame` (a style word for edges), `shadow` (a weight word for elevation) — and the namespace stays open: a renderer reads the slots it knows, derives its intermediate tones from them, ignores what it does not know, and preserves everything when round-tripping. A theme overrides the renderer's own default slot by slot, never all-or-nothing, and the semantic model survives with every token stripped — a theme is how a weave looks, never what it says. ### 6.6 Compatibility Conventions follow semantic versioning: patch for wording and icons, minor for new kinds, major for removed terms or changed semantics. A replaced term is marked `deprecated true` with `replaced_by`; renderers keep rendering it while validators warn. ## 7. Syntax ### 7.1 Plain Words, Few Symbols A weave is read by people at least as often as by machines, and a symbol that has to be explained is a symbol that should not exist. This is the **complete** non-alphanumeric vocabulary: ```txt { } open and close a block [ ] open and close a list " delimit a short string , separate list items -> direct a shorthand edge .. a range between two values // /* */ comments ``` Everything else in a weave is a word. The rule for additions: if a reader must be taught a character, use a word instead. ### 7.2 Statements ```txt [id] [kind ] ["Title"] [{ block }] "short value" [list, of, ids] { key value } [form-word] [in ] // end of line opens a text block [form-word] [in ] { // a brace opens a named-material block ``` A statement runs to the end of its line. What follows the head decides the form: a `{` opens a block, a `[` opens a list, a `"` starts a short value, and end-of-line opens a text block that runs until `end `. ### 7.3 Identifiers ```txt [a-zA-Z_][a-zA-Z0-9_-]*(\.[a-zA-Z_][a-zA-Z0-9_-]*)* ``` Every renderable object carries a stable id. Ids let tools render focused views, track a subject across versions, anchor comments, remember expansion state, diff two generated weaves, and merge a human edit into a regenerated one. ### 7.4 Text Blocks Any text-valued keyword may open a block by appearing alone on its line, with an optional form word after it, closed by `end ` at the opening indentation. See §4.1 for the full rules. This is the only place where whitespace carries meaning, and only as a dedent. ### 7.5 Comments ```weave // line comment /* block comment */ ``` ### 7.6 Grammar ```txt weave := "weave" (id | string) kind? "{" body* "}" body := unit | relation | edge | source | attribute | props | meta | use unit := "unit" id kind? string "{" (attribute | content | unit | relation | props | meta)* "}" relation := "relation" id? kind? "{" (attribute | props | meta)* "}" edge := "edge" id "->" id kind? string? source := "source" id kind? "{" attribute* "}" content := "content" word? ("in" id)? ( "{" (attribute | outline)* "}" | NEWLINE material "end" "content" ) outline := "outline" "{" region* "}" region := "region" selector value word attribute* kind := "kind" id attribute := word (string | number | id | list | range) props := "props" "{" (word scalar)* "}" meta := "meta" word string use := "use" "profile" id ("version" string)? ``` A unit's `content` blocks and child `unit` declarations are significant in the order they appear: together they are its material (§4.2). ## 8. Canonical JSON The text syntax compiles to a canonical JSON object. A unit's `parts` array preserves the order of its material. ```json { "weave": { "id": "request-directives", "units": [ { "id": "directives", "kind": "go.struct", "ref": "common/request.go:RequestDirectives", "title": "RequestDirectives", "summary": "Every knob a caller may set for one request.", "parts": [ { "t": "content", "form": "go", "text": "type RequestDirectives struct {" }, { "t": "unit", "id": "d.retry" }, { "t": "content", "form": "go", "text": " ReadTimeout time.Duration" }, { "t": "unit", "id": "d.integrity" }, { "t": "content", "form": "go", "text": "}" } ], "units": [ { "id": "d.retry", "kind": "go.fields", "title": "Retry knobs", "summary": "Attempt count, backoff base, and whether jitter is applied.", "parts": [] }, { "id": "d.integrity", "kind": "go.fields", "title": "Integrity knobs", "summary": "The checksum algorithm, and whether a mismatch is fatal.", "parts": [] } ] } ], "relations": [], "sources": [] } } ``` A unit with an empty `parts` array and no children is described rather than written. Named material carries a `ref` object in place of `text`, holding the source, path, region, checksum, and outline. Canonicalization defines: stable unit ordering within each parent, preserved part order, normalized ids and convention names, expanded shorthand edges, normalized time formats, deduplicated references — and **material dedented, never reflowed**. A canonicalizer that rewraps a paragraph or reindents a function has corrupted the material. ## 9. Validation | Level | Checks | | --- | --- | | syntax | the file parses; every text block has a matching `end`; blocks balanced | | core | ids unique; references resolve; `from`/`to` exist | | material | named sources exist; regions valid against the source; checksums match; outline regions nest without crossing; literal material round-trips after dedent | | depth | no summary depends on its children to be understood; leaves are written, described, or natural | | truth | each summary describes the material in its subtree; low-confidence claims are not rendered as fact; contradictions are explicit relations, not omissions | Convention validation is advisory by construction: an unknown kind is a warning, not an error, because a closed world would defeat §6.1. Validators emit machine-readable errors so a generator can repair its own output: ```json { "error": "unknown_reference", "path": "units[3].reveals[1]", "reference": "service.payments", "message": "Unit service.payments is referenced but not defined." } ``` ```txt generate -> validate -> repair -> validate -> format ``` ## 10. Conformance - **WL-Parser** — parses `.weave` and emits canonical JSON. - **WL-Validator** — validates core semantics without convention knowledge. - **WL-Renderer** — renders at least one view from canonical JSON. - **WL-Resolver** — resolves named material and verifies checksums. - **WL-Generator** — generates WeaveLang and marks material, uncertainty, and convention usage. - **WL-Writer** — writes material for described units, from their summaries and their surroundings (§12.2). File types: `.weave` (text), `.weave.json` (canonical AST), `.weave.lock` (resolved conventions). ## 11. Rendering A renderer is given a focus and a depth, and returns three sets: the active world, the envelope of ancestors, and the previews of children. Nothing about that query lives in the file — a view is a tool's input, not a fact about the subject. ```txt 1. Resolve the focus unit. 2. The focus and its siblings are the active world. 3. Ancestors are envelopes, rendered from collapsed_summary. 4. Children (lexical and revealed) are previews, rendered from preview_summary. 5. Include relations among active units; collapse those crossing outward. 6. At a unit with material, render its parts in order: literal parts verbatim, described parts as their summaries, in place. 7. Preserve hidden descendants as expandable portals. ``` Recommended material resolution as depth increases: ```txt shallow: files, headings, symbols, scene titles middle: signatures, hunks, focused paragraphs deepest: exact lines, exact text, transcript ranges ``` A described part must be visibly a description and not mistaken for material. It must never be silently omitted: a reader who cannot see that something belongs here has been told the material is complete when it is not. **The three readings, by distance.** A renderer that shows a unit at more than one distance gives it exactly three readings, each drawn from authored rungs: ```txt current unit the full gist: title, summary, gist elements, material, children — complete enough to skip the whole subtree and hold its ideas; the face does NOT repeat here (§4.1: it is the outside reading, and the open page must not begin with the list the reader just finished on the card) direct child the face: the short title or name and the one short element (§13 G6, or the collapsed summary where no face is declared) — readable at a glance; everything else recedes deeper presence only: the 1–2 word name, or the icon (§6.5), plus the shapes of its own children — enough to say what is there and that there is more, nothing that pretends to be readable ``` Each reading substitutes a shorter authored rung; none truncates a longer one, and no reading below the current unit shows text too small to read — an unreadable summary is noise wearing a summary's clothes. What renderers avoid: treating a weave as a collapsible bullet tree, a file explorer, a UML clone, a mind map where every edge means the same thing, or a graphic where the scale changes but the semantics do not. Never convert a whole weave straight to Mermaid, Graphviz, SVG, or canvas — resolve the three sets first, then draw only those. ## 12. Generation Contract ### 12.1 Writing A Weave A model generating WeaveLang must: 1. **Never edit the material.** Literal material is verbatim; everything above it is interpretation. If material needs describing, describe it in the summary. 2. **Make each depth independently readable.** Short summaries shallow, nuance and material deep. Never expand every branch equally. 3. **Mark uncertainty** with `confidence` and explicit `cites`, and never render a low-confidence claim as fact. 4. **Preserve locators** for named material — paths, revisions, line ranges, symbols — at the granularity of the citing depth. 5. **Not hide conflicts.** Two incompatible readings are two units and a `kind contradicts` relation between them, never one smoothed sentence. 6. **Plan flat, emit nested.** Plan as `id | depth | parent | kind | title | summary | material?`, then emit. This reduces orphaned children and broken references. 7. **Name a unit the same way in all three summaries.** The variants must share their head noun phrase. Readers treat a concept referred to by a repeated label as a main topic and one referred to by varied paraphrase as minor, regardless of its actual importance, so elegant variation makes a reader down-rank the unit. 8. **Copy `ref` verbatim.** Never normalise, renumber, or prettify it. Its whole value is that it is a copy. 9. **Give every unit a `name`,** one or two words where they suffice and never more than three, sharing its head noun with the three summaries. The name is what chips, crumbs and dots carry; a weave without names forces every renderer to truncate claims, and a wordy name defeats the smallest boxes it exists for. 10. **Describe rather than pad.** A part that is conventional or uninteresting at this depth is a described unit with a real summary, not invented material and not a silent gap. 11. **Audit before publishing.** Every unit is judged against the §13 checklist in an independent pass — the model that summarizes and the model that checks are never the same call. Every number a summary, bullet, or face carries is verified against the material or child that claims it; a number that cannot be pointed to is removed, not softened. Where a convention publishes a whole-weave property (§6.3's fully woven), the property is checked mechanically, not asserted. §13 states what a good weave looks like — how much belongs in one unit, where it splits, and what makes a parent's account complete and true of its children. It is law, and its checklist (§13 H) is runnable against a finished weave. ### 12.2 Writing Material For A Described Unit A described unit is a brief. To write its material, use: - its `summary`, which states what belongs there; - its `kind`, which states what form it takes; - the **literal parts on either side of it**, which fix its context exactly — the preceding part shows what it must continue, and the following part shows what it must lead into; - its ancestors' summaries, which are the constraints it must satisfy; - its relations and `cites`; - sibling material as a style reference. Write into the unit as a `content` block. Do not move it, rename it, merge it with a neighbour, or alter any surrounding literal part. If the summary is too weak to write from, add a `unit kind question` rather than guessing. ### 12.3 Reading A Weave A model interpreting a weave reads the active depth as complete, uses ancestors for orientation, treats children as optional, treats literal material as immutable ground truth, treats a described unit as a statement about what belongs there rather than as an absence, and never invents children. ## 13. Authoring: What A Good Weave Looks Like A weave is a tree of **units**. Each unit carries a written account of itself and children that resolve it further. The governing law is: > **A unit is a complete and true account of everything below it, at its own resolution.** A reader who reads one unit and stops holds no false belief about anything in its children. They descend for mechanism, not for correction. The rest of this section is the operative content of that sentence: what "complete" means, what "true" means, how big a unit is, and where it splits. Two amendments to the plain reading, both forced by evidence, both stated as law below: - **Completeness is bounded by level of representation.** A unit is complete about *what is there and how the parts depend on each other* (the textbase), and deliberately incomplete about *why the mechanism works* (the situation model). A unit that pre-explains everything measurably damages learning from its own children (Kintsch 1994, p. 301, reporting McNamara et al. 1996: high-knowledge readers scored 61% on problem solving after a low-coherence text vs 46% after the fully coherent one). - **"Nothing surprises them" means nothing contradicts them.** Surprise at the level of mechanism is the payload of descent. Surprise at the level of fact is a defect. --- ### A. How much belongs in one unit **A1. The unit's size is governed by the number of NEW, MUTUALLY DEPENDENT ideas a reader must hold at once for the unit's own claim to be true — not by how many facts it states, and not by how many children it has.** The "3–5 points per node" instinct aims at the wrong quantity, and it conflates three quantities that behave differently: | Quantity | Governed by | Bound | | --- | --- | --- | | (a) How many things the unit states | Nothing | Unbounded | | (b) How many NEW interacting ideas the claim requires held at once | Element interactivity | The real budget — see A2, A3 | | (c) How many children the unit has | Visual search and steering cost | A navigation dial — see D | Quantity (a) is not a cost. A set of mutually independent elements imposes an interactivity count of 1 however many there are — memorising sin(A+B) = sin(A)cos(B) + cos(A)sin(B) has "many elements but each of the elements can be memorised independently of the others because they do not interact... the element interactivity count is 1 despite the many elements" (Chen, Paas & Sweller 2023, *Educational Psychology Review* 35:63). Learning the periodic table's symbols is "a difficult, but not a complex task... this task does not impose a heavy working memory load" (ibid.). A unit listing twenty independent configuration values is long, not big. Splitting it buys nothing and costs a navigation level. Quantity (b) is not a constant of the format. It is a property of the material crossed with the assumed reader: `3x = 9` solved for `x` is 15 interacting elements for a novice; `a/b = c` solved for `a` is 28 for a novice and 1 for an expert (ibid.). Cognitive Load Theory's own authors refuse to name a threshold on principle, because element interactivity depends on the material and the reader's knowledge (Sweller, van Merriënboer & Paas 2019), and Chen et al. add that "the effects of relatively small differences in element interactivity on experimental results are not likely to be visible" — a rule discriminating 3 from 5 is below the resolution of the method that would test it. The "3–5" number itself does not come from anywhere that binds here. Cowan (2001) puts capacity at 3–5 chunks, mean ~4, but observable only under boundary conditions a reading surface violates by construction: the text stays visible, the reader re-looks, the material connects to prior knowledge. Miller (1956) described two different limits and called the shared number "a pernicious Pythagorean coincidence." Neither is a display limit or a fanout limit. And an already-formed chunk occupies one slot regardless of how much it stands for — which is why the operative variable is *new* interacting ideas, not ideas. **A2. The unit's central claim relates at most THREE things that must co-vary.** This is the one count in the literature that binds a single act of understanding. Relational complexity work finds ternary (3-way) relations processed well, quaternary relations producing significant decline in *both* speed and accuracy, and 5-way relations at chance (Halford, Wilson & Phillips 1998; Halford et al. 2005). A unit's claim is exactly such an act: one decision over dimensions that must vary together. A claim needing four co-varying dimensions is two claims. **A3. The unit's account stays well under a dozen new interacting ideas.** Operative procedure, executable by hand: mark the account's idea units; strike every one already known to the intended reader; strike every one that does not depend on any other; count the residue. The only published expository calibration is a 171-word passage on Kleefstra syndrome scored at "at least 16 interacting elements for novices to learn," counted "by calculating the unit ideas and thought groups," and classified as HIGH element interactivity (Chen, Paas & Sweller 2023) — roughly one interacting idea per 11 words of unrelieved dependency. **No measured threshold exists; this is a judgment call.** The call: a dozen. It sits below the one passage the literature labels high, and it is the number an author can check without instrumentation. **A4. Compression is not free, and a parent shrinks by carrying fewer ideas, never by carrying the same ideas in fewer words.** Reading time is governed by propositions rather than words: at a fixed 16-word sentence length, each additional proposition costs roughly 1.5 s (Kintsch & Keenan 1973, *Cognitive Psychology* 5(3), 257–274). A terse parent that dutifully preserves every child's claim is the worst artifact in the format — short and dense. The correct reduction is generalization and construction (§E), not tightening. **A5. There is no word budget.** For calibration only, not as a limit: two expert rhetoric instructors summarising 492- and 532-word texts containing 81 and 68 idea units settled unprompted at about 60 words (Brown & Day 1983, Tech. Rep. No. 270, ERIC ED225136; expert N = 2). --- ### B. The split test **B1. Volume is not a split signal.** See A1. Length alone never justifies a split. **B2. Split when the account needs "and also" between two independent relations.** One unit carries one relation. The same information cast as comparison, problem/solution, or causation is recalled better than the identical information cast as a collection of descriptions (Meyer & Freedle 1984, *AERJ* 21(1), 121–143; direction established, magnitudes not verified here). A unit organised as one relation therefore holds *more* than a unit organised as a list — structure raises the ceiling that A3 caps. **B3. Split when the claim needs a fourth co-varying dimension** (A2). **B4. Split at the seam where carry-over is smallest.** In the cyclical model of comprehension, propositions are carried across a boundary in a small buffer; an incoming proposition that shares no argument with anything carried over triggers a search or an inference, and "each one of these operations disrupts the automatic comprehension processes and adds to the difficulty of reading" (Kintsch & van Dijk 1978, *Psychological Review* 85(5), 363–394, pp. 368–372; the buffer size s = 4 is stipulated by the authors as "a reasonable value to try," not fitted). The signature of a badly placed split is therefore not overload but a referential stumble at the boundary — *wait, what is this referring to?* Honest status: the segmenting meta-analysis could not distinguish designer-chosen meaningful boundaries from two rival explanations, concluding that "none of the three postulated explanations can be ruled out" (Rey et al. 2019, *Educational Psychology Review* 31, 389–419). Meaningful boundaries remain a live, undifferentiated candidate. The seam test is theory-motivated, not meta-analytically demonstrated. Use it anyway; nothing better is available and nothing contradicts it. **B5. The unit of substance is one completed step of one relation.** The canonical segmentation cut a 140 s narrated animation into 16 segments of 8–10 s, each of which "explained one major step in the process" and carried "one or two sentences of narration" (Mayer & Chandler 2001, as reported in Rey et al. 2019: transfer d = 1.15, retention d = −0.31). Across 88 comparisons the average reported segment ran 75.49 s (SD 109.63) against an average reported whole of 1137.21 s (SD 1437.53) — the enormous SD is itself the finding: there is no optimal size, because size follows the content's own step structure. **B6. Splitting has a real price; do not split on suspicion.** Segmenting improves retention (d = 0.32, k = 67, n = 6100) and transfer (d = 0.36, k = 56, n = 4754) but makes learning significantly *slower* (d = −0.92, k = 19), and that time estimate carries significant publication bias (τ = 0.51, p = .03), so the true cost is probably understated (Rey et al. 2019). Under reader-controlled pacing — which is the weave's case — the retention benefit is marginal (d = 0.19, 95% CI [−0.02, 0.40], p = .07) while transfer holds (d = 0.45, 95% CI [0.23, 0.66]). --- ### C. The merge test **C1. A child that states no proposition its parent does not already entail is a re-read. Merge it up.** Mere re-exposure is close to worthless: readers given four study periods read a passage 14.2 times and recalled 40% at one week, while readers who read it 3.4 times and then retrieved recalled 61% (d = 1.26; Roediger & Karpicke 2006, *Psychological Science* 17(3), 249–255). Across four experiments on textbook chapters and a *Scientific American* article, "with only several exceptions, rereading did not significantly increase performance on the assessments" (Callender & McDaniel 2009, *Contemporary Educational Psychology* 34(1), 30–41). **C2. A unit whose account only names its children is not a unit.** It is a label. Absorb it into its parent. **C3. A unit with exactly one child is a defect.** It adds a level and states no relation. Each level costs a full decision plus a steering term, and novice visual search within a level is linear at T = 0.08n + 0.30 s (Cockburn, Gutwin & Greenberg 2007) — one extra sibling costs 80 ms, one extra level costs a decision. **C4. A parent over structurally simple or obviously parallel children earns nothing.** Organisational signalling had no effect at all when the topic structure was simple; it altered recall only under complex structure (Lorch & Lorch 1996, *Journal of Educational Psychology* 88(1), 38–48). **C5. Material that lengthens a unit without adding a main idea is elaboration, and it is a net negative.** Elaborated textbook passages roughly doubled reading time with no offsetting gain in memory for main ideas (Daley & Rawson 2018, *Educational Psychology Review* 31(1), 197–222), and a follow-up found reduced attention and *lower* memory for main ideas (Daley & Rawson 2021, *EPR* 33(3), 1165–1189). --- ### D. Breadth versus depth **D1. Width is a navigation dial. Depth is a comprehension dial. Set each from its own evidence; they diverge, and the divergence is not a contradiction.** **Navigation evidence favours wide and shallow.** An 8-wide × 3-deep hierarchy was reliably the slowest and left users most lost; 16 × 32 was fastest; 32-wide was not reliably worse than 16-wide, and label quality rather than memory was the operative factor (Larson & Czerwinski 1998). Best performance comes from many choices on introductory screens and fewer at deeper levels (Parush & Yuviler-Gavish 2004). Within a level, scanning is cheap and linear (Cockburn, Gutwin & Greenberg 2007); a level is not. **Learning evidence never manipulates fanout at all.** The standard review states that studies varying link counts "did not simultaneously manipulate or control for breadth (number of choices at each level), depth (number of levels), and topology" (DeStefano & LeFevre 2007, *Computers in Human Behavior* 23(3), 1616–1641), and lists that experiment as future work. **The study this question wants does not exist.** What the learning literature manipulates instead is (i) whether an explicit superordinate account exists, (ii) how many choices sit between the reader and the next unit, and (iii) how coherent an order the structure induces. On those three it is consistent: - An explicit hierarchy over a fixed body of leaves raised low-prior-knowledge readers' free recall by roughly a third (M = 26.21 vs 19.71, F(1,50) = 5.62, d = 0.67) and left high-prior-knowledge readers untouched, while lowering disorientation for everyone (F(1,50) = 17.23, f = 0.58) and fixing reading order enormously (F(1,50) = 101.98, f = 1.35, with a significant structure × prior-knowledge interaction, LPK d = 2.47, HPK d = 1.58) — Amadieu, Tricot & Mariné 2009, *Computers in Human Behavior* 25(2), 381–388, N = 54 (50 analysed), 17 sections / 681 words. - In a companion study, the effort required to understand the map was lower under the hierarchy for both novices and experts (U = 0, p = .002; U = 2, p = .005) — Amadieu, van Gog, Paas, Tricot & Mariné 2009, *Learning and Instruction* 19(5), 376–386, N = 24, 5 organising nodes over 24 content texts. That study's conceptual-knowledge result (p = .036) exceeds its own stated corrected alpha of .025 and does not carry weight here. - "In general, readers' performance was better when hypertexts had hierarchical structure" (DeStefano & LeFevre 2007). Adding lateral/semantic links on top of a hierarchy slowed navigation in 4 of 5 studies, and "the effect of number of links was inconsistent across studies although there was little evidence that more links led to better performance." - Low-vocabulary readers scored lower on hypertext than on linear text when no overview was present (p < .004) while high-vocabulary readers showed no difference (p = .14); with a persistent overview the interaction was not significant (Blom et al. 2019, *Learning and Individual Differences* 73, 124–137; 207 recruited, 198 analysed, each student reading two of the four designs). **D2. Prefer wide at the top and narrower with depth.** (Parush & Yuviler-Gavish 2004.) **D3. Add a level only when it carries a real account. Never add a level to hit a fanout number, and never split a level to hit one either.** **D4. Sibling labels are chosen for decidability, not brevity.** Label quality, not structure, was the operative factor in the widest navigation study available (Larson & Czerwinski 1998). **D5. No cross-links between siblings.** Every link is a decision paid out of the same working memory holding the evolving text representation (DeStefano & LeFevre 2007), and lateral links are the manipulation that repeatedly cost time without buying performance. **D6. Fanout has no evidenced upper bound; this is a judgment call.** The call: no cap below roughly thirty siblings, provided every label is decisive (D4) and every sibling is accounted for in the parent (E7). Two children is suspect (C3). The only shape actually tested inside a learning study is 5 organising nodes over 24 texts, and it is not a demonstrated optimum. **D7. The tree is optimised for comprehension and charges for it in retrieval.** Keeping a coarse view co-present with the detail produced measurably better synthesis — about half a grade on essays (2.47 vs 2.00 linear vs 1.95 fisheye, F(2,32) = 4.16) — at ~20% more time on question answering with *no* gain in answer quality (F(2,313) = .18, p > .5) — Hornbæk & Frøkjær 2003, *ACM ToCHI* 10(2), 119–149, N = 20. The survey conclusion: "For particular tasks such as document comprehension, no alternative has been found more effective," alongside "the current state of research fails to provide clear guidelines" (Cockburn, Karlson & Bederson 2008, *ACM Computing Surveys* 41(1), Art. 2). For pure navigation the reverse holds — elision beat co-presence on source-code navigation (Jakobsen & Hornbæk 2006), and focus+context was faster by up to 56% on other task types (Baudisch et al. 2002). If the surface has a retrieval mode, the coarse account collapses in it. --- ### E. What makes a parent account complete and TRUE of its children There is a formal theory. It is the macrostructure account (Kintsch & van Dijk 1978, *Psychological Review* 85(5), 363–394), and it licenses exactly three meaning-reducing operations. **E1. Every statement in a parent is produced by DELETION, GENERALIZATION, or CONSTRUCTION over its children. Nothing else is admissible.** - **Deletion** — "Each proposition that is neither a direct nor an indirect interpretation condition of a subsequent proposition may be deleted" (p. 366). "'Delete' here does not mean 'delete from memory' but 'delete from the macrostructure'" (p. 373). Nothing leaves the weave; it leaves this resolution. - **Generalization** — "Each sequence of propositions may be substituted by the general proposition denoting an **immediate** superset" (p. 366). The immediacy constraint is what stops a parent going vacuous. *"This function handles errors"* is a legal generalization of nothing. - **Construction** — "Each sequence of propositions may be substituted by a proposition denoting a global fact of which the facts denoted by the microstructure propositions are normal conditions, components, or consequences" (p. 366). This is the only operation that introduces a proposition no child states. **E2. Entailment is necessary. "A macrostructure must be implied by the (explicit) microstructure from which it is derived" (p. 366).** Operative test: negate any single fact in a child. If the parent's account still reads as true, the parent is not about that child — it is a teaser. Conversely, a parent statement entailed by no child is a fabrication and is deleted or demoted. Entailment is *not* sufficient, and the theory does not claim it is. A third determinant is co-equal: the controlling schema, i.e. the reader's purpose, which sets the relevance criterion. "If the schema that controls the macro-operations is not well defined, the outcome will be haphazard, and we would argue that no scientific theory can, in principle, predict it" (p. 374). **E3. Every weave declares its reader and its purpose.** Without one, two parents can both satisfy E1 and E2 and differ, and neither is wrong. The authors also concede there is no decision procedure — "whether a microproposition is generalizable in its particular context or can be replaced by a construction must be decided on the basis of intuition at present." The checks in §G are the enforcement; they are not a proof. **E4. Nothing is deleted that a remaining statement cannot be interpreted without.** "The basic constraint of the macrorules is that no proposition may be deleted that is an interpretation condition of a following proposition. In fact, this also guarantees that a macrostructure itself is connected and coherent" (p. 366). This is the non-arbitrary lifting rule: a detail is lifted into the parent not because it is important — unfalsifiable — but because something else in the parent is uninterpretable without it. A parent therefore cannot be assembled by ranking children and taking the top *k*; ranking is blind to interpretation dependencies and will drop exactly the connective facts. **E5. Standalone test.** Delete every child. The parent still reads as a connected account. Coherence here is referential — argument overlap between propositions (p. 367) — which the authors defend explicitly as a tractable proxy, "neither a necessary nor a sufficient criterion linguistically," rather than a definition. **E6. Completeness is relational, not extensional. The parent states which way each dependency runs.** A summary can be produced from the textbase alone, be factually correct, and confer nothing: the reader "knows that blood turns purple because it cannot get rid of carbon dioxide through the lungs — that is what the text states — but not why this is so. The text might as well have asserted [the reverse] — it would make equally little sense to the reader" (Kintsch 1994, *American Psychologist* 49(4), 294–303, p. 295). Reader satisfaction does not detect this: "a feeling of understanding at the level of the textbase can conceal incomplete understanding at the level of the situation model" (p. 302). **Operative test: from the parent alone, could a reader tell "therefore" from "because"?** A parent that lists what its children do, without the relation among them, fails. **E7. Coverage at each level is total.** Silence about a child is a negative signal, not a neutral one: in a half-signalled text, signalled content was recalled equally well as in a fully signalled text, but *unsignalled* content was recalled worse than the same content in a text with no signals at all (Lorch & Lorch 1996). A parent that accounts for some children and omits the rest leaves the omitted children worse off than no parent would. **E8. Parts go up; interactions go down.** Naming the components and their characteristics before the account of how they interact is among the best-evidenced moves in instructional design — median d = 0.75–0.88 depending on which of Mayer's syntheses is read (d = 0.88 across ten experiments, Mayer 2014, "Multimedia Instruction," Ch. 31 in *Handbook of Research on Educational Communications and Technology* 4th ed., pp. 385–399; 13 of 16 tests at d = 0.75 in his 2017 summary; 10 of 10 at d = 0.78 in his 2021 meta-analysis, which states the boundary as possibly not applying to high-prior-knowledge learners). This is the operational division of labour between a parent and a child. **A parent that describes interactions is doing its child's job at lower fidelity — that is the lossy-teaser failure.** **E9. The parent is written as an ORGANIZER, not as a précis.** Across 27 advance-organizer studies, the *poor* organizers were "specific factual pre-questions, summaries, outlines"; what worked were concrete models, analogies, examples, and sets of general higher-order rules phrased in already-familiar terms (Mayer 1979, "Twenty years of research on advance organizers: Assimilation theory is still the best predictor of results," *Instructional Science* 8(2), 133–167; 10 clear advantages, 13 under predicted conditions, 4 null). Mayer's review is an argued refutation of an earlier negative review (Barnes & Clawson 1975) by an interested party, and he concedes it is "still not possible to offer a fool-proof definition of what constitutes an advance organizer." It also reports a genuine trade: organizer readers excelled on far transfer while control readers recalled more specific technical detail. A meta-analysis of 135 studies reports a small facilitative effect (Luiten, Ames & Ackerson 1980, *AERJ* 17(2), 211–218; no effect size is quoted here because none could be verified). **Authoring test:** *if you can produce the parent by deleting sentences from the children, you have written an outline.* If the parent asserts something true of all children that appears verbatim in none, you have written an organizer. **E10. The operations that produce a table of contents.** Each is a documented novice behaviour, not a stylistic lapse (Brown & Day 1983): - **Copy-delete.** "(a) read text elements sequentially; (b) decide for each element on inclusion or deletion; (c) if inclusion is the verdict, copy it more or less verbatim from the text." Any pipeline that builds a parent by selecting and copying from children is executing this strategy. - **Coverage as the quality gate.** Deletion is at ceiling for adults and shows no significant age effect — college students deleted 93% of trivial and 95% of redundant material; junior-college students 92% and 94%. It discriminates nothing. Do not gate on "does the parent cover the children." - **Failure to invent.** The discriminating operation is writing a proposition no child states: experts did it on 84% of warranted occasions, four-year college students on 49%, tenth graders on about a third. Superordination showed the same gap — experts perfect against 70% for college students. - **Inheriting the source's segmentation.** Experts "favored the paragraph combining strategy and attempted to use it whenever possible" and worked top-down, "selecting or inventing [topic sentences] first and then writing their summary around and in support of the topic sentences." Younger subjects were "'captured' by the paragraph structure provided in the input passage." **A tree whose unit boundaries mirror the source's existing divisions is, by this evidence, a novice tree.** (Expert N = 2; and experts could not state their own rules when asked afterwards — do not elicit the criterion by interviewing a good summariser.) - **Enumeration without relation.** Both structured and unstructured overviews improved memory for topics, but without a specific reader goal the unstructured menu-list overview produced a fragmented knowledge structure (Dee-Lucas & Larkin 1995, *Cognition and Instruction* 13(3), 431–468, reported via Hornbæk & Frøkjær 2003). **E11. A parent is complete at the level of fact and deliberately incomplete at the level of mechanism.** Perfect pre-organisation is achievable and it has a measured cost. An outline consistent with the following text improved verbatim verification and roughly halved inference performance (Mannes & Kintsch 1987, *Cognition and Instruction* 4(2), 91–115; figures read from a bar chart in Kintsch 1994, approximately 57% vs 47% on verbatim and 27% vs 45% on inference — approximate, do not quote as exact). "Because everything fits so well into preexisting slots, there is little inducement for elaborating a complex situation model" (Kintsch 1994, p. 297); "a text that spells everything out and explains everything to the last detail does not leave enough room for constructive activities on the part of the learner" (p. 301). The effect reverses by expertise: on problem solving, high-knowledge readers scored 61% after the low-coherence text vs 46% after the coherent one, while low-knowledge readers scored 17% vs 30% — the gap *penalises* novices (Kintsch 1994, p. 301, reporting McNamara et al. 1996, *Cognition and Instruction* 14(1), 1–43). And the catch is explicit: "It must indeed be possible for a diligent reader to generate whatever was not made explicit in the text. Thus, not any poorly written, disorganized text will do." So the gap is placed precisely: at the mechanism, never at the fact. **E12. Any claim that depends on exact wording is carried verbatim in a leaf and never paraphrased upward.** Repetition of technical prose builds the conceptual level while verbatim recognition *falls* (Mayer 1983, *Journal of Educational Psychology* 75(1), 40–49; 88 undergraduates, passages heard 1–3 times; reported here from secondary summaries, primary not read). Gist and verbatim are encoded in parallel rather than one derived from the other, and readers default to the vaguest gist that answers the question, descending only when it does not (Reyna 2012, *Judgment and Decision Making* 7(3), 332–359). The same mechanism produces confident error: gist-based false memories "will be more consistent over time than true memories" (ibid.). A signature, a threshold, an error string, a flag name paraphrased at a parent's resolution will be remembered wrong even though it was read correctly. **E13. A child that overturns something its parent implies says so explicitly, in the child.** Readers cannot be delegated this check, and more framing above makes them worse at it: the probability of an undetected contradiction rose from .064 with one introductory paragraph to .511 with three (F(1,92) = 19.86, p < .001, N = 94), with subjects explicitly told that contradictions occurred and that finding them was the task — and still missing up to 51% (Glenberg, Wilkinson & Epstein 1982, *Memory & Cognition* 10(6), 597–602). The mechanism is that more prior structure supplies more places to attach conflicting material without the conflict surfacing, and "a reader assumes by default that comprehension is progressing smoothly." The authors note the effect may be conditional on how high a coherence goal the reader adopts, which a navigable weave may raise. Parent/child consistency is enforced at authoring time, mechanically, against E2 and E4 — never by review reading. --- ### F. Redundancy across levels **F1. The same idea appearing at three resolutions is correct, and it is not what the redundancy principle prohibits.** That principle is about *modal* redundancy: identical words delivered simultaneously as speech and on-screen print while a graphic competes for the visual channel (Mayer 2014, Ch. 31, median d = 0.72 across five studies — note that Mayer's own 2021 meta-analysis downgrades it to 8 of 12 tests at median d = 0.10). The one experiment to separate the constructs factorially found them opposite in sign: *content* redundancy raised learning and lowered cognitive load, while *modal* redundancy did the reverse (Albers, Trypke, Stebner, Wirth & Plass 2023, *British Journal of Educational Psychology* 93(S2), 339–352; 2 × 2 within-subject, N = 46, purpose-built material — one small study, treat as licence, not as proof). **F2. Exactly one rendering of a given statement is visible at a time.** This is the operative content of F1's prohibition. A parent's sentence must not be re-shown as a caption while its child is open. The second encounter is a separate act by the reader, never a co-present stream. **F3. The mechanism is recursive re-filtering, and its return saturates.** Macrostructure is built by applying the macrorules again under a stricter relevance criterion, "until only a single macroproposition (essentially a title for that text unit) remains" (Kintsch & van Dijk 1978, p. 374). A proposition selected as relevant at *k* levels has reproduction probability 1 − (1 − m)^k (ibid.; m̂ = .391 for immediate recall, Table 8, p. 387 — fitted parameters from one 1,300-word text under an assumed independence of storage attempts, not a measured curve). The curve rises steeply and then flattens. **F4. Depth is a filter over one body of content, not a partition of it.** This is why every level can be an account of everything below it: each level's output is the whole content passed through a stricter criterion. A parent states the *same* content under a stricter relevance criterion — not *different* content. **F5. Whatever sits at the top is the retention set.** High-level propositions are recalled two to three times better than low ones (ibid., pp. 365, 370). The authors' own reading is that this is a processing-frequency effect — superordinate propositions stay in the carry-over buffer across more cycles and get more independent storage attempts — which the weave reproduces by construction, since a reader re-encounters the parent's content while working through every child. The corollary is a cost: material omitted from the higher levels is systematically forgotten, so partial coverage in a parent is actively destructive, not merely incomplete (see E7). **F6. Redundancy earns its keep only when each descent is a DIFFERENT act of comprehension.** Re-exposure alone is near worthless (C1) and it inflates confidence: readers who restudied predicted they would remember better than readers who retrieved (d = 0.54 and d = 0.61) and were wrong (Roediger & Karpicke 2006). What repetition of technical prose does when it does anything is build the conceptual level selectively while verbatim declines, and one presentation preceded by an organizer performed about like three (Mayer 1983 — secondary). A related study reports a Levels × Presentations interaction, with secondary summaries stating that the levels effect increased with repetition and that no repetition effect appeared when an organizer preceded the first presentation (Bromage & Mayer 1986, *JEP* 78(4), 271–278; direction secondary-sourced only, primary not read). **Operative test:** each level changes the *kind* of representation being built — frame, then mechanism, then verbatim detail. A child that changes only length is a re-read (C1). **F7. Do not claim spacing.** The spacing effect is large and robust (36.7% vs 47.3% across 271 comparisons and 14,811 participants, t(540) = 6.6, p < .001; 32.8% vs 62.2% at 8–30 day retention — Cepeda, Pashler, Vul, Wixted & Rohrer 2006, *Psychological Bulletin* 132(3), 354–380) but it is item recall at day-scale gaps, and its surviving mechanisms all require a temporal gap. For text specifically, distributing the second reading was *worse* immediately (t(137) = −2.93, p = .004) and no better after a week (t(137) = 1.05, p = .297) — it merely forgot less (Greving & Richter 2018, *Frontiers in Psychology* 9:2517, N = 191). Three resolutions read in one sitting is near-massed. A spacing-like benefit requires designing for return visits, which is a navigation property, not an authoring one. **F8. The redundancy turns harmful under expertise; the escape is one action.** The same assistance yields d = +0.505 for low-prior-knowledge learners and d = −0.428 for high-prior-knowledge learners (Tetzlaff, Simonsmeier, Peters & Brod 2025, *Learning and Instruction* 98, 102142; 176 effect sizes, 60 studies, N = 5924). Redundant information "is frequently difficult to ignore" (Kalyuga, Ayres, Chandler & Sweller 2003, *Educational Psychologist* 38(1), 23–31), so the expert's cost scales with the parent's length while the novice's benefit comes mostly from the frame, which is short. The asymmetry sets the default: helping novices helps more than sparing experts costs. **Show the parent by default; make descent and skipping each one action; keep the parent short.** Honest contradiction, unresolved: the segmenting meta-analysis moderates the *other* way — retention benefit d = 0.29 with no prior knowledge, −0.12 (n.s.) with some, and d = 0.73 with high prior knowledge (Q = 20.49, df = 2, p < .001), which the authors themselves flag as contrary to their hypothesis, with transfer unmoderated (Rey et al. 2019). Expertise reversal for *assistance* and expertise reversal for *segmentation* are demonstrably not the same phenomenon. No evidence settles which governs a layered document. **F9. Elision is not restatement.** A level the reader can leave collapsed is opened but under-attended: subjects opened almost all initially collapsed sections yet spent about 30% less time on them, and incidental learning fell accordingly (3.42 correct vs 4.20 linear and 4.58 overview+detail, F(2,32) = 6.80, p < .01) while reading got faster (37.4 min vs 44.4 and 44.5) — Hornbæk & Frøkjær 2003. A parent must be a *substitute* for its children, not a pointer to them. **F10. A coarse account can beat the full material, so a parent is not a concession.** Summaries of textbook chapters outperformed the full chapters at 20 minutes (.793 vs .693) and one week (.675 vs .600), with the 6–12 month difference not significant (.595 vs .575, near the 50% chance floor) and a transfer advantage only marginal (t(186) = 1.89, p < .1); the authors' own claim is that learning from summaries is "at least as good as reading the original text" (Reder & Anderson 1980, *Journal of Verbal Learning and Verbal Behavior* 19(2), 121–134). Note the limit: no condition in that work ever gave the same content at two resolutions, so it does not test the stack. **F11. Do not cite the spiral curriculum or progressive disclosure as support.** "Although there is no clear empirical evidence of the overall effects of the spiral curriculum on student learning, 'features' of that curriculum have been linked to improved learning outcomes" (Johnston 2012, ERIC ED538282). The measured win in technical documentation is *cutting*, not layering: a minimal manual of 45 pages, "less than a quarter the length of the commercial training manual," produced 40% less learning time, t(17) = 3.06, p < .01 (Carroll, Smith-Kerker, Ford & Mazur-Rimetz, "The Minimal Manual," *Human-Computer Interaction* 3(2)). The mechanisms this section relies on each carry their own evidence; the traditions add rhetoric and nothing else. **F12. Three levels. No evidence bears on 2 vs 3 vs 4; this is a judgment call.** The call: three, with a fourth only where the material's own structure forces it. The reproduction curve saturates (F3), each level costs a full navigation decision (D1), and segmentation costs time (B6). --- ### G. The face of a unit: gist, distillate, figure What a reader meets when a unit is the active world, before any descent, is the unit's **face**. The face is a convention about how the account is *composed*, not a new construct: everything below lives in the summary field and in ordinary content blocks. The core gains nothing. **G1. The gist.** The summary paragraph — the complete-and-true account §13 A–F already demands. It is prose, it is short, and it is a substitute for the children (F9), never a pointer at them. **G1a. Short breath.** No element of a face or gist is an essay. A summary rung or a gist paragraph holds one claim and stays within three to four set lines — roughly sixty to ninety words — and a bullet or a table row stays on one line. An account that needs more room is not tightened into density (A4 forbids that trade); it CHANGES SHAPE — into bullets, a table, a timeline (G3a) — or it pushes mechanism down a level, where §13's whole structure already pays for it. No study fixes the line count; the budget is a judgment call, stated as one (compare F12), and the proposition ceiling (A4) is the evidence-backed bound behind it. **G1b. The spill rule: a weave has no spoilers.** A unit's account is written as if by someone who has read everything below it and is summarizing it whole — outcomes, endings, conclusions, and the core message included, end to end. It is never a teaser: no withheld payoff, no "we will see," no hook standing where a fact belongs. A reader who stops at this unit walks away with all the ideas at this resolution — what descent adds is texture, mechanism in the flesh, and the verbatim experience, never a truth that was held back. The hook has its own rung (`preview_summary` may invite); the gist and its elements spill. A gist that protects a surprise fails completeness (E), whatever else it does well. **G1c. The account speaks as the work, never about the weave.** A summary is the work's own voice, compressed — active, first-order, carrying the ideas, conclusions, and lessons as the author would state them in a denser edition: "Business exists to serve; waste, greed, and finance betray it," not "Ford argues that business exists to serve." Descriptive distance is a residue of note-taking, and the reader came for the work. And the medium never mentions itself: no unit counts, no "leaves," no "this weave" — scaffold-talk inside an account tells the reader about the container when they asked about the contents. Two bounded exceptions: a unit whose kind is interpretation or criticism speaks as the critic it is; and a weave whose SUBJECT is the format itself uses the format's vocabulary, because there it is the contents. **G1d. Plain words.** The simplest wording that carries the idea, and as few words as will carry it. Complexity in the material is not a license for complexity in the account: a difficult book compresses to simple core points in plain language, or the compression has not happened. A term of art earns its place only where replacing it would lose meaning the reader needs; everything else is said the way one person tells another. Simple is not vague (the guard rails of §13 E still bind every fact) and not casual — it is the shortest honest path to the idea. **G2. The distillate.** Two to five bullets, written as a markdown content block in the unit's own material, each carrying one load-bearing fact — a number, a name, a mechanism — taken from the level below. The gist and the distillate have different jobs: the gist is read, the distillate is *scanned*, and a returning reader re-anchors on the bullets without re-reading the paragraph. A bullet that restates the gist's phrasing is padding; a bullet the gist silently depends on is a completeness defect (E). No evidence crosses summary-plus-bullets against summary-alone at equal length; the composition is a judgment call, stated as one (compare F12). **G3. The figure.** Where the unit's material affords a real structure — a flow, an arithmetic, a timeline, a comparison — one visual content block (form `svg`, `diagram`, or a named image) drawn from the unit's own facts. Words-plus-picture beats words alone for explanations of mechanism (Mayer's multimedia principle); the effect rides on the mechanism being depicted, so a figure earns its place only where there is a mechanism, and a decorative figure is noise wearing the contract's clothes. Most units have no figure, and that is the correct count for them. **G3a. The open gist's element vocabulary.** The gist content of a unit — what it shows when it is the active world — composes from five element types, in any combination the claims call for: a **paragraph** (the gist itself), **bullets** (numbered where order carries meaning, plain where it does not), a **table** for a comparison, a **diagram** for a mechanism, a **timeline** for a dated sequence. The shape is chosen by the claim, never by variety; two elements that state the same claim in different shapes are one statement rendered twice (F2). The collapsed face draws from the same vocabulary but takes ONE element (G6); the open gist may take several because its job is the complete account. **G3b. Doors.** In authored prose — bullets, gists, faces — a fact that a child carries is linked to that child (§4.1 unit links): `[the beef trolley](#ch5.p4)`. A well-faced unit lets a reader decide where to dig, and a door is that decision made one activation cheap; a tool may preview the child's collapsed reading on approach. Verbatim material never carries links, because material is never edited. **G4. Faces are uniform across siblings.** If one child of a parent leads with a gist and bullets, its siblings do too. A reader's scan pattern is learned once per level, not once per unit. **G5. The face is renderer-independent.** A tool that shows only summaries still holds a valid weave; a tool that renders figures inline gets them from ordinary content blocks. Nothing about the face changes parsing, validation, or identity. **G6. The collapsed face may be structured, and less is the whole craft.** A unit may declare one or more `face`-role content blocks (§4.1): a tiny table, three bullets, a five-row timeline, a small diagram. The contract for the collapsed reading is strict where the open gist's is generous: - **One element.** A tool shows at most one face block when the unit is seen from outside — the first. A collapsed reading that needs two elements is an open reading that has not admitted it. - **Fewer rows than the gist.** The face states the overall idea in less than the unit's own gist content — three to five rows is the working ceiling. It compresses by the same macrorules as a summary: deletion and generalization, never shrunken type. - **The shape is chosen by the claim.** A comparison faces as a table; a sequence as a timeline; independent facts as bullets; a mechanism as a diagram; and a unit whose claim is genuinely one sentence faces as prose — the summary ladder already carries that, and such a unit declares no face block at all. - **Same facts, another resolution.** A face block restates facts the unit's gist already accounts for. A fact that appears only in the face is a completeness defect in the gist (E), not a feature of the face. --- ### H. Checklist Run per unit, bottom-up. A failure is a defect, not a preference. **Truth and completeness (E)** 1. **Claim in the account, subject in the title.** The unit's summary asserts something; the title addresses the subject directly in two to five words and is not a sentence. (§2.2.1) 2. **Invention.** The parent's claim is true of all children and appears verbatim in none. (E9, E10) 3. **Entailment.** Every parent statement is a deletion, an immediate-superset generalization, or a construction over the children. Negate any single child fact — if the parent still reads true, it is not about that child. (E1, E2) 4. **Interpretation conditions.** Nothing is deleted that a remaining parent statement cannot be interpreted without. (E4) 5. **Standalone.** With all children deleted, the parent still reads as one connected account. (E5) 6. **Total coverage.** Every child is accounted for. No child is silently unmentioned. (E7) 7. **Direction.** For every dependency among children, the parent states which way it runs. A reader can tell "therefore" from "because". (E6) 8. **Parts up, interactions down.** The parent names the components and their characteristics; the children carry how they interact. (E8) 9. **Gap placement.** The parent is complete at the level of fact and silent at the level of mechanism — never the reverse. (E11) 10. **Verbatim.** Every exact string, number, signature, or flag name lives verbatim in a leaf and is not paraphrased upward. (E12) 11. **Revision marked.** A child that overturns something its parent implies says so, in the child. (E13) 12. **Purpose declared.** The weave states the reader and purpose that set its relevance criterion. (E3) **Size (A, B, C)** 13. **One relation.** The account turns on a single relation — comparison, cause, problem/solution, sequence — not a collection of descriptions. (B2) 14. **Ternary ceiling.** The claim relates at most three things that must co-vary. (A2) 15. **Interacting-idea count.** Strike ideas already known to the intended reader and ideas that depend on nothing; the residue is well under a dozen. (A3) 16. **No volume splits.** No unit was split for length alone. (B1) 17. **Seam.** Every split falls where referents carry over least; no child opens with an unresolvable reference. (B4) 18. **Child earns its place.** Every child states at least one proposition not inferable from its parent. (C1) 19. **No lone children.** No unit has exactly one child. (C3) 20. **No pointer units.** No unit's account merely names its children. (C2) 21. **No padding.** No unit contains material that lengthens it without adding a main idea. (C5) 22. **Boundaries recut.** Unit boundaries are not inherited from the source's own segmentation where meaning cuts differently. (E10) **Shape and surface (D, F)** 23. **Depth earns itself.** Every level carries a real account; none exists to hit a fanout number. (D3) 24. **Labels decide.** Every sibling label lets a reader choose without opening it. (D4) 25. **No sibling cross-links.** (D5) 26. **One rendering.** A given statement is visible in exactly one place at a time. (F2) 27. **Skippable.** The parent shows by default; skipping it and descending are each one action. (F8) 28. **Each descent changes kind.** Frame, then mechanism, then verbatim detail — no level differs from its parent only in length. (F6) **Face (G)** 29. **Gist present.** The unit's summary is a substitute for its children, not a pointer at them. (G1, F9) 30. **Distillate where it pays.** A unit standing on three or more independent facts carries 2–5 bullets, each holding a number, name, or mechanism; none restates the gist's phrasing. (G2) 31. **Figure only on affordance.** A visual exists exactly where the unit's material holds a flow, arithmetic, timeline, or comparison — and nowhere else. (G3) 32. **Uniform faces.** Siblings at one level compose their faces the same way. (G4) 33. **Shape by claim.** Every gist element's type — paragraph, bullets, table, diagram, timeline — is the one its claim calls for; no claim is rendered in two shapes. (G3a, F2) 34. **Bullets are doors.** Each authored bullet whose fact a child carries links that child; no link targets an id that does not resolve. (G3b) 35. **Short breath.** No gist paragraph or summary rung runs past three to four set lines; what needs more room changes shape or moves down a level, never densifies. (G1a, A4) 36. **The spill.** The account states every outcome, ending, and conclusion at its resolution — nothing withheld for effect; teaser language in a gist is a defect. (G1b) 37. **Direct titles.** The title addresses the unit's subject in two to five words, never a sentence; the claim lives in the summary. Child boxes carry the title where it fits, grandchildren the 1–2 word name, and below that the icon. (§2.2.1) 38. **The work's own voice.** The account is active and authorial — the work compressed, not notes about it — and never mentions the weave, its units, or its counts; interpretation units and format-subject weaves excepted. (G1c) 39. **Plain words.** Every idea is stated in the simplest wording that carries it; a term of art survives only where its replacement would lose needed meaning. (G1d) --- ### I. What this section does not settle Named so that nobody mistakes a judgment call for a result. - **No study crosses branching factor with depth against comprehension.** The standard review says so explicitly and lists it as future work (DeStefano & LeFevre 2007). Every fanout number in this section is a navigation result or a judgment call. - **No measured threshold for unit size exists.** CLT declines to give one on principle (Sweller, van Merriënboer & Paas 2019) and states that small differences are undetectable (Chen, Paas & Sweller 2023). A3's dozen is calibrated against a single published expository count. - **The number of levels is unevidenced.** F12 is a judgment call. - **Whether one piece of writing can be both a complete substitute and a good preparation is untested.** Summaries and outlines are the documented *poor* organizers (Mayer 1979) while summaries beat full texts as substitutes (Reder & Anderson 1980) — not a contradiction, but two different jobs asked of one artifact. **This is a judgment call.** The call: write the parent as an organizer first. The substitute property follows from entailment-completeness (E2, E7); the organizer property does not follow from coverage, and coverage is at ceiling for anyone (E10). - **Every study cited on comprehension uses linear prose or short animations read once, in documents of 17–25 nodes and 680–2000 words.** Transfer to a navigable tree over a large corpus, where the reader may stop anywhere and the same content appears at three resolutions, is an inference in every case. The mechanisms generalise — order, parent relations, decision cost, expertise-relativity, coverage. The shapes do not. ## 14. Non-Goals WeaveLang is not a programming language, not a replacement for source code, not a replacement for UML, BPMN, RDF, OpenAPI, or tracing systems, not a visual notation, and not a guarantee that a generated summary is correct. It carries source code without becoming one. A `content` block is opaque to the core: the language never parses, evaluates, or type-checks what is inside it. It only knows where the material sits in the structure of meaning. ## 15. Examples ### 14.1 One Function, Partly Written ```weave weave "rate-limit" kind software.capability { unit allow kind software.function "allow" { ref "src/limit.ts:allow" summary "Return false once the tenant's window is full. Never block on Redis: a limiter that fails closed takes the service down with it." content typescript export async function allow(tenantId: string): Promise { const key = `rl:${tenantId}:${Math.floor(Date.now() / 1000)}` end content unit count kind software.body "Counting the request" { summary "Increment the key and set a 60-second expiry on first use. Any Redis error counts as zero, so an outage lets traffic through." } content typescript return count <= 1000 } end content } } ``` ### 14.2 A Class, Mostly Described ```weave weave "invoice" kind software.module { unit invoice kind java.class "Invoice" { ref "src/main/java/billing/Invoice.java" summary "An immutable invoice. Totals are computed once at construction, so a line item cannot be added after a total has been read." content java public final class Invoice { end content unit fields kind java.fields "State" { summary "The tenant id, an immutable list of line items, the currency, and the computed total, all final." } unit ctor kind java.constructor "Constructor" { summary "Takes tenant, items and currency; copies the item list defensively and computes the total before returning." } unit total kind java.method "getTotal" { summary "Returns the precomputed total. No rounding happens here — rounding is applied per line item at construction, so the sum is exact." content java public Money getTotal() { return total } end content } content java } end content } } ``` One method is written because its rounding behaviour is the thing a reader gets wrong. The rest is described, because it is what anyone would expect. ### 14.3 A Book, Read Closely In One Place ```weave weave "Crime and Punishment" kind book { unit thesis kind book.theme "Freedom requires self-knowledge" { summary "The novel ties freedom to painful self-recognition, and refuses to let its protagonist reason his way around it." unit part.one kind book.part "Part One" { summary "Raskolnikov reasons his way to the murder, and the reasoning is presented as sound until the act makes it absurd." unit ch.one kind book.chapter "Chapter I" { summary "The rehearsal walk. He tests the route, the bell, and himself." unit passage.opening kind book.paragraph "The opening" { summary "The narrator withholds the destination for a full paragraph, so the reader arrives at the door as unprepared as the protagonist pretends to be." content On an exceptionally hot evening early in July a young man came out of the garret in which he lodged in S. Place and walked slowly, as though in hesitation, towards K. bridge. end content } unit rest kind book.scenes "The pawnbroker's flat" { summary "He climbs, rings, is admitted, and conducts a transaction whose ordinariness is the point." } } unit ch.rest kind book.chapters "Chapters II to VII" { summary "Marmeladov's confession, the letter from his mother, and the dream of the horse — each supplying a reason he will later claim was the reason." } } } relation m1 kind book.foreshadows { from ch.rest to thesis label "Marmeladov confesses what Raskolnikov will not" } } ``` ### 14.4 A Standard ```weave weave "RFC 9110 — HTTP Semantics" kind document { source rfc kind document.spec { uri "https://www.rfc-editor.org/rfc/rfc9110" title "HTTP Semantics" } unit contract kind document.spec "One shared meaning for HTTP messages" { summary "Defines methods, status codes, and header semantics shared by all HTTP versions." unit req.idempotency kind document.requirement "Idempotent methods" { ref "9.2.2" summary "A client may repeat GET, PUT, or DELETE without additional effect, which is what makes automatic retry safe." content A client MUST be able to repeat an idempotent request without additional effect beyond that of the first request. end content } unit req.conditional kind document.mechanism "Conditional requests" { ref "13" summary "A validator turns a request into a question about what changed." unit q.weak_etag kind document.ambiguity "Do weak validators satisfy range requests?" { ref "13.1.3" summary "The section constrains this; implementations disagree." confidence 0.4 } } } relation cond_needs_validator kind document.depends_on { from req.conditional to field.etag label "conditional requests are meaningless without a validator" } } ``` ## 16. Summary ```txt Anything meaningful is a unit. Any connection that is not containment is a relation. Any nesting is a depth. A unit's material is its parts, in order: what is written, and what is described. Any domain is a string. ``` Five constructs, seven symbols, no enums in the middle. The core stays small so that the unseen case — the material nobody has woven yet — still fits.