The Principia Machina/Inputs/Yardsticks

The Principia Machina: map
Reading the diagrams Structure key Process key Definition of terms Roles
Reading by audience Start here: the walk through The operator's guide Tutorial: create a UUID Workspace Container (UWC) Public Recorder inputs Sponsors: your first agent
The specification Contents: parts, tables, diagrams TPS 0.5.0 (declared 2026-10-03, revision 8; machine-optimized text) Decisions (the foundations record, one line each)

Public Recorder inputs: a help set for the people who put things into The Principia Machina - authors of a new UWC, operators, and the declaring authority. It explains; the specification governs. Start at the index; for a guided walk from a blank file to a declared UWC, follow the tutorial. Agents read the agent-facing page instead.

Where ordering enters: SR4 and SR5 order conflicting records; a yardstick refines the order, never the outcome. (diagram page.)

Purpose

How to write a yardstick: a UWC's own rule for ordering records, and the rules that keep it from bending the strike skeleton.

Explains: TPS 0.3.0 (declared final on 2026-09-28 at revision 6; it follows TPS 0.1.1, declared final on 2026-09-26), whose sections 2.2 to 2.5 carry the zone schemas with the optional declared form, the ROLE field, the D variable and the structure check (records D92.1, D98.1, D99.1, D100.1, D103.1-D105.1, D106.1-D108.1, D132.1, D176.1, D177.1, D179.1 and D186.1); TPC-PY 0.1.0 (declared on 2026-09-28, tree digest a00161c1b321fd66abc591209007d46a7fa6290097835060e50f381426259043, conformed TPS 0.3.0; tpc_zone 0.5.0, tpc_units 0.1.1, tpc_tests 0.2.0, tpc_form 0.2.0, tpc_eom 0.1.0; schema 0.5.0) with check_draft 0.5.0; the yardstick evaluator, TPC-PY tpc_yardstick 0.1.0. Where this page and the specification differ, the specification governs.

What a yardstick is

When two standing records contradict each other, the strike rule keeps the one closer to the TFK and strikes the other. The framework's own measure of closeness is distance: first the number of assumptions a record rests on, then its number of derivation steps (SR4, SR5). A yardstick is a Measure Set entry that declares a finer order, or a different order inside a limiting case. It orders records; it never decides a contradiction itself. SR5 and SR7 do that, whatever the yardstick says (TPS 2.4, 4.4 and 4.5).

The form

Each yardstick is an object with three fields, all required:

NAME

an identifier, unique among the yardsticks.

KEY

a list of terms. Two records are compared term by term, first to last; the first term that differs decides, and the lower value is closer.

LIMITING

a list of limiting cases, each {"DOMAIN": ..., "KEY": [...]}. Inside that DOMAIN, and only there, its KEY replaces the main KEY. Write [] when there are none.

The terms

Term	Value on a record
SR1	0 if the record passes SR1 (it does not contradict the TFK), 1 if it fails
A	the number of distinct assumptions in the record's closure
S	the record's number of derivation steps
FIELD:name	a numeric field of the record (not usable yet; see below)
NEG:term	the term with its sign reversed
WSUM:c*atom;...	a weighted sum; each weight c is a TMS constant by name; each atom (A, S or FIELD:name) at most once

A term contains no spaces.

The rules a key must meet

1. It begins with SR1, and SR1 appears nowhere else. So every record that contradicts the TFK ranks below every record that does not (SR9 C1).
2. Every term parses, and every weight is a TMS constant (SR9 C5).
3. Adding an assumption never makes a record closer. The first term whose value moves with A must move up with it. A key that prefers records with more assumptions is refused (SR9 C2). A limiting key is exempt inside its declared DOMAIN, as SR9 C2 allows.
4. You cannot declare how contradictions are resolved. That is fixed by SR5 and SR7 (SR9 C4).

The second line: the SR9 harness

A yardstick that passes the key rules is then run on the synthetic record suite, a fixed set of test records, and SR9 C1, C2 and C4 are checked on it. The checker prints one line per yardstick:

YARDSTICK combined_distance: C1 pass, C2 pass, C4 pass

For a well-formed yardstick without FIELD terms the key rules already guarantee all three, so this line confirms them. If it ever shows FAIL on a yardstick the key rules accepted, that is a defect in the checker, not in your draft: report it to the operator.

FIELD terms

A FIELD term names a numeric field of a register record. The list of record fields is owed (C-16), so a FIELD term passes the key rules but cannot be run: the checker reports REFUSED, FIELD terms await the record field schema (C-16) and the draft does not pass. Do not use FIELD terms until C-16 lands.

Non-goals

A pass on the synthetic suite is evidence, not proof: the suite is finite (TPS 4.5).

Worked example

The spring UWC's yardstick, with constants w_a = "1" and w_s = "0.5":

{
  "NAME": "combined_distance",
  "KEY": ["SR1", "WSUM:w_a*A;w_s*S", "S"],
  "LIMITING": []
}

It ranks first on SR1, then on a + 0.5 s, then on s. Take two records that both pass SR1. The first rests on one assumption and takes three steps: its key is [0, 2.5, 3]. The second rests on two assumptions and takes one step: its key is [0, 2.5, 1]. They tie on the weighted sum, and the step count breaks the tie: the second is closer.

A limiting case, which reverses the priority of steps and assumptions only for small displacements:

{
  "NAME": "small_domain_first",
  "KEY": ["SR1", "A", "S"],
  "LIMITING": [
    {
      "DOMAIN": "|x| < x_max / 10",
      "KEY": ["SR1", "S", "A"]
    }
  ]
}

Two keys that are refused, with the checker's messages:

[
  {
    "NAME": "no_sr1",
    "KEY": ["WSUM:w_a*A;w_s*S", "S"],
    "LIMITING": []
  },
  {
    "NAME": "prefers_more",
    "KEY": ["SR1", "NEG:A"],
    "LIMITING": []
  }
]

YARDSTICK:no_sr1: KEY must begin with SR1
YARDSTICK:prefers_more: KEY ranks a record higher when an assumption is added (SR9 C2)

Governing sections: TPS 2.4, 4.4 and 4.5.

---

Previous: The Measure Set. Next: Text and numbers.