Conventions for Specifications and TRMs

This document defines how the technical documents of Peios are written and how they are read. It governs two classes of document:

• the specifications of this anthology — the four books that state what must be true for a Peios system and for the parties that interoperate with one; and
• the technical reference manuals — the per-component books that describe exhaustively how one piece of Peios actually behaves.

It covers normative language, the structure a document of each class takes, how any part of either is cited, and the style rules both share.

1.1.1 What this document does not cover #

• Task documentation — the tutorial and how-to material written for people using or building on Peios. That has its own house style, maintained separately, and neither the normative apparatus of a specification nor the exhaustiveness of a reference manual applies to it.
• Any behaviour of Peios itself. Nothing here specifies what a Peios system does. This document constrains documents.
• The renderer. The static site generator that builds these books supplies the chapter and article numbering this document's addressing scheme relies on, and is specified separately.
• Editorial process. How a document is reviewed, by whom, and when it is considered ready are project conventions rather than document conventions.

1.1.2 Position in the anthology #

This document sits ahead of the four specification books because it is read first. It is not itself a specification: it defines no Peios behaviour, and no implementation conforms to it. What conforms to it are documents.

Every technical document in this corpus is either a specification or a technical reference manual, and the difference is not a matter of subject, length, or tone. It is a matter of how many independently written parties have to reproduce the same computation in order to agree.

• If one party computes something and everyone else calls it, that is a manual.
• If a second party must reproduce it identically, or the two produce divergent results, that is a specification.

1.2.1 The sharper form of the test #

A third party wanting to interact with something directly is necessary but not sufficient. What makes something a specification is a second role — a party whose behaviour the other side depends on.

A system-call surface has no second role. It has callers, and callers are documented rather than specified. The question that settles it is which party is asking: a registry source answers the kernel's questions, and a package producer emits what a consumer validates, so both of those are specifications. Nobody serves mount(2), so that is a manual.

1.2.2 Most subsystems split #

The expected outcome for any given subsystem is both: a specification stating the contract, and a manual covering the nuances of how one implementation fulfils it.

Binary signing is a specification because a third party can sign binaries; the kernel's verification machinery behind it is a manual. Security descriptor inheritance is a specification even though there is one kernel, because the kernel does not propagate a descriptor change and every userspace tool that propagates one has to agree. A package's manifest schema is a specification; how a package manager decides which of several candidates to install is a manual.

A subsystem whose only external surface is its own syscalls contributes no specification at all, and that is a legitimate outcome rather than an oversight.

1.2.3 Consequences for the reader #

A specification tells you what you may rely on. Its statements are commitments, and an implementation that contradicts one has a defect.

A manual tells you what a component does. Its authority comes from the software: where the two disagree, the software is right and the manual is stale. A manual makes no stability commitment, and nothing in one is a promise about a future version.

That difference is why the two classes are written so differently, and why a reader must be able to tell at a glance which one is in front of them (§4.2).

1.3.1 Normative keywords #

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY in this document are to be interpreted as described in RFC 2119. Their meaning within a specification is defined in §2.1.

Text set off as a note is informative.

1.3.2 The two halves carry different weight, deliberately #

Chapters 2 and 3 govern specifications and are normative throughout. A specification that violates one of their requirements is malformed, and the requirement is stated as such.

Chapter 4 governs technical reference manuals and is deliberately lighter. Most of it is SHOULD and MAY, and some of it is offered as guidance carrying no normative weight at all. A manual is a description of software rather than a contract, so prescribing its shape tightly would be prescribing the shape of the software.

Two rules in chapter 4 are exceptions and are stated as MUST NOT, because they are what makes the class a class rather than a matter of taste: a manual carries no RFC 2119 keywords (§4.2), and a manual does not narrate the difference between itself and a specification (§4.4).

Chapters 5 and 6 apply to both classes.

1.3.3 Reading order #

An implementer needs §2.1 and chapter 5, and nothing else.

An author needs the chapter for the class they are writing, then chapters 5 and 6.

A reader trying to work out which class a document belongs to, or why a given fact is documented in one place rather than another, wants §1.2.

A specification MUST declare its use of RFC 2119 keywords in its conventions article (§3.1).

The following keywords, when they appear in uppercase, MUST be interpreted as described in RFC 2119:

A specification MAY use a subset. Its conventions article MUST list which keywords it uses.

2.1.1 Lowercase is not a keyword #

The same words in lowercase carry no normative weight. This is not a loophole to be exploited: a lowercase "must" in a passage that reads as a requirement is an editing defect, because the reader cannot tell whether an obligation was intended.

An author writing a requirement MUST use the uppercase form. An author writing description SHOULD reach for a verb that is not a keyword at all — "is", "carries", "produces" — rather than relying on case to carry the distinction.

2.1.2 Requirements are stated against a role #

A specification with more than one party MUST state each requirement against the role rather than the program (§3.2). An obligation on a consumer binds whatever process is acting as the consumer, and one program may serve different roles on different interfaces.

2.1.3 SHOULD means something #

A SHOULD is not a soft MUST and not a decorative MAY. It marks a requirement with a real exception, and a specification using one SHOULD say what the exception is — either inline or in an adjacent note.

2.2.1 Everything is normative by default #

All text in a specification is normative unless it is explicitly marked otherwise.

2.2.2 Marking #

Informative text MUST be marked, using a note callout:

> [!NOTE]
> This paragraph gives context and defines no behaviour.

An inline aside introduced by "For example" or "Note:" is also informative.

2.2.3 What informative text may not do #

Informative text MUST NOT contain an RFC 2119 keyword used in its normative sense. Where a note needs to refer to required behaviour, it MUST cite the normative statement that defines it rather than restating it.

2.2.4 What informative text is for #

Rationale, worked examples, the attack a rule defends against, and the alternative that was considered and rejected.

A specification SHOULD carry that material rather than omit it. A rule whose reason is unrecorded is a rule that a later revision will remove as redundant, or preserve for the wrong reason — and a wrong reason is what the revision after that will reason from.

A specification that includes pseudocode MUST document its conventions in its conventions article (§3.1).

The conventions below are established across this corpus and SHOULD be used, so that a reader moving between books does not have to relearn the notation.

Pseudocode MUST appear in a fenced code block.

A specification MAY use further conventions — and, or, not for boolean operators, or named error returns — and MUST document any it uses.

2.3.1 Pseudocode is normative #

Pseudocode in a specification is a normative statement like any other, and MUST be read as one. It is not an illustration of a rule stated elsewhere; where it is meant as illustration, it belongs in a note (§2.2).

A specification book and each of its chapters carry a fixed opening and closing shape, so that a reader arriving at any chapter finds the same things in the same places.

3.1.1 Book level #

A book MUST open with an introduction chapter containing:

3.1.2 Chapter level #

A chapter specifying a protocol or a format MUST open with:

and SHOULD close with an Extension article (§3.4) and a Conformance article (§3.4), in that order, before any appendices.

A chapter defining a data structure rather than a protocol has no roles and no conformance obligations of its own, and is exempt from both.

3.1.3 Terminology delegates rather than repeats #

A terminology article MUST define the terms the chapter introduces. A term already defined elsewhere in the corpus MUST be delegated by reference rather than redefined:

Terms defined in §5.2 — package, manifest, payload, repository — are
used here with the same meaning and are not redefined.

3.1.4 Scope names its exclusions #

A scope article's exclusion list MUST identify, for each excluded item, which document covers it. An exclusion that names nothing tells a reader the subject is out of scope without telling them where to go, which is the least useful thing a scope article can do.

A specification with more than one party MUST name its roles in its scope article, and MUST state every requirement against a role rather than against a program.

A role is a position in an interaction, not a piece of software. One program frequently occupies several — a repository operator is usually also a package producer, and a daemon that answers one protocol may consume another.

3.2.1 Why the distinction is load-bearing #

Naming a program in a requirement makes the requirement untestable against anything else, which defeats the purpose of writing the specification down. The whole reason a contract is published is that somebody other than the current implementation may satisfy it.

3.2.2 Enumerating roles #

A chapter's scope article SHOULD present its roles as a table giving, for each, the obligation it carries:

Two or three roles is typical. A specification finding itself with six has probably merged two interactions that want separate chapters.

3.2.3 Conformance follows the roles #

Because requirements attach to roles, a conformance article (§3.4) states what each role must do, separately. A reader implementing one side needs to know which requirements are theirs without reading the other side's.

The conventions below hold across every book in this anthology. A book MUST NOT restate them, and MUST state any point on which it differs.

3.3.1 Byte order #

All multi-byte integer fields are little-endian unless explicitly stated otherwise.

3.3.2 Sizes #

All sizes and offsets are in bytes. u8, u16, u32, and u64 denote unsigned integers of 8, 16, 32, and 64 bits.

3.3.3 Layout tables #

A field layout is given as a table in declaration order. A layout table is normative: fields appear on the wire in the order listed, with no padding between them.

3.3.4 Notation #

Hexadecimal values carry the 0x prefix. Byte sequences are written as space-separated hex pairs: 0a 0b 0c.

3.3.5 Strings #

Strings are UTF-8 (RFC 3629). String comparison is byte-for-byte equality unless stated otherwise.

3.3.6 Hashes and signatures #

Hash values are lowercase hexadecimal unless stated otherwise, and hash algorithms are named by their IANA-registered identifiers.

3.3.7 Timestamps #

Timestamps are RFC 3339, in UTC, and end with Z.

3.3.8 What a book's conventions article carries #

Given the above, a book's conventions article (§3.1) is short. It MUST carry the book's RFC 2119 declaration, and SHOULD carry only:

• notation the book introduces that is not listed here;
• any point on which the book departs from this article;
• pseudocode conventions, if the book uses pseudocode (§2.3).

3.4.1 Extension #

A chapter specifying a wire format, a file format, or a protocol SHOULD close with an extension article stating how the thing may grow.

An extension article SHOULD distinguish:

• Additive changes, which an implementation of the current version can ignore safely — a new optional field, a new entry in an open-ended set.
• Changes requiring a version bump, which it cannot — a new required field, a new value in a closed enumeration, any change to an algorithm the format has frozen.
• Reserved space, where the format deliberately leaves room, and what an implementation does when it encounters a value there.

A specification MUST state, for every enumeration it defines, whether that enumeration is closed. An implementation cannot decide whether to ignore or reject an unknown value without being told.

3.4.2 Conformance #

A chapter SHOULD close with a conformance article summarising, per role (§3.2), what that role must do. The article is a summary and MUST NOT introduce a requirement stated nowhere else.

A conformance article SHOULD also state plainly what conformance does not require. A reader who has just been given a list of obligations benefits more from knowing where their freedom lies than from a longer list.

A technical reference manual is an exhaustive descriptive reference for one component: what it does, how it behaves at every edge, and what happens when it fails.

The hardware analogy is deliberate. If the specification anthology is the architecture reference manual, a TRM is the per-implementation technical reference manual that sits beside it — the document that tells you what this thing actually does, given that the architecture told you what any conforming thing must do.

4.1.1 One book per component #

A TRM covers one component, where the boundary is drawn by what ships and is maintained together rather than by subject matter. Several subsystems that live in one codebase and version together are chapters of one manual, not manuals of their own.

4.1.2 Its authority comes from the software #

This is the property that governs everything else in this chapter. A specification is authoritative over its implementations: where the two disagree, the implementation has a defect. A TRM is the reverse. Where a manual and the software disagree, the software is right and the manual is stale.

A TRM therefore makes no stability commitment. Nothing in one is a promise about a future version, and a reader who needs a promise needs a specification instead.

4.1.3 What belongs in one #

Everything about the component that is true and not specified elsewhere: its architecture, its state, its configuration, its algorithms where they are its own, its failure modes, its on-disk artifacts, and the reasoning behind its design decisions.

A manual SHOULD carry rationale generously. It is the only document in the corpus with room for it, and a component's design decisions are otherwise recorded only in the history of the work that produced them.

4.1.4 What does not #

Anything a third party must reproduce in order to interoperate. That is a contract, and a contract belongs in a specification (§1.2). A manual cites it (§4.6) rather than restating it.

4.2.1 No normative keywords #

A TRM MUST NOT use RFC 2119 keywords. Not uppercase, and not in the lowercase constructions that read as obligation.

This is the one rule in this chapter with no exceptions, because it is what makes the class a class. A manual describes; it does not require. A reader must be able to tell, from the first paragraph of any document in this corpus, whether they are being told what something does or what they must do.

4.2.2 The indicative mood #

Write what the component does.

The third and fourth rows are the ones that catch people. "May" and "must" survive into descriptive prose easily, because an author describing something real slips into obligation without noticing — particularly when the source material was a specification.

4.2.3 Lowercase keywords are the actual hazard #

Uppercase keywords are trivially caught by searching. Lowercase ones are not, and they are far more common: a conversion from specification prose typically leaves a dozen or more.

An author SHOULD search a finished manual for lowercase must, should, shall, may not, and must not, and rewrite every instance that reads as a requirement. Idiomatic uses survive — "what the content should be", "two files that cannot both be present" — and the test is whether a reader could mistake the sentence for an obligation.

4.2.4 Register #

Plain declarative prose, addressed to a competent engineer. Not tutorial and not chatty. A manual SHOULD assume its reader knows the platform and wants the specifics.

A TRM's chapter structure follows the component rather than a template. The conventions below are what has worked, offered as guidance.

4.3.1 The introduction #

A manual SHOULD open with an introduction containing:

The overview article is the most valuable page in the book and the one most often written last and least. It SHOULD say what is surprising about the component — the two or three decisions that would not be guessed from the name — rather than restating the component's purpose in a paragraph.

4.3.2 Body chapters #

Ordered so that a reader following the component's own flow reads them in order: what it is made of, what it does, in the sequence it does it.

4.3.3 A failure-modes chapter #

A manual SHOULD close with a chapter describing what goes wrong: the common failures, what each looks like from outside, what signal is available, and how to get back to a known state.

This is the chapter readers arrive at from a search engine at two in the morning, and it is the one most often omitted. A manual that documents every success path and no failure path has documented the easy half.

4.3.4 Appendices #

Consolidated reference material: constants, paths, on-disk state, configuration keys, event types. See §6.1.

4.3.5 Length is not a virtue, but exhaustiveness is #

A manual SHOULD document the edge cases. The odd interaction, the counter-intuitive default, the thing that happens only when two features meet — those are why the manual exists. A summary of the happy path is already in the component's README.

A TRM describes what the component does now. This has a consequence that authors reliably find uncomfortable, and it is worth stating directly.

4.4.1 Divergences are not narrated #

A TRM MUST NOT frame anything as a difference between itself and a specification. No "the specification requires X but the implementation does Y", anywhere, in any form.

Where an implementation does not satisfy a contract, that is a defect. It is recorded as one, in the project tracker, against the work that would fix it — and the manual simply describes what the software does.

4.4.2 Which does not mean writing around it #

Describing the true state is not the same as being vague about it. A manual SHOULD state plainly what a component does not do, where a reader would otherwise assume it did:

peipkg does not check free space before it starts. Exhaustion is discovered when a write fails.

That sentence is descriptive, useful, and carries no comparison to any contract. The distinction is between what is absent — which a reader needs — and what was promised — which belongs in the tracker.

4.4.3 Interim states #

Where behaviour is deliberately provisional, a manual MAY say so and describe the intended end state, provided it describes the current one first and at greater length. A manual SHOULD NOT let a description of an intention displace the description of what actually runs.

A technical reference manual proposal is a TRM for a component that does not exist yet.

It is written exactly as a TRM is written — indicative mood, no normative keywords, exhaustive — and it describes software that has not been built.

4.5.1 Why the class exists #

A design that has been written out at reference-manual depth is a design whose gaps are visible. Every field, limit, and interaction has to be decided in order to be described, and describing it is how the contradictions surface.

4.5.2 Saying what it is #

A proposal MUST identify itself as one. It SHOULD do so in two places: in its description, and in an opening article stating plainly that a manual's authority comes from the software (§4.1) and that this one has none of that yet — so a surprising statement in it is a design decision that has not survived contact with an implementation.

The document class carries that warning by itself, which is why no banner on every page is needed.

4.5.3 It graduates in place #

A proposal sits alongside the finished manuals and MUST NOT be moved when the software lands. Moving it breaks every inbound link. Graduating consists of correcting it against the implementation and dropping the word "proposal".

4.5.4 Reviewing one #

A proposal cannot be verified against code, so review is internal composition instead: for each field, rule, limit, and configured value, find every other place the document constrains it, and compose them by hand.

The failure to look for is two rules that are individually right and jointly wrong — a default stated in one chapter and a validity constraint stated in another, which together reject the default. The related one is two rules with no stated order, where both can fire on one input and the document never says which runs first.

Composing every pair of independently configured size limits on one data path, at their default values, is worth doing every time. Two documents in a row have carried a ceiling on one side larger than the ceiling on the other, letting one party accept what the other cannot carry.

A proposal MAY still contribute a specification chapter, where the component owes one. Publishing a contract with no implementation to keep it honest is a real cost, and it is a decision to take deliberately rather than by default.

Where a component implements a published contract, its manual cites the contract rather than restating it.

4.6.1 Cite, do not paraphrase #

A manual SHOULD state that the contract exists, name where it is, and describe what this implementation does about it:

A dependency is satisfied by a candidate when the conditions of PSPU §5.21 hold. Three consequences of those rules shape how peipkg behaves.

A manual MUST NOT restate the contract's normative content in descriptive prose. A paraphrase is a second copy that drifts, and because the paraphrase carries no normative keywords, a reader cannot tell which of the two they are supposed to rely on.

4.6.2 What the manual adds #

The nuances of one implementation: the order it does things in, the limits it applies, what it does where the contract leaves a choice, and what it does not implement.

A manual is the right place to say that a component is more restrictive than the contract requires, or that it makes a choice the contract leaves open. Those are facts about the software, not comparisons against it.

4.6.3 Where the split falls #

The recurring question is whether a given fact belongs in the manual or in the specification, and the test in §1.2 answers it: if a second independently written party must reproduce it, it is contract.

Worked, from one component: what satisfies a dependency is contract; which of several satisfying candidates gets chosen is implementation. The schema of a declaration is contract; the command-line flag that overrides it is implementation. The layout of an artifact is contract; where the tool keeps its own database is implementation.

§4.6 covers the ordinary direction: a manual cites the contract it implements. The reverse direction needs a rule of its own, because a specification that defers to a manual has given something up, and a reader is entitled to know that it did.

4.7.1 When it is allowed #

A specification MAY cite a manual for material it deliberately does not specify. It MUST NOT cite one for material within its own scope.

The test of §1.2 decides which case applies. If a second, independently written party must reproduce the behaviour, it is contract — and a citation to a manual there is a specification failing at its job, since the other party has no manual for their own implementation. If no second party is expected to reproduce it, because the component is Peios' alone and is described rather than standardised, then the manual is the only document that holds the material, and naming it beats implying a standard exists somewhere.

4.7.2 Say that it is a deferral #

A specification citing a manual MUST make the deferral legible rather than let it read as an ordinary cross-reference. "Described in the Peios Kernel TRM §3.8" says what it is; "see §3.8" does not.

Where a scope article excludes a whole area to a manual, it SHOULD say why once, in that article, rather than re-arguing it at each citation site. The sites then only need to name the article.

4.7.3 The standing case #

KACS is the one that recurs. Peios' access-control implementation is described in the Peios Kernel TRM §3 and is not separately specified, so PCDS — which specifies the structures KACS consumes — defers to that manual wherever a structure's meaning depends on what KACS does with it. PCDS §1.1 records the arrangement; the individual citations name the articles.

Any part of any book in this corpus is addressable with the § symbol followed by a number derived from the book's structure.

The examples are qualified because a bare § reference means "this book" (§5.2). Within this document, §2.1 is the RFC 2119 article and §A is the normative-reference list.

5.1.1 Where the numbers come from #

Chapter and article numbers derive from the ordering of directories and files, and are supplied by the renderer. An author does not write them into the text.

A chapter appendix — a file whose name marks it as an appendix, within a chapter directory — is lettered rather than numbered, and cited in the form §N.A. A book-level appendix, at the book root, is rendered as "Appendix A" and is cited by its letter alone, with no chapter component at all.

The two are easy to confuse and produce silently wrong references. An author adding a second appendix to a chapter SHOULD check the rendered index before relying on the citation.

5.1.2 Stability #

Section numbers are positional. Inserting a chapter shifts every following chapter; inserting an article shifts the rest of its chapter.

A book that other documents cite SHOULD therefore append rather than insert, where the choice exists. Where a restructure is unavoidable, every inbound reference has to be revalidated (§5.4).

5.2.1 Within a book #

A reference to another part of the same book omits the book name:

The claim-path set is the union defined in §5.23.

5.2.2 Between books #

A reference to another book leads with that book's short name:

A dependency is satisfied when the conditions of PSPU §5.21 hold.

The short name is the one declared in the book's own metadata — PCDS, PGSS, PSPK, PSPU. A reference to a manual names the component: the peipkg TRM §7.4.

5.2.3 Referring to a whole book #

All identifiers in this chapter conform to PCDS.

5.2.4 Prose and the reference are different things #

A citation MAY be accompanied by prose naming what is at the other end:

Sender authentication is performed by peer credential (§4.18).

The descriptor store article (§4.20) defines the retention rules.

The § reference is the durable part. The prose is a readability aid, and it MAY drift across revisions without invalidating the reference — which is also why prose alone is not a citation.

5.2.5 In code and in commit messages #

A code comment or a test referring to a documented rule SHOULD carry the full citation, so that a search finds every site depending on it:

/* Per PCDS §5.6: inherited ACEs precede explicit ones. */

The finest addressable unit in this corpus is the article — the §N.M form of §5.1.

There is no addressing below it. Headings within an article are not numbered, and there is no scheme for citing an individual normative statement.

5.3.1 Why not #

An earlier corpus defined one: clauses numbered implicitly by counting normative statements within the deepest enclosing heading, cited as §3.2.1(4), with a validation rule for checking that a clause number still resolved.

It was specified in detail and never adopted. Across thirteen documents it was used eighteen times, and never once in the current corpus. What it cost was real: every editorial change to an article renumbered the clauses after it, so every citation into that article had to be checked against a count that nothing computed.

Article-level citation has proved sufficient in practice. An article is small enough to be a useful target and stable enough to be worth citing.

5.3.2 Writing for citability #

Because the article is the unit, an author SHOULD size articles so that one is a sensible thing to point at. An article covering one rule is easy to cite; an article covering nine unrelated rules forces every citation to be approximate.

Where a single statement genuinely needs to be picked out, a citation MAY name it in prose alongside the article reference:

the duplicate-key rule of §5.9

5.3.3 Reading an old citation #

A (N) clause suffix in older material, or in a code comment predating this corpus, refers to the retired scheme. It SHOULD be resolved to an article reference when the surrounding text is next touched.

5.4.1 Every reference resolves #

A published book MUST NOT contain a reference that does not resolve. A reference to a chapter, article, or appendix that does not exist is an error, not a cosmetic defect: it is indistinguishable, to a reader, from a reference to something that was deleted.

5.4.2 Checking #

Because section numbers are positional (§5.1), any structural change invalidates references — including references from other books, which the author making the change is least likely to be looking at.

After a structural change, an author SHOULD:

1. Build the affected books and extract the actual chapter and article numbering from the rendered index.
2. Collect every § reference in the corpus.
3. Check each against that numbering.

Steps 1 to 3 are mechanical and worth automating. What is not mechanical is whether a reference that still resolves still means what the citing text implies. A reference to "the ordering rules of PSPU §5.6" resolves happily after that article is rewritten to cover something else.

5.4.3 Two traps #

Line-wrapped references. A citation split across a line break — the book's short name at the end of one line and the § number at the start of the next — is easy for a checker to miss and easy for an author to introduce.

Appendix forms. A chapter appendix and a book appendix take different forms (§5.1), and a reference using the wrong one resolves to nothing — or worse, to something.

An appendix consolidates reference material that is defined in the body: constants, limits, enumerated values, paths, configuration keys, event types, wire vocabularies.

6.1.1 Appendices and the body do not duplicate #

Where a constant, table, or layout is defined in an appendix, the body MUST reference it rather than restate it — and where it is defined in the body, the appendix MUST reference that.

Exactly one of the two is the definition. The other points at it.

An appendix entry SHOULD carry a citation to the article that defines what it lists, so that a reader who needs the semantics can get there in one step.

6.1.2 What earns an appendix #

Material a reader looks up rather than reads: something they arrive at knowing what they want.

A limits appendix is the clearest case. Every size bound, count cap, and default in one table is genuinely more useful than the same figures scattered across twenty articles, and the body articles then cite it rather than repeating the number.

6.1.3 Generated appendices #

An appendix listing values that exist in source — an ABI table, a constants list, an error enumeration — SHOULD be generated from that source rather than transcribed, with a check mode that fails when the committed file is stale.

6.2.1 One canonical home #

Every exhaustive table or enumeration lives in exactly one place. Everywhere else that needs it gets a clearly framed subset and a reference to the canonical one.

This applies across the whole corpus, not within a single book: a table in a specification is not re-tabulated in a manual, and a manual's configuration reference is not duplicated into task documentation.

6.2.2 Subsets are labelled as subsets #

A partial table MUST be framed as partial. A reader who cannot tell a subset from the full set will treat the subset as exhaustive, which is how a table that was correct becomes a document that is wrong.

6.2.3 Disagreeing copies are never averaged #

Where two copies of a table disagree, the resolution is to check the source — the implementation, or the specification that defines it — and then to delete one of the copies. Splitting the difference produces a third value that matches nothing.

6.2.4 Layout tables #

A table describing a binary layout is normative in a specification (§3.3) and descriptive in a manual, and in both cases gives fields in declaration order.

6.2.5 Formatting #

A table row MUST NOT contain an unescaped |. A pipe inside a cell — common when documenting bitwise expressions — silently eats a column, and the resulting table renders as though it always had one fewer.

A table SHOULD have a header row with a meaningful label per column. Field | Type | Description beats three unlabelled columns.

Very wide tables SHOULD be broken up or transposed. A table that needs horizontal scrolling is a table nobody reads the right-hand end of.

A note carries what the surrounding text cannot: why the rule is the way it is, what it defends against, what was tried instead.

> [!NOTE]
> Text.

In a specification a note is informative and is bound by §2.2. In a manual, where nothing is normative, a note is a change of register rather than of authority.

6.3.1 What a good note does #

• Names the failure the rule prevents. Concretely, with the mechanism. "Without this, an attacker who controls a cache edge replays an older signed index and the consumer never notices" is worth ten lines of abstract rationale.
• Records the alternative that was rejected, and why. The next person to look at the design will otherwise propose it again.
• Flags the counter-intuitive. Where a reader's first instinct is wrong, a note is where to say so.

6.3.2 What a note is not #

• A restatement of the rule above it in different words.
• A place to hide a requirement (§2.2).
• An apology for a design.

6.3.3 Density #

Roughly one note per two or three articles is what has worked. A book with a note under every heading has diluted the marker to the point where readers skip them, which wastes the ones that matter.

Mechanical conventions. None of these affects meaning; all of them affect whether a diff is readable.

6.4.1 Line length #

Prose SHOULD wrap at 78 columns. Tables, code blocks, and link-heavy lines are exempt — breaking those hurts more than it helps.

The reason is diffs. A paragraph on one long line produces a whole-paragraph diff for a one-word change, which makes review of a large document impractical.

6.4.2 Frontmatter #

Every article carries YAML frontmatter with a title and a description:

---
title: Freshness and Rollback Protection
description: An index that verifies is not necessarily current — monotonic
  versions, staleness limits, and the defences against rollback and freeze.
---

Titles are in title case, and name the subject rather than describing it. "Freshness and Rollback Protection", not "How freshness works".

The description is one sentence saying what the article covers. It is what a reader sees in a search result, so it does the work the title deliberately does not: where the title names the subject, the description says what is in there. It SHOULD name the specific things — "monotonic versions, staleness limits" beats "the freshness rules" — because a corpus this size has many articles called Overview, Structure and Conventions, and the description is what tells them apart.

Do not restate the title. title: Persistence with description: How persistence works has spent a line and told the reader nothing.

Books were written without descriptions for a time, and the omission was invisible until search made it obvious. The site build takes --strict, which fails on any article missing one; run it that way.

6.4.3 Headings #

Articles use ## for their top-level headings. An article does not repeat its own title as a heading — the renderer supplies it.

Heading text is short and specific. Because headings are not addressable (§5.3), they are navigation rather than citation targets, and they SHOULD read as scannable labels.

6.4.4 Code and identifiers #

Identifiers, paths, field names, and literal values are in backticks. Fenced blocks carry a language tag where one applies.

Code spans are not translated: a field named size_installed is written that way in prose, not as "size installed".

6.4.5 Text hygiene #

Straight quotes and apostrophes rather than typographic ones; a regular hyphen rather than a non-breaking one; a normal space rather than a non-breaking space; and no zero-width characters. Each of those renders identically and greps differently, which is the worst combination.

An em dash is written as —, spaced as the surrounding prose requires.

6.4.6 Spelling #

British English, except in identifiers, code, and the names of external standards, which are reproduced exactly as their source spells them.

Much of what this corpus documents already has names — given by an external standard, by a published header, or by both, spelled differently. A reader arrives holding one of those names and expects to find it.

6.5.1 Each document uses its own reader's vocabulary #

A specification is written for an implementer who has the external standard and does not have this implementation's source. It uses the external standard's spelling, exactly as that standard spells it.

A technical reference manual is written for someone reading alongside the implementation. It uses the implementation's spelling, exactly as the header declares it.

Neither adopts the other's vocabulary. A specification that named private headers would be documenting something its reader cannot see, and a manual that named only the standard would not match the code in front of the reader.

6.5.2 Divergences are recorded once per book #

Where the two vocabularies disagree, the disagreement is stated once — in a table, in an appendix — and not repeated at every use. Inline double-naming makes prose unreadable to both audiences at once.

The table gives both spellings and nothing else. It is a lookup, not an explanation.

6.5.3 Where a standard names a structure and its constant separately #

Many standards give one name to a structure and another to the constant that selects it: a record type and the numeric tag identifying that record. A reader may arrive with either — one from a declaration, the other from a hex dump — so a table that gives a value MUST name the constant that carries it, not only the structure it selects.

Naming the structure in a column headed with the constant's value is the common form of this mistake. It reads correctly and is unfindable by half the people who need it.

6.5.4 The test #

For any name a reader could plausibly arrive with, searching the corpus for that exact string finds something. A name that appears only as prose — "the offset to the owner SID", where the standard calls the field OffsetOwner — fails this test even though the surrounding text is correct.

Correct and unfindable is the failure this rule exists to prevent. Reference material is read by search.

The external standards this corpus depends on. A book MUST NOT restate this list; it cites into it.

A.1 Deferral #

Where a document defers to an external standard, that standard's requirements apply as though written out. A document citing one MUST name the specific part it relies on where the whole would be ambiguous.

A.2 Citation format #

A.3 IETF #

A.4 Microsoft Open Specifications #

The Windows security model is the design source for several Peios subsystems, and its documents are cited for parity mappings.

A.5 Unicode #

A.6 POSIX and other standards #

A.7 External conventions #

Some documents describe interoperation with conventions that have no formal specification — the sd_notify readiness protocol and the freedesktop os-release file among them. Where a document relies on one, it MUST describe the behaviour it depends on rather than citing the convention alone, because there is no normative text at the other end of the citation.