The Principia Machina/Tutorial/5 Check the draft

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

Run the full check, read every line of its output, and understand what the four digests are and are not.

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, and TPC-PY 0.2.0 (declared on 2026-09-30; tree digest 2998ac4c24dff83bd047a691081b7d27bb25c9d26512bffe519f5c2b6ba127e2, conformed TPS 0.4.0; tpc_zone 0.5.1, tpc_units 0.1.2, tpc_tests 0.2.1, tpc_form 0.2.1, tpc_eom 0.2.0; schema 0.5.0) with check_draft 0.6.0. Where this page and the specification differ, the specification governs.

The finished draft

This is examples/spring_draft.json, exactly. You can copy it from here into a file. Everything the UWC's physics contains is in its "TPK" zone: a mass, a spring, the time, and nothing else.

{
  "TPK": {
    "DOF": [
      {"NAME": "t", "DIMENSION": "T1"},
      {"NAME": "x", "DIMENSION": "L1"},
      {"NAME": "v", "DIMENSION": "L1 T-1"},
      {"NAME": "z", "DIMENSION": "L1"}
    ],
    "CONSTANT": [
      {"NAME": "m", "DIMENSION": "M1"},
      {"NAME": "k_s", "DIMENSION": "M1 T-2"},
      {
        "NAME": "x_max",
        "DIMENSION": "L1",
        "VALUE": "0.05",
        "UNIT": "m",
        "UNCERTAINTY": "0.001"
      }
    ],
    "LAW": [
      {
        "NAME": "EOM_X",
        "STATEMENT": "m dv/dt = -k_s x",
        "REFS": ["m", "v", "k_s", "x", "t"],
        "ROLE": "EOM(v)",
        "EQUATION": "m * D(v, t) = -k_s * x"
      },
      {
        "NAME": "KIN",
        "STATEMENT": "dx/dt = v",
        "REFS": ["x", "v", "t"],
        "ROLE": "EOM(x)",
        "EQUATION": "D(x, t) = v"
      },
      {
        "NAME": "EOM_Z",
        "STATEMENT": "m d2z/dt2 = 0",
        "REFS": ["m", "z", "t"],
        "ROLE": "CONSTRAINT",
        "EQUATION": "m * D(z, t, 2) = 0"
      }
    ],
    "ASSUMPTION": [
      {
        "NAME": "A_kpos",
        "PROPOSITION": "k_s is positive",
        "REFS": ["k_s"]
      },
      {
        "NAME": "A_mpos",
        "PROPOSITION": "m is positive",
        "REFS": ["m"]
      }
    ],
    "CONSTRAINT": [
      {
        "NAME": "C_NOZ",
        "TARGET": "z",
        "ACTION": "FIX",
        "VALUE": "0",
        "UNIT": "m",
        "STATEMENT": "only motion on the spring axis is described: z = 0"
      }
    ],
    "BOUNDARY": [
      {
        "NAME": "B_small",
        "PREDICATE": "|x| < x_max",
        "REFS": ["x", "x_max"],
        "CONDITION": "abs(x) < x_max"
      }
    ]
  },
  "TrM": {
    "HEADER": {
      "ENVIRONMENT_INVENTORY": [
        {"ENVIRONMENT_QUANTITY": "time", "DIMENSION": "T1"},
        {"ENVIRONMENT_QUANTITY": "position", "DIMENSION": "L1"},
        {"ENVIRONMENT_QUANTITY": "velocity", "DIMENSION": "L1 T-1"},
        {"ENVIRONMENT_QUANTITY": "transverse_position", "DIMENSION": "L1"}
      ],
      "SIGNATURE": [
        {
          "NAME": "time_derivative",
          "OVER": ["x", "v", "t"],
          "IMAGE": "d/dt maps position to velocity",
          "FORM": "D(x, t) = v",
          "IMAGE_FORM": "D(position, time) = velocity"
        }
      ],
      "TRANSFORMATIONS": [
        {"NAME": "time_translation", "STATEMENT": "t -> t + t0"}
      ]
    },
    "ENTRIES": [
      {
        "NAME": "E_t",
        "DOF": "t",
        "DOMAIN": "always",
        "ENVIRONMENT_QUANTITY": "time",
        "IDENTIFICATION": "t is the reading of a laboratory clock from an arbitrary origin",
        "FALSIFIER": "a second clock whose readings differ from t by more than a constant offset beyond the stated uncertainty",
        "FALSIFIER_CLASS": "F3",
        "BEARS": [],
        "DIMENSION": "T1"
      },
      {
        "NAME": "E_x",
        "DOF": "x",
        "DOMAIN": "|x| < x_max",
        "ENVIRONMENT_QUANTITY": "position",
        "IDENTIFICATION": "x is the displacement of the mass along the spring axis from the point where the spring exerts no force",
        "FALSIFIER": "a measured spring force not proportional to x inside the domain",
        "FALSIFIER_CLASS": "F3",
        "BEARS": ["EOM_X", "KIN"],
        "DIMENSION": "L1"
      },
      {
        "NAME": "E_v",
        "DOF": "v",
        "DOMAIN": "|x| < x_max",
        "ENVIRONMENT_QUANTITY": "velocity",
        "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",
        "FALSIFIER_CLASS": "F2",
        "BEARS": ["KIN"],
        "DIMENSION": "L1 T-1"
      },
      {
        "NAME": "E_z",
        "DOF": "z",
        "DOMAIN": "always",
        "ENVIRONMENT_QUANTITY": "transverse_position",
        "IDENTIFICATION": "z is the displacement of the mass perpendicular to the spring axis",
        "FALSIFIER": "a measured z different from 0 beyond its uncertainty",
        "FALSIFIER_CLASS": "F3",
        "BEARS": ["EOM_Z", "C_NOZ"],
        "DIMENSION": "L1"
      }
    ]
  },
  "TMS": {
    "PARAMETERS": {
      "STEP_CONVENTION": "one application of an inference rule or algebraic identity is one step",
      "K": "2",
      "N_X": 2,
      "S_MAX": 10
    },
    "CONSTANTS": [
      {"NAME": "w_a", "VALUE": "1"},
      {"NAME": "w_s", "VALUE": "0.5"}
    ],
    "YARDSTICKS": [
      {
        "NAME": "combined_distance",
        "KEY": ["SR1", "WSUM:w_a*A;w_s*S", "S"],
        "LIMITING": []
      }
    ]
  }
}

Run it

python3 check_draft.py my_draft.json        (Linux, macOS)
py check_draft.py my_draft.json             (Windows)

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
STRUCTURE map (shown whatever STRUCTURE_CHECK says): analysis RUN; D variable t
     t: INDEPENDENT
     v: DETERMINED (LAW EOM_X)
     x: DETERMINED (LAW KIN)
     z: FIXED
     index 0, initial values 2 (the determined part; information)
     closed: EOM_Z (ZERO)
STRUCTURE findings: none
STRUCTURE structurally regular

D(TPK) ad9d20d633d374edf7f7a2ddfefa6e886e67132a6e8a7cd42edd0237d3927088
D(TrM) f767f3635d0cbc54473b6f889c20a94d8d37f95d627d2c856516bac9c7d37de9
D(TMS) 7a962e2297d6798801fa2593be9cd92995cc3a5f9c817cc8a19335c625784128
D(TFK) 46db0af2a3f5fd6e86447bd1764cd5b934cf0f0be3c9f91d16fd47aa435afe5b

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.5.1, tpc_units 0.1.2, tpc_tests 0.2.1, tpc_form 0.2.1, tpc_eom 0.2.0; schema 0.5.0). TPX decides at the gate.

Reading the output

TPK PASS, TrM PASS, TMS PASS

Each zone passed its structural checks: T1 for the kernel (the declared forms parsed, and their names match REFS), and the schema checks for the manifold and the Measure Set, including the yardstick key rules.

T2 PASS, T5 PASS

The two kernel tests that run on every kernel as it is entered: no assumption is joined into two claims, and no degree of freedom (DOF) or constraint is idle.

T4 PASS, T6 PASS

The two that run where a form is declared: each EQUATION has one dimension on both sides, and the CONDITION is decided for every value. Without forms these lines read NO FORM (by inspection) (step 2.8).

IC1-IC4 PASS

The isomorphism checks, as the manifold is entered: every quantity and every DOF is identified exactly once, the dimensions match, what each entry bears has entries, and the signature's FORM reads as its IMAGE_FORM. An untied DOF would be listed here and held for the final pass.

YARDSTICK combined_distance: C1 pass, C2 pass, C4 pass

The yardstick ran on the synthetic record suite and met SR9 C1, C2 and C4.

FINAL T3 (constraints and laws) and IC2 PASS

The final pass, which needs all three zones: no DOF is both removed and fixed, or fixed twice; no two laws give one left side two different right sides; no law whose every name has a value is false; and no untied DOF is left for IC2_POLICY to settle. In this draft no law has a value for every name - m, k_s, x and v have none - so the last test finds nothing to evaluate. Step 6 shows a law that it does evaluate.

The STRUCTURE lines

The structure check's result: the EOM map, which gives for each DOF its label and the law that gives it; the findings, each with its question for the declaring authority; and the label the final pass would give, here structurally regular. With STRUCTURE_CHECK set to OFF the label would read Structure not Validated at Inception, reason CHECK OFF (TPS 2.2.20).

The four D(...) lines

The digests of the three zones and of the whole TFK. See below.

The list of inspections

What no machine checks yet. The declaring authority performs these by eye before declaring (step 7).

The last line

A reminder that this result is advisory, and which TPC-PY modules produced it.

The exit status is 0: all three zones are present and every check passes.

Note what the output does not say. Nothing in it tells you the kernel lacks gravity, friction or air resistance: that is your choice, made at step 1 and written at step 2. The structure check tells you whether each DOF has one equation of motion, not whether the equations are the right physics. A pass means the draft is well-formed; it does not mean the physics you meant is the physics you wrote.

What the digests are

Each is a SHA-256 fingerprint of one zone in a canonical form, and D(TFK) combines the three in a fixed order. The UWC will be bound to D(TFK): every write is checked against it, and a mismatch halts all writes until the declaring authority decides (TPS 2.5). Because the canonical form normalizes spelling, only a change of meaning moves a digest (Text and numbers). A digest also names the schema version it was taken under: the same kernel checked under an older schema gives different digests.

What the digests are not

• Not something to type anywhere. TPX computes the digests again from the draft it stores; a digest copied by hand is not a digest.
• Not a certificate. TPX of record decides. These digests exist so that you and the declaring authority can compare them with TPX's candidate certificate at step 7: a difference means the draft TPX holds is not the file you checked.

If your copy of the example gives different digests, your file differs from the one above, or your checker is not the one named on the last line; compare them line by line.

Non-goals

A pass does not mean the kernel is right. It means the draft is well-formed under the checks that exist.

Worked example

The step is its own example.

Governing sections: TPS 2.5, 5.5, 2.2 and 4.5.

---

Previous: 4 Write the Measure Set. Next: 6 Fix refusals.