The Principia Machina/Tutorial/6 Fix refusals

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)

Tutorial: create a new UWC. One small example - a mass on a linear spring, moving only along x - is taken from a blank file to a declared UWC in eight steps. Each step says what runs today and what is specified but not yet built. It explains; the specification governs. Field-by-field reference: Public Recorder inputs.

Purpose

Practise reading refusals and fixing them, on six files that each contain deliberate mistakes.

Explains: TPS 0.1.0, revision 4 (declared final 2026-09-22); the zone schemas the declaring authority selected on 2026-09-22 (records D92.1, D98.1, D99.1, D100.1, and for units D103.1, D104.1, D105.1; schema 0.3.0), whose text enters TPS at revision 5, and the kernel tests and isomorphism checks selected the same day (D106.1, D107.1, D108.1; tpm_kernel_tests 0.2.0), whose text follows at the next TPS revision; TPC-PY as built 2026-09-22 (tpc_zone 0.3.0, tpc_units 0.1.0, tpc_tests 0.1.0; no TPC-PY version is declared yet) with check_draft 0.3.0. Where this page and the specification differ, the specification governs.

Every refusal names its component first, so you can find it in your file. All problems in a zone are listed at once, sorted alphabetically. Fix them all, then run the check again. Every message is explained on Inputs: refusal messages.

Mistakes in the kernel

examples/spring_mistakes_tpk.json is the step-2 kernel with these entries changed (the others as before):

"DOF":        {"NAME": "v", "DIMENSION": "LT-1"}
"CONSTANT":   {
                "NAME": "x max",
                "DIMENSION": "L1",
                "VALUE": "0.05",
                "UNIT": "m",
                "UNCERTAINTY": "0.001"
              }
"LAW":        {
                "NAME": "N2",
                "STATEMENT": "m dv/dt = -k_s x",
                "REFS": ["m", "v", "k", "x"]
              }
"ASSUMPTION": {
                "NAME": "A_lin",
                "PROPOSITION": "the restoring force is linear in x (Hooke régime)",
                "REFS": ["x"],
                "STATE": "PROPOSED"
              }
"CONSTRAINT": {
                "NAME": "C_NOZ",
                "TARGET": "z",
                "ACTION": "FIX",
                "VALUE": "0",
                "UNIT": "s",
                "STATEMENT": "motion confined to z = 0"
              }
"BOUNDARY":   {
                "NAME": "B_small",
                "PREDICATE": "|x| < x_max",
                "REFS": ["x", "x max"]
              }

The checker says:

TPK  REFUSED, 5 problems
       ASSUMPTION:A_lin: mutable field STATE is not permitted in the TFK
       CONSTANT:x max: NAME x max is not an identifier
       CONSTRAINT:C_NOZ: UNIT s has dimension T1, not L1 of TARGET z
       DOF:v: DIMENSION LT-1 is not a dimension
       LAW:N2: REFS k does not resolve
TrM  MISSING (not checked)
TMS  MISSING (not checked)
FINAL not run: a zone is missing

Advisory result (TPC-PY: tpc_zone 0.3.0, tpc_units 0.1.0, tpc_tests 0.1.0; schema 0.3.0). TPX decides at the gate.

Message	What is wrong	Fix
ASSUMPTION:A_lin: mutable field STATE ...	a status field inside the kernel	delete "STATE": "PROPOSED"; status lives in register records
CONSTANT:x max: NAME x max is not an identifier	a space in a name	rename it x_max, and correct the boundary's REFS to match
DOF:v: DIMENSION LT-1 is not a dimension	the tokens run together	write L1 T-1
LAW:N2: REFS k does not resolve	REFS names k, but the constant is k_s	correct the REFS entry
CONSTRAINT:C_NOZ: UNIT s has dimension T1, ...	z is a length, fixed with a unit of time	write "UNIT": "m"

Note that the boundary's REFS still said x max and was not refused: it matched the misspelled constant exactly. When you rename a thing, search the file for every place that cites it.

Mistakes in the manifold

examples/spring_mistakes_trm.json has this entry E_v:

{
  "NAME": "E_v",
  "DOF": "v",
  "DOMAIN": "|x| < x_max",
  "ENVIRONMENT_QUANTITY": "speed",
  "IDENTIFICATION": "v is the time derivative of x",
  "FALSIFIER": "a measured velocity differing from dx/dt beyond uncertainty",
  "BEARS": ["KIN"],
  "DIMENSION": "L1 T-1"
}

TPK  PASS
     T2 PASS
     T5 PASS
TrM  REFUSED, 2 problems
       ENTRY:E_v: ENVIRONMENT_QUANTITY speed is not in the ENVIRONMENT INVENTORY
       ENTRY:E_v: missing field FALSIFIER_CLASS
TMS  MISSING (not checked)
FINAL not run: a zone is missing

Advisory result (TPC-PY: tpc_zone 0.3.0, tpc_units 0.1.0, tpc_tests 0.1.0; schema 0.3.0). TPX decides at the gate.

E_v names speed, which the inventory does not list (it says velocity), and has no FALSIFIER_CLASS. Use velocity and add "FALSIFIER_CLASS": "F2".

Mistakes in the Measure Set

examples/spring_mistakes_tms.json declares these two yardsticks:

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

TPK  PASS
     T2 PASS
     T5 PASS
TrM  PASS
     IC1-IC4 PASS
TMS  REFUSED, 2 problems
       YARDSTICK:combined_distance: KEY must begin with SR1
       YARDSTICK:prefers_more: KEY ranks a record higher when an assumption is added (SR9 C2)
FINAL not run: it runs once every check above passes

Advisory result (TPC-PY: tpc_zone 0.3.0, tpc_units 0.1.0, tpc_tests 0.1.0; schema 0.3.0). TPX decides at the gate.

The first key begins with the weighted sum instead of SR1; put SR1 first. The second, ["SR1", "NEG:A"], prefers records with more assumptions, which SR9 C2 forbids; delete it, or, if it expresses a real limiting case, move it into a LIMITING entry with the DOMAIN where it applies.

A hidden character

examples/spring_mistakes_text.json has an invisible right-to-left override, U+202E, at the end of a law's statement. On screen the statement looks correct; in the file, where JSON lets it be written as an escape, it is visible:

{
  "NAME": "KIN",
  "STATEMENT": "dx/dt = v\u202e",
  "REFS": ["x", "v"]
}

TPK  REFUSED, 1 problem
       LAW:KIN: field STATEMENT contains disallowed character U+202E
TrM  MISSING (not checked)
TMS  MISSING (not checked)
FINAL not run: a zone is missing

Advisory result (TPC-PY: tpc_zone 0.3.0, tpc_units 0.1.0, tpc_tests 0.1.0; schema 0.3.0). TPX decides at the gate.

Delete the statement and type it again. Text copied from web pages, chat programs and PDF files is where such characters usually come from.

Mistakes the kernel tests and isomorphism checks catch

examples/spring_mistakes_checks.json is the finished draft with four changes. Each is well-formed on its own, so the structure checks pass, and the next checks find them:

ASSUMPTION A_lin:  "PROPOSITION": "the restoring force is linear in x and the track is frictionless"
DOF added:         {"NAME": "y", "DIMENSION": "L1"}
inventory added:   {"ENVIRONMENT_QUANTITY": "acceleration", "DIMENSION": "L1 T-2"}
ENTRY E_v:         "DIMENSION": "L1"

The checker says:

TPK  PASS
     T2 REFUSED, 1 problem
       ASSUMPTION:A_lin: PROPOSITION joins claims with "and" (T2)
     T5 REFUSED, 1 problem
       DOF:y: named by no LAW (T5 c)
TrM  PASS
     IC1-IC4 REFUSED, 3 problems
       IC1: environment quantity acceleration is identified by no entry
       IC4(b): ENTRY:E_v: DIMENSION L1 differs from DOF v's L1 T-1
       IC4(b): ENTRY:E_v: DIMENSION L1 differs from environment quantity velocity's L1 T-1
     and 1 untied DOF, held for the final pass
       IC2: DOF y is untied
TMS  PASS
YARDSTICK combined_distance: C1 pass, C2 pass, C4 pass
FINAL not run: it runs once every check above passes

Advisory result (TPC-PY: tpc_zone 0.3.0, tpc_units 0.1.0, tpc_tests 0.1.0; schema 0.3.0). TPX decides at the gate.

Message	What is wrong	Fix
ASSUMPTION:A_lin: PROPOSITION joins claims with "and" (T2)	two claims in one assumption	make two assumptions, each with its own REFS: A_lin for the linear force, A_nofric for the frictionless track
DOF:y: named by no LAW (T5 c)	y was added, but no law uses it	add the law that governs y, or delete y
IC1: environment quantity acceleration is identified by no entry	the inventory lists a quantity no entry uses	remove it from the inventory; the kernel has no DOF for it
IC4(b): ENTRY:E_v: DIMENSION L1 differs ... (two lines)	E_v says a length; v and velocity are L1 T-1	write "DIMENSION": "L1 T-1" in E_v
IC2: DOF y is untied	y has no manifold entry; held, not refused	goes with y: delete y, or give it a law and an entry

The last line is not a problem. It is held for the final pass, where the Measure Set's IC2_POLICY would decide it; the final pass did not run, because other checks refused. Note that T2 and T5 did not stop the manifold's checks: those need only a kernel that passes T1, so you see every problem in one run.

One the final pass catches

examples/spring_mistakes_final.json is the finished draft with a second constraint on z:

"CONSTRAINT": [ ..., {
    "NAME": "C_REST",
    "TARGET": "z",
    "ACTION": "FIX",
    "VALUE": "2",
    "UNIT": "cm",
    "STATEMENT": "the mass rests on a 2 cm block"
  }]

TPK  PASS
     T2 PASS
     T5 PASS
TrM  PASS
     IC1-IC4 PASS
TMS  PASS
YARDSTICK combined_distance: C1 pass, C2 pass, C4 pass
FINAL T3 and IC2 REFUSED, 1 problem
       CONSTRAINT:C_NOZ and CONSTRAINT:C_REST: z fixed at 0 m and at 2 cm (T3)

Advisory result (TPC-PY: tpc_zone 0.3.0, tpc_units 0.1.0, tpc_tests 0.1.0; schema 0.3.0). TPX decides at the gate.

Everything before the final pass passes: C_REST is well-formed, its unit is a length, and a law (FREE_Z) names z. Only with the three zones in hand does T3 compare the two values, in SI: 0 m against 0.02 m. A DOF cannot be fixed at two values; keep one constraint. If the mass does rest on a block, fix z at 2 cm in C_NOZ, change its statement, and delete C_REST.

Two more you will meet

A missing comma or bracket stops the file from being read at all:

DRAFT: cannot be read: Expecting ',' delimiter: line 6 column 7 (char 115)

The message gives the line and column. And a number where a string belongs, or the reverse:

TMS  REFUSED, 2 problems
       PARAMETERS: field K has the wrong type
       PARAMETERS: field N_X has the wrong type

K is a decimal and goes in quotes, "2"; N_X and S_MAX are whole numbers and do not.

Non-goals

The checker never repairs a draft. It tells you what to change; you change it.

Worked example

The step is its own example.

Governing sections: TPS 5.5, 2.2, 2.3 and 2.4.

---

Previous: 5 Check the draft. Next: 7 Inspect, submit and declare.