Peios Specification Documents

Every Peios specification MUST be assigned a PSD number. The PSD number is the primary citation handle for the specification and is permanent for the life of the specification.

§2.1.1 Assignment

PSD numbers MUST be assigned per specification, not per version. A specification that has versions v0.20, v0.22, and v0.56.1 has one PSD number, not three.

PSD numbers MUST be sequential positive integers assigned in order of specification creation. The first specification is PSD-001, the second is PSD-002, and so on.

PSD numbers MUST be assigned when the specification is created. A specification is citable by PSD number while still in draft status.

PSD numbers MUST NOT be reused. A withdrawn specification retains its PSD number.

§2.1.2 Format

In prose, PSD numbers MUST be written as PSD- followed by the number zero-padded to three digits: PSD-001, PSD-012, PSD-103.

§2.1.3 Directory naming

The PSD number MUST be encoded in the specification's directory name using the format psd-NNN--name, where:

• NNN is the PSD number zero-padded to three digits
• -- is a literal double hyphen separator
• name is a short kebab-case identifier for the specification

The -- separator MUST be used to separate the PSD number from the name. This makes the two components machine-parseable (split on --) and visually distinct from hyphenated names.

The short name MUST be lowercase. It MUST use only ASCII lowercase letters, digits, and hyphens. It SHOULD be short (one to two words). It MUST NOT start or end with a hyphen. Multi-word names MUST use hyphens as separators (kebab-case).

Examples:

specs/psd-001--psd/
specs/psd-002--binary-identifiers/
specs/psd-003--kmes/
specs/psd-004--kacs/
specs/psd-005--eventd/
specs/psd-006--lcs/
specs/psd-007--loregd/
specs/psd-008--peinit/

§2.2.1 Specification root

All specifications MUST reside under the specs/ directory. Each specification MUST have its own directory named according to the psd-NNN--name convention defined in §2.1.

§2.2.2 Version directories

Within a specification directory, each version MUST have its own directory named vMAJOR.MINOR or vMAJOR.MINOR.PATCH matching the Peios software version (see §3.1).

Examples:

specs/psd-004--kacs/
  trail.toml
  v0.20/
    trail.toml
    1-introduction/
    2-sids/
    3-security-descriptors/
    ...
  v0.22/
    trail.toml
    1-introduction/
    2-sids/
    3-security-descriptors/
    ...

Each version directory is a complete, self-contained edition of the specification. Version directories MUST NOT contain references to files in other version directories.

§2.2.3 Chapter directories

Within a version directory, chapters MUST be organised as numbered directories using the format N-name where:

• N is a positive integer (no zero-padding required)
• name is a kebab-case slug describing the chapter

Chapters MUST be numbered sequentially starting at 1. Gaps in numbering SHOULD NOT exist in finalized versions but MAY exist in drafts to reserve space for future chapters.

Appendix chapters MUST be numbered contiguously after the last substantive chapter.

§2.2.4 Section files

Within a chapter directory, sections MUST be markdown files using the format N-name.md where:

• N is a positive integer
• name is a kebab-case slug describing the section

Section files MUST be numbered sequentially starting at 1 within their chapter.

§2.2.5 Subsections

Subsections within a section file MUST use markdown headings. The heading hierarchy maps to the addressing scheme:

• ## headings are subsections
• ### headings are sub-subsections
• Deeper nesting follows the same pattern

There is no enforced depth limit.

§3.1.1 SemVer synchronisation

PSD versions MUST use Semantic Versioning (MAJOR.MINOR.PATCH), synchronised with the Peios software version. When a specification is updated, it MUST take the version number of the software release that the change ships with.

The patch component MUST be omitted when it is zero. v0.22 is correct; v0.22.0 is not.

§3.1.2 Complete editions

Each version of a specification MUST be a complete, self-contained edition. Versions are not diffs or patches on previous versions. A reader MUST be able to understand the specification from a single version directory without consulting other versions.

§3.1.3 Revision count

Each specification has a revision count equal to the number of version directories under its specification directory. The revision count MUST NOT be stored explicitly -- it is derived from the filesystem.

Each version of a PSD MUST have a lifecycle status recorded in its version-level trail.toml.

§3.2.1 States

§3.2.2 Transitions

Lifecycle transitions are one-directional:

• draft → final: The version has been reviewed and is ready for implementation.
• draft → withdrawn: The draft was abandoned before finalisation.
• final → withdrawn: The finalised version was found to contain errors serious enough to retract it. A replacement version SHOULD be published.

A final version MUST NOT return to draft. If a finalised specification needs semantic changes, a new version MUST be published.

§3.2.3 Errata

Typographical errors in a final version MAY be corrected in place without publishing a new version, provided the correction does not change the semantic meaning of any normative statement. If a typo could be read as a different normative requirement, it MUST be treated as a semantic change and corrected via a new version.

A withdrawn version MUST NOT transition to any other state. Its PSD number and version directory are retained for historical reference.

§3.2.4 Version succession

Within a specification, a newer final version implicitly supersedes all older versions. The version resolution rule (§3.3) determines which version applies in any given context. No explicit supersedes metadata is required.

Multiple versions of a specification MAY be final simultaneously. This is expected -- a v0.20 and a v0.22 may both be final, with the version resolution rule selecting the appropriate one for each referencing context.

§3.2.5 Metadata

The version-level trail.toml MUST contain:

status = "final"
date = "2026-04-20"

• status: One of draft, final, or withdrawn.
• date: The date of the most recent change to this version, in YYYY-MM-DD format.

When a specification references another PSD by number without an explicit version, the applicable version MUST be resolved as follows:

The resolved version is the highest version of the referenced PSD whose version number is less than or equal to the version of the referencing document, using SemVer ordering.

Only final versions participate in version resolution. A draft version MUST NOT be selected by the resolution rule. A withdrawn version MUST NOT be selected by the resolution rule.

If no final version of the referenced PSD exists at or below the referencing version, the reference is unresolvable. This SHOULD be treated as an error during cross-reference validation.

§3.3.1 Explicit version pinning

A reference MAY include an explicit version to override the resolution rule:

PSD-004 v0.22 §3.2(1)

Explicit version pinning SHOULD only be used when citing historical behavior that has since changed.

§4.1.1 Specification-level metadata

Each specification MUST have a trail.toml file in its specification directory containing:

name = "KACS"
description = "Kernel Access Control Subsystem — tokens, security descriptors, access checks, and integrity controls."

• name: The short display name of the specification. MUST match the name component of the directory (case may differ).
• description: A one-line description of what the specification covers.

No other fields are required at the specification level.

§4.1.2 Version-level metadata

Each version MUST have a trail.toml file in its version directory containing:

status = "draft"
date = "2026-04-24"

• status: The lifecycle state. See §3.2 for valid values and transition rules.
• date: The date of the most recent change to this version, in YYYY-MM-DD format.

No other fields are required at the version level.

§4.1.3 File-level metadata

Every markdown file within a specification MUST have YAML frontmatter containing at minimum:

---
title: Page Title
---

The title field is the display name of the section. No other frontmatter fields are required.

§4.2.1 Introduction chapter

Every PSD MUST have a 1-introduction/ chapter containing at minimum:

Additional introduction sections MAY be added after the required four.

§4.2.1.1 Scope

The scope section MUST list what the specification covers and what it does not cover. Items excluded from scope SHOULD identify which specification or subsystem covers them.

§4.2.1.2 Terminology

The terminology section MUST define terms specific to this specification. Terms already defined in another PSD MAY be delegated by reference rather than redefined:

Terms defined in PSD-006 (LCS, RSI, hive, source, key, value,
layer) are used here with the same meaning and are not redefined.

§4.2.1.3 Conventions

The conventions section MUST declare conformance to PSD-001 and MUST declare the use of RFC 2119 normative keywords. It SHOULD document any notational conventions used in the specification, including:

• Pseudocode notation (see §5.3)
• Byte order (if the specification defines binary formats)
• String encoding (if the specification defines string handling)

§4.2.1.4 Prior art

The prior art section MUST document the design influences, reference material, and compatibility considerations for the specification. The content varies by specification:

• For specifications with a clear predecessor (e.g., Windows Security Model): parity mappings documenting what is faithful, what diverges, and what is omitted.
• For specifications based on external standards (e.g., RFCs, ISO standards): which standards, which parts adopted, which parts rejected.
• For novel specifications: design influences, alternative approaches considered, and rationale for the chosen design.

§4.2.2 Substantive chapters

Every PSD MUST have at least one substantive chapter beyond the introduction. The number and organisation of substantive chapters is at the author's discretion.

§4.2.3 Appendices

Appendix chapters MUST be numbered contiguously after the last substantive chapter and SHOULD use the naming convention N-appendix-a/, N+1-appendix-b/, etc.

§4.2.4 Reference tables

Specifications that define registry schemas, constant sets, configuration parameters, or other enumerable artifacts SHOULD include a reference appendix that consolidates all such items with back-references to the normative section where each is defined.

Each entry in a reference table SHOULD include at minimum the item identifier (key path, constant name, etc.) and a § citation to the section that defines its semantics. Additional columns (type, default value, description) are at the author's discretion.

§4.3.1 Numbering scheme

The numbering scheme derives from the filesystem structure:

Chapter directories MUST use the format N-name/ where N is a positive integer. Files within chapters MUST use the format N-name.md where N is a positive integer.

Chapter and section numbering MUST start at 1 within their parent. Numbers MUST be sequential -- gaps SHOULD NOT exist in finalized versions but MAY exist in drafts.

§4.3.2 Subsection numbering

Subsections are numbered by the sequential order of headings within a file, not by explicit numeric prefixes. The first ## heading in a file is subsection 1, the second is subsection 2, and so on. Nested headings (###, ####) restart numbering within their parent heading.

## Overview          ← §3.2.1
## ACE Ordering      ← §3.2.2
### By Type          ← §3.2.2.1
### By Position      ← §3.2.2.2
## Inheritance       ← §3.2.3

§4.3.3 Files without subsection headings

A section file with no ## headings has no subsections. Content is addressed at the section level: §3.2, §3.2(1).

§4.3.4 Stability

Section numbers are positional. Inserting a chapter shifts all subsequent chapter numbers. Inserting a file shifts subsequent section numbers within that chapter. Inserting a ## heading shifts subsequent subsection numbers within that file.

Within a final version, the structure MUST NOT change. Section numbers are frozen on finalisation.

When a new version restructures content, the changelog (see §7.1) MUST document structural changes that affect numbering.

Every PSD MUST declare its use of RFC 2119 normative keywords in the conventions section of its introduction chapter (§1.3).

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

• MUST, MUST NOT
• SHALL, SHALL NOT
• SHOULD, SHOULD NOT
• MAY
• REQUIRED, OPTIONAL

A PSD MAY use a subset of these keywords. The conventions section MUST list which keywords the specification uses.

§5.2.1 Default

All text in a PSD is normative unless explicitly marked otherwise.

§5.2.2 Informative markers

Text MUST be marked as informative using one of the following:

• Block quotes with the [!INFORMATIVE] callout:

  > [!INFORMATIVE]
  > This text provides context but does not define behavior.
  

• Inline introduction using "For example" or "Note:":

  For example, a token with no groups would have an empty group list.
  
  Note: this behavior differs from the Windows implementation.
  

Informative text MUST NOT contain normative keywords (MUST, SHALL, etc.) used in their RFC 2119 sense. If an informative block needs to describe required behavior, it SHOULD refer to the normative clause that defines it.

§5.2.3 Clause numbering

Informative text MUST NOT receive clause numbers. Only normative statements are numbered (see §6.1).

PSDs that include pseudocode MUST document their pseudocode conventions in the conventions section of the introduction chapter (§1.3).

The following conventions are established across existing Peios specifications and SHOULD be used by new specifications for consistency:

Pseudocode MUST be enclosed in fenced code blocks (triple backticks).

§5.3.1 Type conventions

The following type conventions are established across existing specifications:

• All access masks are 32-bit unsigned integers unless otherwise stated.
• SID comparison is byte-for-byte equality of the binary encoding.
• GUID comparison is byte-for-byte equality of the 16-byte binary value.

A specification that relies on any of these conventions MUST state so explicitly rather than assuming the reader knows the convention.

§6.1.1 Definition

A clause is a specific normative statement within a PSD. Clauses are the fundamental unit of traceability -- they are what code implements, tests verify, and coverage matrices track.

§6.1.2 Which statements are clauses

Every statement using a normative keyword (MUST, MUST NOT, SHALL, SHALL NOT, SHOULD, SHOULD NOT, REQUIRED) in its RFC 2119 sense is a clause.

Statements using MAY or OPTIONAL are clauses if the behavior they describe needs to be tested or referenced. They MAY be excluded from clause counting if the behavior is trivial.

Informative text (see §5.2) is never a clause.

§6.1.3 Numbering

Clause numbers are positional and implicit. They MUST NOT be written inline in the specification text. A clause's number is derived by counting normative statements sequentially within the most specific section (the deepest heading level that contains them).

If a section has subsection headings, clause numbering restarts in each subsection.

## Overview

An ACL MUST contain at least one ACE.

## Ordering

ACEs MUST be sorted by type before evaluation.

The sort order MUST place deny ACEs before allow ACEs.

§6.1.4 When to cite at clause granularity

Most references SHOULD cite at the section or subsection level (§3.2 or §3.2.1). Clause-level citations (§3.2.1(3)) SHOULD be reserved for cases where a subsection contains multiple normative statements and the reference needs to identify one specifically.

§6.1.5 Stability

Within a final version, the document structure MUST NOT change. Clause numbers are frozen because the text they derive from is frozen.

When a new version restructures content, clause numbering shifts naturally with the text. The changelog (see §7.1) MUST document clause changes between versions so that consumers of the previous version's citations can update their references.

§6.2.1 The § notation

Sections within a PSD MUST be addressable using the § symbol followed by the hierarchical section number derived from the document structure (see §4.3).

§6.2.2 Citation format

A full citation combines the PSD number with a section address:

§6.2.3 Within-spec references

References to sections within the same specification SHOULD omit the PSD number:

The SD assigned to a new key is computed as described in §3.4.2.

When a bare § reference would be opaque without context, a hybrid form combining prose and § notation MAY be used for readability:

Sender authentication is performed via PID matching (§11.1.3).

The Notify socket subsection (§11.1.3) defines the
authentication protocol.

The § reference is the durable citation. The prose is a readability aid that MAY drift across versions without invalidating the reference.

§6.2.4 Between-spec references

References to other specifications MUST include the PSD number:

Access checks are performed using the algorithm defined in
PSD-004 §10.1(1).

When referencing an entire specification without a specific section:

All GUIDs in this specification conform to PSD-002.

No version annotation is needed -- the version resolution rule (§3.3) applies automatically.

§6.2.5 In code

Code comments referencing PSD clauses SHOULD use the full citation:

/* Per PSD-002 §2.1(1) */
struct peios_guid {
    uint32_t time_low;
    uint16_t time_mid;
    uint16_t time_hi_ver;
    uint8_t  clock_seq_hi;
    uint8_t  clock_seq_low;
    uint8_t  node[6];
};

// TestStartupSequence tests PSD-007 §2.1(3)
func TestStartupSequence(t *testing.T) { ... }

§6.2.6 In coverage matrices

Coverage matrices SHOULD use the full citation for each clause:

| Clause               | Code              | Test                    | Status |
|----------------------|-------------------|-------------------------|--------|
| PSD-004 §3.2.1(1)   | kacs/acl.c:142    | kacs_acl_test.c:test_1  | pass   |
| PSD-004 §3.2.1(2)   | kacs/acl.c:158    | kacs_acl_test.c:test_2  | pass   |

§6.3.1 Validation on version bump

When a new version of any PSD is published, all cross-references within the updated specification and all cross-references from other specifications that resolve to the updated specification SHOULD be validated.

§6.3.2 Validation steps

Cross-reference validation consists of:

1. Parse all PSD-NNN §x.y.z(n) references in the updated specifications.
2. Resolve the target version via the version resolution rule (§3.3).
3. Verify the section path exists in the target's document structure.
4. Verify the clause number exists by counting normative statements at the target location.
5. Optionally verify semantic consistency -- does the referenced content still match what the referencing text implies?

Steps 1 through 4 are mechanically automatable. Step 5 requires human or AI review.

§6.3.3 Unresolvable references

A reference that cannot be resolved (PSD number does not exist, section path does not exist in the resolved version, clause number exceeds the count of normative statements) SHOULD be treated as an error.

A specification MUST NOT be finalised with unresolvable cross-references.

§7.1.1 Requirement

Each version directory except the first MUST contain a CHANGES.md file documenting what changed from the previous version of the same specification.

The first version of a specification MUST NOT have a CHANGES.md file.

§7.1.2 Format

The changelog MUST use the following structure:

# PSD-004 (KACS): Changes in v0.22

## Summary

One-paragraph overview of why this version exists.

## Breaking Changes

- §10.1(3) removed — access check no longer considers X
- §4.3(5) changed — token lifetime now bounded by Y

## Additions

- New chapter: 15-audit-events
- §7.2(12) added — new privilege for Z

## Structural Changes

- Former chapter 8 is now chapter 9 (new chapter 8 inserted)
- All §8.x references from other specs must be updated to §9.x

## Clarifications

- §3.2.1(7) reworded for clarity (no semantic change)

§7.1.3 Rules

The heading MUST identify the PSD number, specification name, and version.

Breaking changes and additions MUST reference section and clause addresses using the new version's numbering.

Structural changes that shift section numbering MUST be called out explicitly. This aids cross-reference validation by identifying which external references need to be updated.

Clarifications MUST explicitly state "no semantic change" when the rewording does not alter the meaning of the normative statement.

Sections with no entries MAY be omitted from the changelog.

§8.1.1 Dictionary files

Peios maintains a corpus-wide dictionary of defined terms in dict/ at the learn site root. Each product or specification domain has its own dictionary file in TOML format.

A specification that introduces new terms SHOULD have a corresponding dictionary file at dict/<name>.toml.

§8.1.2 Term format

Dictionary entries MUST use the following TOML structure:

[[terms]]
term = "Security Identifier"
abbr = "SID"
aliases = ["SID"]
definition = "A variable-length binary value that uniquely identifies a principal."
category = "Identity"
product = "kacs"
etymology = "From Windows SIDs (MS-DTYP §2.4.2)"

[[terms.refs]]
label = "SID Format Specification"
path = "spec/kacs/v0.22/sids/format"

Required fields:

• term: The full display name of the term.
• definition: The definition text.
• category: A grouping category for related terms.

Optional fields:

• abbr: An abbreviation (e.g., "SID", "KACS").
• aliases: A list of alternative names for the term.
• product: Which product or specification this term belongs to.
• etymology: Historical source or origin of the term.
• refs: An array of references linking to specification sections.

§8.1.3 Auto-linking

The learn site configuration MUST enable automatic dictionary linking:

[dictionary]
auto_link = true

When auto-linking is enabled, Trail SHOULD automatically link occurrences of defined terms in rendered specification text to their dictionary entries.

§8.1.4 Relationship to terminology sections

Dictionary entries provide corpus-wide definitions for Trail to auto-link. Terminology sections within individual specifications (§4.2) provide specification-scoped definitions and may delegate to other specifications. The two mechanisms are complementary -- a term may appear in both a dictionary file and a terminology section.

PSDs frequently reference external specifications, standards, and documentation. This appendix defines the citation conventions for commonly referenced sources and the general rules for referencing any external document.

§9.1.1 Normative deferral

An external specification SHOULD only be referenced as a normative implementation dependency when the implementation would genuinely be delegated to a third-party library. If Peios owns the implementation, the PSD MUST be self-contained -- an implementer MUST be able to build the feature from the PSD alone, without reading the external source.

External sources SHOULD be cited as prior art, parity references, or format compatibility targets. They MUST NOT be the sole definition of behavior that Peios implements directly.

The boundary between "explicitly specify" and "defer to external" is whether the code is written by the Peios project:

• Kernel code: Almost always explicitly specify. There are no third-party libraries in the kernel. Even well-known formats (msgpack, CBOR, protobuf) must be specified in the PSD if they appear in kernel paths, because someone has to write or embed the implementation.
• Userspace code with library support: Deferral is acceptable when a well-maintained library exists and the specification would simply restate the library's contract. The PSD SHOULD still specify which subset of the external format is used and any constraints beyond what the library enforces.
• Userspace code without library support: Treat as kernel code -- explicitly specify.

A PSD that defers to an external specification MUST identify the deferral explicitly:

Event payloads are encoded using MessagePack as defined by the
MessagePack specification. KMES does not interpret or validate
payload contents; encoding and decoding are a userspace concern.

A PSD that re-specifies behavior from an external source MUST identify the external source as prior art and document any divergences:

SIDs use the binary format defined in this specification. The
format is byte-compatible with MS-DTYP §2.4.2. See §1.4 for
divergences.

§9.1.2 Citation format

External references MUST use the document's canonical short identifier where one exists (e.g., RFC 2119, MS-DTYP). The full title SHOULD appear at first use or in the prior art section (§1.4).

When referencing a specific location within an external document, the section number MUST be included: MS-DTYP §2.4.2, RFC 7230 §3.2.6. Use the section numbering convention native to the referenced document.

External references MUST NOT use URLs as the primary citation form. URLs are unstable. The canonical identifier and section number are the durable reference; a URL MAY be included parenthetically or in the prior art section for convenience.

§9.1.3 IETF RFCs

Format: RFC NNNN or RFC NNNN §N.N.

RFCs are cited by number. No zero-padding.

First use within a PSD SHOULD include the title:

... as described in RFC 2119 ("Key words for use in RFCs to
Indicate Requirement Levels").

§9.1.4 Microsoft Open Specifications

Format: MS-XXXX or MS-XXXX §N.N.N.

Microsoft protocol specifications are published under the Open Specifications program. They are cited by their short identifier (the [MS-XXXX] document code).

Section references use the document's own numbering:

SIDs use the binary format defined in MS-DTYP §2.4.2.

Conditional ACE bytecodes are specified in MS-DTYP §2.4.4.17.4
and MUST be byte-compatible.

§9.1.5 Unicode Standard

Format: Unicode N.N for the standard itself, or the filename for normative data files.

When a PSD references Unicode data files, it MUST specify the version and which entries are used:

Case-insensitive comparison uses Unicode Simple Case Folding
(CaseFolding.txt, status S and C entries, Unicode 16.0).

§9.1.6 MessagePack

Format: MessagePack or msgpack.

Event payloads are encoded using MessagePack (msgpack) as defined
by the MessagePack specification.

First use SHOULD include both the full name and the common abbreviation.

§9.1.7 systemd / sd_notify

Format: sd_notify (code-formatted as an API identifier).

References to systemd compatibility interfaces use the API name directly. No document citation is needed -- sd_notify is a well-known Linux API.

Services signal readiness via `READY=1` sent through sd_notify.

§9.1.8 Other external sources

For external sources not listed above, the following rules apply:

1. Use the document's canonical short identifier if one exists.
2. Include the full title at first use.
3. Include section numbers when referencing specific content.
4. Do not rely on URLs as the primary identifier.