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 spring, moving along one line, with nothing else in its world - 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 files that each contain deliberate mistakes - among them the commonest physics mistake: declaring a force and forgetting what balances it.

Explains: TPS 0.2.0 (proposed; revision 5 of the tree, imported 2026-09-26, not yet declared; TPS 0.1.0 was declared final on 2026-09-22), whose sections 2.2 to 2.5 now carry the zone schemas at schema 0.4.0 with the optional declared form (records D92.1, D98.1, D99.1, D100.1, D103.1-D105.1, D106.1-D108.1 and D132.1); TPC-PY as built at increment 9 (tpc_zone 0.4.0, tpc_units 0.1.0, tpc_tests 0.2.0, tpc_form 0.1.0; no TPC-PY version is declared yet) with check_draft 0.4.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 six entries changed:

DOF v:           "DIMENSION": "LT-1"
CONSTANT x_max:  "NAME": "x max"
LAW EOM_X:       "REFS": ["m", "v", "k", "x", "t"]
ASSUMPTION A_kpos gains:  "STATE": "PROPOSED"
CONSTRAINT C_NOZ:  "UNIT": "s"
BOUNDARY B_small:  "REFS": ["x", "x max"]

The checker says:

TPK  REFUSED, 9 problems
       ASSUMPTION:A_kpos: mutable field STATE is not permitted in the TFK
       BOUNDARY:B_small: CONDITION names x_max, which is not in REFS
       BOUNDARY:B_small: REFS x max is not named in CONDITION
       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:EOM_X: EQUATION names k_s, which is not in REFS
       LAW:EOM_X: REFS k does not resolve
       LAW:EOM_X: REFS k is not named in EQUATION
TrM  MISSING (not checked)
TMS  MISSING (not checked)
FINAL not run: a zone is missing

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

Message	What is wrong	Fix
ASSUMPTION:A_kpos: mutable field STATE ...	a status field inside the kernel	delete "STATE": "PROPOSED"; status lives in register records
BOUNDARY:B_small: CONDITION names x_max, which is not in REFS and REFS x max is not named in CONDITION	the boundary's REFS followed the misspelled constant; its CONDITION did not	fixed by renaming the constant and correcting the REFS, below
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
CONSTRAINT:C_NOZ: UNIT s has dimension T1, ...	z is a length, fixed with a unit of time	write "UNIT": "m"
DOF:v: DIMENSION LT-1 is not a dimension	the tokens run together	write L1 T-1
LAW:EOM_X: REFS k does not resolve, EQUATION names k_s, which is not in REFS and REFS k is not named in EQUATION	REFS names k, but the constant, and the equation, say k_s	correct the REFS entry

Nine lines, six mistakes. The declared forms report two of them more than once: an EQUATION or CONDITION must name exactly its REFS, so a wrong REFS entry shows up against the form as well. Without the forms, the boundary's REFS x max would have matched the misspelled constant and passed unnoticed. When you rename a thing, search the file for every place that cites it.

Mistakes in the manifold

examples/spring_mistakes_trm.json is the step-3 file with this entry E_v:

{
  "NAME": "E_v",
  "DOF": "v",
  "DOMAIN": "|x| < x_max",
  "ENVIRONMENT_QUANTITY": "speed",
  "IDENTIFICATION": "v is the rate of change of x with t",
  "FALSIFIER": "a measured velocity that differs from the rate of change of the measured x beyond uncertainty",
  "BEARS": ["KIN"],
  "DIMENSION": "L1 T-1"
}

TPK  PASS
     T2 PASS
     T5 PASS
     T4 PASS
     T6 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.4.0, tpc_units 0.1.0, tpc_tests 0.2.0, tpc_form 0.1.0; schema 0.4.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
     T4 PASS
     T6 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.4.0, tpc_units 0.1.0, tpc_tests 0.2.0, tpc_form 0.1.0; schema 0.4.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", "t"],
  "EQUATION": "D(x, t) = 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.4.0, tpc_units 0.1.0, tpc_tests 0.2.0, tpc_form 0.1.0; schema 0.4.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_pos (in place of A_kpos and A_mpos):
                   "PROPOSITION": "k_s is positive and m is positive"
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_pos: PROPOSITION joins claims with "and" (T2)
     T5 REFUSED, 1 problem
       DOF:y: named by no LAW (T5 c)
     T4 PASS
     T6 PASS
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.4.0, tpc_units 0.1.0, tpc_tests 0.2.0, tpc_form 0.1.0; schema 0.4.0). TPX decides at the gate.

Message	What is wrong	Fix
ASSUMPTION:A_pos: PROPOSITION joins claims with "and" (T2)	two claims in one assumption	make two assumptions, each with its own REFS: A_kpos for the stiffness, A_mpos for the mass
DOF:y: named by no LAW (T5 c)	y was added, but no law uses it	add the law that governs y - its equation of motion - 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 degree of freedom (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.

Two the declared forms catch

examples/spring_mistakes_form_law.json is the finished draft with a slip in EOM_X's equation: "EQUATION": "m * D(v, t) = -k_s * x * x".

TPK  PASS
     T2 PASS
     T5 PASS
     T4 REFUSED, 1 problem
       LAW:EOM_X: EQUATION sides have dimensions L1 M1 T-2 and L2 M1 T-2 (T4)
     T6 PASS
TrM  PASS
     IC1-IC4 PASS
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.4.0, tpc_units 0.1.0, tpc_tests 0.2.0, tpc_form 0.1.0; schema 0.4.0). TPX decides at the gate.

The left side is a force, L1 M1 T-2; the right side, with x twice, is L2 M1 T-2. Write -k_s * x. Only the EQUATION is read: the STATEMENT still said -k_s x, and a STATEMENT that disagreed with its EQUATION would pass every mechanical check. That agreement is read by the declaring authority at step 7.

examples/spring_mistakes_form_boundary.json rewrites the boundary's CONDITION as "x / x_max < 1":

TPK  PASS
     T2 PASS
     T5 PASS
     T4 PASS
     T6 REFUSED, 1 problem
       BOUNDARY:B_small: CONDITION uses / on x_max with no guard x_max != 0 (T6)
TrM  PASS
     IC1-IC4 PASS
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.4.0, tpc_units 0.1.0, tpc_tests 0.2.0, tpc_form 0.1.0; schema 0.4.0). TPX decides at the gate.

Dividing by x_max is undefined where x_max is 0, and a boundary must be decided for every value (T6). Either guard it, x_max != 0 and x / x_max < 1, or, better, write what the PREDICATE says, abs(x) < x_max. The guard would silence T6 but not the second mistake: x / x_max < 1 drops the lower half of |x| < x_max. The checker does not compare a CONDITION with its PREDICATE; the declaring authority does.

One the final pass catches

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

{
  "NAME": "C_OFF",
  "TARGET": "z",
  "ACTION": "FIX",
  "VALUE": "2",
  "UNIT": "cm",
  "STATEMENT": "only motion on the line z = 2 cm is described"
}

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

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

Everything before the final pass passes: C_OFF is well-formed, its unit is a length, and a law (EOM_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.

Gravity without the track

The commonest physics mistake is to declare one force and forget what balances it. examples/spring_mistakes_gravity.json is the finished draft, reread as a glider on a level track with z the height: the manifold's quantity for z is renamed height, and the author adds standard gravity (g_n, 9.80665 m s-2, the conventional value of the 3rd CGPM, 1901) and changes EOM_Z to say that gravity pulls the mass down, but keeps C_NOZ, the track that holds z at 0, and declares no force from the track:

"g_n" constant:  {"NAME": "g_n", "DIMENSION": "L1 T-2", "VALUE": "9.80665", "UNIT": "m s-2"}
LAW EOM_Z:       "EQUATION": "D(z, t, 2) = -g_n"

TPK  PASS
     T2 PASS
     T5 PASS
     T4 PASS
     T6 PASS
TrM  PASS
     IC1-IC4 PASS
TMS  PASS
YARDSTICK combined_distance: C1 pass, C2 pass, C4 pass
FINAL T3 (constraints and laws) and IC2 REFUSED, 1 problem
       LAW:EOM_Z and CONSTRAINT:C_NOZ: EOM_Z evaluates 0 = -9.80665 under the fixed values (T3)

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

The final pass evaluates EOM_Z, because every name in it now has a value: z is fixed, so its second derivative is 0, and g_n is 9.80665. The law says 0 = -9.80665. The kernel says the mass falls and says it cannot move: it contradicts itself. In the laboratory the track pushes up on the glider; in the kernel nothing does, because nothing is declared.

The fix is to declare the track's push. examples/spring_track_draft.json adds a DOF F_n, the support force, puts it in EOM_Z, and gives it a manifold entry:

DOF added:       {"NAME": "F_n", "DIMENSION": "M1 L1 T-2"}
LAW EOM_Z:       "STATEMENT": "m d2z/dt2 = F_n - m g_n"
                 "REFS": ["m", "z", "t", "F_n", "g_n"]
                 "EQUATION": "m * D(z, t, 2) = F_n - m * g_n"
inventory added: {"ENVIRONMENT_QUANTITY": "support_force", "DIMENSION": "M1 L1 T-2"}
ENTRY added:     E_Fn, identifying F_n with the upward force the track exerts, bearing EOM_Z

TPK  PASS
     T2 PASS
     T5 PASS
     T4 PASS
     T6 PASS
TrM  PASS
     IC1-IC4 PASS
TMS  PASS
YARDSTICK combined_distance: C1 pass, C2 pass, C4 pass
FINAL T3 (constraints and laws) and IC2 PASS

D(TPK) 329f45f982f2955f71dc5a87e593331f15207c32845218192f6fb18a945599bb
D(TrM) 0af6d96f513f0372226eed6e6ad01f77bc70146094cf15d124f566d56c0db42e
D(TMS) 4d872a9763445da95db9298c1ebaed56cf7ba744b126770c0da42b027d3e7b15
D(TFK) d178ad732fdd98b83fa89d00a15605a4ddfb76c89fc302daafd5db8a60242734

Inspections still owed to the declaring authority before declaring:
  - T2 the semantic part: each ASSUMPTION states one claim (guide 3.6)
  - T3 over the assumptions, and over the laws beyond the ground fragment at depth 1, to depth S_MAX (guide 3.6)
  - T4, T6 and T3 over every law or boundary without a declared form, as listed beside the kernel tests (D108.1)
  - IC4 (a) that each SIGNATURE image holds in the environment, beyond the syntactic reading, and each borne law is expressible (guide 4.6)
  - IC5 falsifier invariance under the TRANSFORMATIONS (guide 4.6)
  - equivalence of environment quantities under the TRANSFORMATIONS (names are taken as written)
  - every STATEMENT, PROPOSITION, PREDICATE and IMAGE names only what its REFS or OVER list, and agrees with its declared form where one exists

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

It passes. The support is now in the UWC, and with C_NOZ it has a value a result can derive: F_n = m g_n. Friction and air resistance are still absent, because they are still undeclared; add them the same way if your glider feels them.

Two cautions. First, T3 caught the first version only because every name in EOM_Z had a value. Written as m * D(z, t, 2) = -m * g_n, the same mistake passes every mechanical check (examples/spring_gravity_unbound.json), because m has no value; it then waits for the declaring authority's inspection at step 7. Second, g_n here is a constant you typed, with a value you chose; it is gravity only because you declared it.

PENDING D176-D18x: environment presets or modules. If an option such as "gravity at the default Earth-surface strength" is adopted, this section will show it in place of the hand-declared g_n and F_n.

Two more you will meet

A missing comma or bracket stops the file from being read at all. examples/spring_mistakes_syntax.json lacks the comma after the DOF x:

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

The message gives the line and column where the reader stopped, which is just after the mistake. And a number where a string belongs, or the reverse (examples/spring_mistakes_types.json, with "K": 2 and "N_X": "2"):

TPK  PASS
     T2 PASS
     T5 PASS
     T4 PASS
     T6 PASS
TrM  PASS
     IC1-IC4 PASS
TMS  REFUSED, 2 problems
       PARAMETERS: field K has the wrong type
       PARAMETERS: field N_X has the wrong type
FINAL not run: it runs once every check above passes

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

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. And it never tells you what you forgot to declare.

Worked example

The step is its own example.

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

---

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