The Principia Machina/Inputs/Prime Kernel

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. Its counterpart for agents is the agent-facing page.

The three zones and their digests. The Prime Kernel is the first zone. (diagram page.)

Purpose

What you write in the first zone of the Full Kernel, kind by kind and field by field.

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; Generic Specification Guide 0.1.0, sections 3.1 and 3.6. Where this page and the specification differ, the specification governs.

A kernel assumes nothing it does not state

Read this before you write anything. The Full Kernel is a closed world: the only physics in a UWC is what its Prime Kernel declares - its degrees of freedom, constants, laws, assumptions, constraints and boundaries. Nothing is supplied from outside.

• No gravity, unless a law or a constant of the kernel declares it.
• No electric or magnetic force, unless declared.
• No friction and no air resistance, unless declared.
• No equation of motion except those the laws state. The kernel does not contain Newton's laws in general, or any other general law; it contains the equations you write, and nothing a reader would "normally assume" beside them.

Why: a result stands only while it derives from the TFK plus the assumptions it declares (TPS 4.4, SR2 and SR3). A derivation that uses a force stated neither in the kernel nor in the assumptions the result declares uses something the UWC does not contain; and an assumption brought in by a result is that result's, counted against it, never the kernel's. No check reports what you left out: completeness is judged only against what you declared (TPS 2.2), so a force you forgot is not an error message, it is simply absent from every result.

The rule is stated in TPS 2.2.19, the closed-world clause. A result may still use something the kernel leaves out, but only as its own assumption record: that record is counted against the result, and it never becomes part of the kernel.

Environment modules are selected (D178.1) and not yet built. The new-container form will ask one question: which of the modules the declaring authority has declared act on the system - the first catalogue selected holds gravity at the standard strength, air resistance at sea level in two forms, and the constant pi. Nothing is pre-selected, and the last answer is "None of these: only the laws I write act". A module you choose adds ordinary entries and terms to your kernel, each shown to you before it enters; nothing is switched on by default, so the closed world above still holds, and once the UWC is declared its modules are fixed with it (Inputs: environment modules; TPS 5.22). Until TPX runs the form, every force is declared by hand; tutorial step 6 shows it for gravity.

What the Prime Kernel is

The Prime Kernel (TPK) is the axiomatic base of a UWC: its laws, assumptions, hard boundaries and constraints, the constants they use, and the degrees of freedom (DOF) they leave free. It is the whole of the UWC's physics. It is immutable once declared. Any change, even a typo, is a new UWC by copy-forward, so check it before you submit (TPS 2.1 and 2.2).

The six kinds

A TPK is one JSON object whose keys are kinds. A kind you do not need may be left out; that means it is empty.

Kind	What it holds	Fields you must give	Fields you may add
DOF	a variable the kernel leaves free for its laws to relate: a coordinate, a state variable, or the time	NAME, DIMENSION	ROLE (only INPUT)
CONSTANT	a named quantity	NAME, DIMENSION	VALUE, UNIT, UNCERTAINTY
LAW	a statement taken as given; in a kernel that describes motion, its equations of motion	NAME, STATEMENT, REFS, ROLE	EQUATION
ASSUMPTION	one proposition taken as given for this UWC that the laws do not already say	NAME, PROPOSITION, REFS	none
CONSTRAINT	a restriction that removes or fixes one DOF	NAME, TARGET, ACTION, STATEMENT	VALUE, UNIT
BOUNDARY	a hard boundary: the region where the kernel is asserted, as a predicate (see PREDICATE below)	NAME, PREDICATE, REFS	CONDITION

Write the kinds in any order in your file. The digest reads them in a fixed order, so the order you choose changes nothing. The exact schema is TPS 2.2.

Beside the six kinds, a TPK may have one more key, PARAMETERS, with one field, D_VARIABLES: "ONE" or "SEVERAL". It says how many different variables the kernel's derivatives may be taken with respect to. ONE is the default: every D(x, s) in the kernel uses the same s, usually the time t, and a second one is refused. SEVERAL lets laws about something that changes in space and in time take derivatives in more than one variable; the structure check does not analyse such a kernel, and its label says so, with the reason PDE (partial differential equation). Leaving PARAMETERS out and writing "PARAMETERS": {"D_VARIABLES": "ONE"} give the same digest (TPS 2.2.6).

The fields

NAME

Letters, digits and the underscore, not starting with a digit, ASCII only: k_s, A_kpos, omega. A name must be unique across the whole TPK, not only within its kind. Greek letters are spelled out, because a Greek letter and a Latin look-alike would read as one name and resolve as two.

DIMENSION

The physical dimension, written in base dimensions with their exponents: L1 T-1 for a speed, M1 L1 T-2 for a force, 1 for a pure number. Always write the exponent, even when it is 1. The bases and the accepted forms are on Text and numbers.

REFS

The list of DOF and CONSTANT names the statement uses. Each must be a DOF or a CONSTANT of the same TPK; a law cannot cite a law, and no entry may cite itself. The checker cannot read your prose, so REFS is how it knows what a statement is about.

ROLE

Required on every LAW; optional on a DOF. It says what a law is for. On a law, write one of these, in capitals and with no spaces: EOM(x) when the law is the equation of motion of the DOF x - it says how x changes; CONSTRAINT for a relation the DOF must keep, such as a pendulum's fixed length (a kind of law, not a CONSTRAINT entry); CONSTITUTIVE for a law that gives a force or a material's response, such as a spring's force; INVARIANT for a quantity the motion keeps, such as an energy; DEFINITION for a law that defines one quantity from others. In the spring example KIN is "ROLE": "EOM(x)" and EOM_X is "ROLE": "EOM(v)"; EOM_Z, which restates the motion of z that C_NOZ fixes, is "ROLE": "CONSTRAINT" (a law that repeats a fixed DOF's motion takes CONSTRAINT, not EOM). On a DOF the only value is INPUT: a quantity the kernel takes as given, such as a driving force or a noise, which needs no equation of motion of its own. The checker refuses a role it cannot read, and an EOM(...) whose name is not a DOF of the kernel. Any other mismatch - an EOM(x) law with no derivative of x, say - is not refused: the structure check reports it (TPS 2.2.6).

STATEMENT, PROPOSITION, PREDICATE

Prose, in any notation you like, subject to the text rules on Text and numbers. Keep each ASSUMPTION to one proposition: "k_s is positive" is one; "k_s and m are positive" is two, and should be two entries. A BOUNDARY's PREDICATE is written, in the tutorial and on this page, to be true where the kernel is asserted: |x| < x_max.

EQUATION (on a LAW), CONDITION (on a BOUNDARY)

Optional. The same law or predicate in the declared form: a small closed grammar over the entry's REFS names, with D(x, t) for the derivative of x with respect to t and D(x, t, 2) for the second (TPS 2.2 states the grammar, its dimensional rules and its canonical spelling). Where a form is present, the checker reads it: the form must name exactly the entry's REFS, both sides of an EQUATION must have one dimension, and a CONDITION must be decided for every value. Where it is absent, those checks are the declaring authority's by inspection. Nothing forces a form on you (record D132.1). A derivative needs its variable - usually the time t - among the REFS, and that variable must be a DOF that no constraint fixes or removes; it may have any dimension, so a kernel in a scaled, dimensionless time works too (TPS 2.2.13). A kernel that uses derivatives therefore declares its variable as a DOF.

VALUE, UNIT, UNCERTAINTY (on a CONSTANT)

VALUE is a decimal written as a string, in quotes: "0.05". A VALUE needs a UNIT and a UNIT needs a VALUE. UNCERTAINTY needs a VALUE, is not negative, and is in the same UNIT. The UNIT is written in the unit form on Text and numbers and must have the constant's DIMENSION: a length may be in m, cm or au, never in s. A constant with a value is also what lets the final pass evaluate a law (see T3 below).

TARGET, ACTION, VALUE, UNIT (on a CONSTRAINT)

TARGET is the one DOF the constraint acts on. ACTION is REMOVE or FIX. FIX needs a VALUE and a UNIT with the TARGET's dimension (1 for a dimensionless DOF, rad or deg for an angle); REMOVE takes neither. A restriction such as "tabletop only" or "no rotation" is written here, as a CONSTRAINT, never as a weakened manifold entry (TPS 2.3). A constraint restricts which motions the kernel describes; it declares no force. If something in your system pushes to keep the constraint - a track, a rail, a string - that push is a force, and it is declared like any other.

A BOUNDARY's PREDICATE states where the kernel is asserted. Several boundaries all hold together; with none, the kernel is asserted everywhere (TPS 2.2.6).

Equations of motion

A kernel that describes motion states its equations of motion as laws: for every DOF except the time, a law that says how it changes. The kernel holds these equations and no general law beside them: writing m dv/dt = -k_s x declares that equation, not Newton's laws. The tutorial writes them out in full, in the declared form, one law each (tutorial step 2).

A check now asks. At the final pass the structure check reads every law that has an EQUATION, together with its ROLE (see ROLE above), and asks whether each DOF that changes is given by exactly one law: nothing missing, nothing given twice. It refuses nothing. It runs when the Measure Set's switch STRUCTURE_CHECK is ON, which it is unless you write OFF (the Measure Set). A DOF that no law gives is a named gap: the UWC then starts with a first task, EOM-0, which must supply that equation before other work lands. Every other finding goes to the declaring authority with a question.

The UWC's certificate carries one of two labels. structurally regular means the check ran and found nothing. Structure not Validated at Inception comes with its reason: the switch was off, the check found something, a law about motion is written only in prose, the laws take derivatives in more than one variable, or no law has an EQUATION. Both labels are valid UWCs, and the label never changes. The same test can run again later over the kernel and the results in the register; that result is shown beside the label, never in its place (TPS 2.2.20, 5.3.47).

What is refused

• The status fields STATE, SCRUTINY, RIDER, NOTE, CHECKS_OWED and RECORDS. They change over the UWC's life, so they belong in register records.
• Any other field the kind does not list.

Both are refused, never silently dropped: text outside the digest would be text the chain does not cover.

The checks

T1 well-formedness runs first, in TPC-PY and, when it is built, in TPX. It checks that every entry has its fields and no others, that names are identifiers and unique, that every REFS and TARGET resolves to the right kind, that dimensions, decimals and units parse, that every unit has the dimension of what it measures, that no entry cites itself, and that every declared form parses and names exactly its entry's REFS, that every law has a ROLE from the list and every EOM(...) names a DOF, and that every derivative's variable is a DOF no constraint fixes or removes - one for the whole kernel unless D_VARIABLES is SEVERAL.

If T1 passes, the kernel tests that run as the zone is entered follow (TPS 2.2):

• T2 atomicity, the part a machine can read: no assumption is visibly joined into two claims at its top level - by a joining word, a semicolon, a second sentence or a list. Text inside closed brackets or quotation marks is not top level. The exact words and signs are in TPS 2.2 and on Refusal messages.
• T5 DOF yield: every DOF is named in the REFS of some law - a DOF no law names is idle - and every constraint's TARGET is named by some law.
• T4 dimensional homogeneity, for every LAW with an EQUATION: both sides have one dimension.
• T6 boundary closure, for every BOUNDARY with a CONDITION: the condition is decided for every value, every partial operation guarded.

At the final pass, after the Measure Set is entered:

• T3 consistency, the part a machine can run: over the constraints, no DOF is both removed and fixed, or fixed at two values compared in SI; over the laws, no two laws give one left side two right sides, and a law whose every name has a value - a constant with a VALUE, or a DOF under a FIX - is evaluated and must not be false. T3 waits for the final pass because its depth, S_MAX, is in the Measure Set.
• The structure check, when the Measure Set's STRUCTURE_CHECK is ON: whether the equations of motion give every changing DOF exactly once. It refuses nothing; see Equations of motion above.

What no machine reads stays with the declaring authority, who inspects it before declaring; each inspection is recorded as debt. The list is in TPS 2.2, and the checker prints it at the end of every passing run: T2's meaning; T3 beyond what is evaluated; T4, T6 and T3 for every law or boundary without a form; and whether each prose field says what its REFS and its form say.

Non-goals

The checks do not judge whether your laws are right, or consistent beyond the bounded test T3 makes. They do not know what you left out: a force you did not declare is absent, and no message says so. The kernel certifies completeness only against the DOF it yields: a degree of freedom the kernel failed to include is invisible to every check (TPS 2.2). The structure check sees the shape of the equations, not their physics: a wrong equation of the right shape passes it.

Worked example

The spring kernel: four DOF (the time t, the displacement x and velocity v along the spring's axis, the displacement z across it), three constants (the mass, the spring's stiffness, and the largest displacement for which the spring law is asserted), three laws - the equations of motion, each with its EQUATION and its ROLE - two assumptions (the stiffness and the mass are positive), one constraint that fixes z at 0, and one boundary with its CONDITION. No gravity, friction, air resistance or electric or magnetic force is declared, so the UWC has none.

{
  "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"
      }
    ]
  }
}

EOM_X and KIN are the equations of motion along the axis; EOM_Z says no force acts across it, and C_NOZ restricts the kernel to motion on the axis, which is why EOM_Z's ROLE is CONSTRAINT. B_small states where the kernel is asserted. For this zone the checker prints:

TPK  PASS
     T2 PASS
     T5 PASS
     T4 PASS
     T6 PASS

With the Translation Manifold and the Measure Set of the tutorial added (examples/spring_draft.json), the structure check gives this kernel the label structurally regular. Step by step, it is built on tutorial step 2.

Governing sections: TPS 2.1, 2.2, 2.5 and 4.4.

---

Previous: Environment modules. Next: The Translation Manifold.