# Conventions for Specifications and TRMs > How the documents of this anthology are written and read — normative language, required structure, citation and addressing, and the style rules for specifications and for technical reference manuals. --- # 1.1 Scope _Peios / Advanced Peios / Conventions / Introduction_ > What this book governs — the two classes of technical document Peios writes — and where it sits in the PCSA anthology. 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. --- # 1.2 The Two Document Classes _Peios / Advanced Peios / Conventions / Introduction_ > Specification or manual, decided by one test — how many independently written parties have to agree. Most subsystems split across both. 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 How to Read This Book _Peios / Advanced Peios / Conventions / Introduction_ > The normative keywords used here, why the specification and manual halves carry different weight, and the order to read the chapters in. ## 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. --- # 2.1 RFC 2119 Keywords _Peios / Advanced Peios / Conventions / Normative Language_ > Uppercase MUST, SHOULD and MAY carry their RFC 2119 meanings; lowercase does not. Requirements are stated against a role, and SHOULD is a real choice. 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: | Keyword | Meaning | |---|---| | MUST, MUST NOT | An absolute requirement or prohibition | | SHALL, SHALL NOT | Synonyms for MUST and MUST NOT | | SHOULD, SHOULD NOT | A requirement that may be set aside for a stated reason, the consequences of which are understood | | MAY | Genuinely optional | | REQUIRED, OPTIONAL | Synonyms for MUST and MAY, used adjectivally | 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. > [!NOTE] > A SHOULD whose exception nobody can name is a MUST that the author > was not confident enough to write. A SHOULD that nothing would ever > satisfy is a MAY. Both are worth catching before publication, because > an implementer reading either has to guess at an intent that was never > formed. --- # 2.2 Informative Text _Peios / Advanced Peios / Conventions / Normative Language_ > Everything in a specification is normative unless marked otherwise — how to mark informative text, what it may not do, and what it is for. ## 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: ```markdown > [!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. > [!NOTE] > The restriction exists because a requirement stated twice is a > requirement that can drift. When a note paraphrases a rule and the > rule later changes, the note becomes a second, contradictory > specification that a reader has no way to rank against the first. ## 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. --- # 2.3 Pseudocode _Peios / Advanced Peios / Conventions / Normative Language_ > Pseudocode in a specification is normative, and the corpus-wide conventions it should be written in. 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. | Symbol | Meaning | |---|---| | `&` (parameter prefix) | In-out parameter — the caller's value is read and may be modified | | `\|` | Bitwise OR | | `&` (in an expression) | Bitwise AND | | `~` | Bitwise NOT | | `\|=`, `&=` | Augmented assignment | | `=` | Assignment | | `==` | Equality comparison | | `->` | Field access through a pointer or reference | | `→` | Return type in a signature | | `//` | Single-line comment | 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). > [!NOTE] > This matters most for algorithms with an ordering that the prose does > not make explicit. Two rules that can both fire on one input need a > stated order, and pseudocode is often where that order actually lives. --- # 3.1 Required Articles _Peios / Advanced Peios / Conventions / Specification Structure_ > The fixed opening and closing shape of a specification book and of each of its chapters, so a reader finds the same things in the same places. 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: | Article | Purpose | |---|---| | Scope | What the book covers, and what it does not — with each exclusion naming where the excluded thing *is* covered | | Conventions | The book's RFC 2119 declaration and any notation specific to it (§3.3) | ## 3.1.2 Chapter level A chapter specifying a protocol or a format MUST open with: | Article | Purpose | |---|---| | Scope and Roles | What the chapter specifies, and the roles that speak it (§3.2) | | Terminology | Terms specific to the chapter | 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: ```markdown Terms defined in §5.2 — package, manifest, payload, repository — are used here with the same meaning and are not redefined. ``` > [!NOTE] > A redefinition is a second definition, and two definitions of one term > drift. Delegation costs the reader one click and costs the corpus > nothing. ## 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. --- # 3.2 Roles _Peios / Advanced Peios / Conventions / Specification Structure_ > A multi-party specification names its roles and states every requirement against a role rather than a program — and conformance follows the roles. 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: | Role | Obligation | |---|---| | Producer | Builds the artifact. Everything the artifact contains is a producer obligation. | | Consumer | Validates and applies it. Every validation and rejection rule binds the consumer. | 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. --- # 3.3 Data Conventions _Peios / Advanced Peios / Conventions / Specification Structure_ > The conventions every book in this anthology inherits — byte order, sizes, layout tables, notation, strings, hashes and timestamps. 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). > [!NOTE] > Before this article existed, four books each carried a near-identical > conventions chapter. Three of them listed the same seven headings. > Duplicated text of that kind does not stay identical: it is where > contradictions breed, and the contradiction is invisible because > nobody reads two copies of the same thing side by side. --- # 3.4 Extension and Conformance _Peios / Advanced Peios / Conventions / Specification Structure_ > How a format or protocol chapter states the way it may grow, and how a book states what conformance to it requires. ## 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. > [!NOTE] > The test for whether a change is additive is not whether it is small. > It is whether an implementation that ignores it still behaves > correctly. An optional field whose absence changes what gets > installed is not additive, however optional it looks. ## 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. > [!NOTE] > The useful shape is: here is what you must reach the same answer on > as everybody else, and here is everything you are free to do > differently. A specification that never says the second half reads as > though it constrains the whole implementation, and implementers > respond by over-constraining themselves or by ignoring it. --- # 4.1 What a TRM Is _Peios / Advanced Peios / Conventions / Technical Reference Manuals_ > An exhaustive descriptive reference for one component — one book each, authority drawn from the software, and what belongs in one. 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 Voice _Peios / Advanced Peios / Conventions / Technical Reference Manuals_ > A manual describes and never requires — no normative keywords, the indicative mood, and the lowercase constructions that are the real hazard. ## 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. | Not this | This | |---|---| | The daemon MUST reject a malformed request | The daemon rejects a malformed request | | A client SHOULD retry after a timeout | A client that times out can retry | | The cache MAY be discarded | The cache can be discarded at any time | | Callers must hold the lock | Callers hold the lock | 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. > [!NOTE] > A validator that flags documents *lacking* normative keywords is > useless here, and worse than useless if it is trusted: for a manual > the signal is inverted. The check has to be run deliberately and in > the opposite direction. ## 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. --- # 4.3 Structure _Peios / Advanced Peios / Conventions / Technical Reference Manuals_ > How a manual is shaped — the introduction, body chapters, a failure-modes chapter and appendices — as guidance rather than a template. 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: | Article | Purpose | |---|---| | Overview | What the component is, and what is unusual about it | | What This Manual Covers | And what is covered elsewhere, naming where | | Terminology | Terms specific to the component, delegating the rest | | Compatibility | Versions, architectures, and what interoperates | 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. --- # 4.4 Describing the True State _Peios / Advanced Peios / Conventions / Technical Reference Manuals_ > A manual describes what the component does now, without narrating its divergences from a specification and without writing around them. 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. > [!NOTE] > The reason is that a manual written as a divergence log rots into a > second changelog nobody maintains, and undermines itself while doing > it: a reader who is told the document is describing something wrong > stops trusting the parts that are describing something right. > > It is also the wrong audience. The person who needs to know about a > divergence is whoever will fix it, and they are looking at the > tracker, not at a reference manual. ## 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. --- # 4.5 Proposals _Peios / Advanced Peios / Conventions / Technical Reference Manuals_ > A TRM for software that does not exist yet — why the class exists, how it says so, and how it graduates in place once the software does. 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. --- # 4.6 Citing a Specification _Peios / Advanced Peios / Conventions / Technical Reference Manuals_ > A manual cites the contract it implements rather than paraphrasing it, and adds what only an implementation can — order, limits, and choices. 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. > [!NOTE] > The most reliable way to settle a borderline case is to read the > target specification's own scope article. It states what that book > excludes, and it has overturned a placement more often than any > argument from first principles. --- # 4.7 Citing a Manual _Peios / Advanced Peios / Conventions / Technical Reference Manuals_ > The reverse direction — when a specification may defer to a manual, how the deferral must read, and KACS as the standing case. §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. > [!NOTE] > This is not licence to let a specification thin out over time. Each > deferral is a decision that a given area will not be standardised, > and the scope article is where that decision is visible. A citation > to a manual appearing anywhere else, without a scope article behind > it, is a defect. --- # 5.1 Section Addressing _Peios / Advanced Peios / Conventions / Citation and Addressing_ > Where a § number comes from — the book's own structure — and how stable it is across revisions. Any part of any book in this corpus is addressable with the `§` symbol followed by a number derived from the book's structure. | Form | Means | Example | |---|---|---| | `§N` | Chapter N | PSPU `§5` | | `§N.M` | Article M of chapter N | PSPU `§5.23` | | `§N.A` | Appendix A of chapter N | PSPU `§5.A` | | `§A` | Appendix A of the book | the peipkg TRM `§A` | 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 Citing Between Books _Peios / Advanced Peios / Conventions / Citation and Addressing_ > Citing within a book, between books, and into code — and why the § reference, not the prose beside it, is the durable part. ## 5.2.1 Within a book A reference to another part of the same book omits the book name: ```markdown 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: ```markdown 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 ```markdown 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: ```markdown 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: ```c /* Per PCDS §5.6: inherited ACEs precede explicit ones. */ ``` > [!NOTE] > This is the mechanism that makes a specification change tractable. > When a rule moves, the citations are what tell you which code was > relying on it. Prose references — "as the security descriptor spec > says" — do not survive a grep. --- # 5.3 Granularity _Peios / Advanced Peios / Conventions / Citation and Addressing_ > The article is the finest addressable unit, why the clause-level scheme was retired, and how to write an article worth citing. 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: ```markdown 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 Validation _Peios / Advanced Peios / Conventions / Citation and Addressing_ > A published book must contain no reference that fails to resolve — how to check, and the two traps that survive a careless check. ## 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. > [!NOTE] > The failure this catches is specific and common: an article count > changes by one, every reference past that point is off by one, and > every one of them still resolves — to the wrong article. Nothing > reports an error, and the document is wrong in a way that reads as > correct. ## 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. --- # 6.1 Appendices _Peios / Advanced Peios / Conventions / Shared Style_ > What earns an appendix, why an appendix and the body must not duplicate each other, and how generated appendices are handled. 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. > [!NOTE] > A value written down twice is a value that will eventually be written > down differently. The appendix is where this bites hardest, because > an appendix is exactly the kind of page that gets updated in isolation > by someone who has not read the body — or skipped entirely by someone > who has. 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. > [!NOTE] > The argument is empirical. In one case, a hand-written ABI appendix > had every numeric value correct and a systematic error in the *names*. > Transcription reproduces a wrong name faithfully and produces offsets > nobody can cheaply re-check; generation cannot. --- # 6.2 Tables and Enumerations _Peios / Advanced Peios / Conventions / Shared Style_ > Every exhaustive table has exactly one home, subsets are labelled as subsets, and disagreeing copies are resolved rather than averaged. ## 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. --- # 6.3 Notes _Peios / Advanced Peios / Conventions / Shared Style_ > What a note carries that the surrounding text cannot — the reasoning behind a rule — and what a note must not be used for. A note carries what the surrounding text cannot: why the rule is the way it is, what it defends against, what was tried instead. ```markdown > [!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. --- # 6.4 Formatting _Peios / Advanced Peios / Conventions / Shared Style_ > The mechanical conventions — line length, frontmatter, headings, code identifiers, text hygiene and spelling. 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`: ```yaml --- 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. --- # 6.5 Naming External Constants _Peios / Advanced Peios / Conventions / Shared Style_ > Each document uses its own reader's vocabulary, divergences are tabulated once per book, and structures are distinguished from the constants that select 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. --- # Appendix A Normative References _Peios / Advanced Peios / Conventions_ > The external standards this corpus depends on, and the citation format for referring to them. 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 | Form | Means | |---|---| | `RFC 2119` | The whole document | | `RFC 8259 §7` | A specific section | | `Unicode 16.0` | A version of a standard | | `MS-DTYP §2.4.2` | A section of a Microsoft Open Specification | ## A.3 IETF | Reference | Title | Used for | |---|---|---| | RFC 2119 | Key words for use in RFCs | Normative keywords (§2.1) | | RFC 3339 | Date and Time on the Internet | Timestamps (§3.3) | | RFC 3629 | UTF-8 | String encoding (§3.3) | | RFC 3986 | Uniform Resource Identifier | URL syntax | | RFC 4648 | Base16, Base32, Base64 Encodings | Base64, §4 alphabet | | RFC 7468 | Textual Encodings of PKIX Structures | PEM key files | | RFC 8032 | EdDSA | Ed25519 signing and verification | | RFC 8259 | JSON | JSON documents | | RFC 8478 | Zstandard | Compression | | RFC 8915 | Network Time Security | Authenticated time | ## 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. | Identifier | Title | |---|---| | MS-DTYP | Windows Data Types | | MS-ERREF | Windows Error Codes | | MS-LSAD | Local Security Authority (Domain Policy) Remote Protocol | | MS-SAMR | Security Account Manager Remote Protocol | | MS-ADTS | Active Directory Technical Specification | | MS-GPOL | Group Policy: Core Protocol | | MS-GPREG | Group Policy: Registry Extension Encoding | ## A.5 Unicode | Reference | Used for | |---|---| | Unicode 16.0 | Normalization forms, case folding | | `CaseFolding.txt`, status `S` and `C` entries | Case-insensitive comparison | ## A.6 POSIX and other standards | Reference | Used for | |---|---| | IEEE Std 1003.1-2017, Chapter 14 | The pax interchange format | | MessagePack specification | Event payload encoding | | SPDX License List | License identifiers | ## 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.