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. Agents read the agent-facing page instead.

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.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; 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.

PENDING D176-D18x: the TPS section that states this closed-world rule, if one is added; this paragraph will then name it instead of explaining it from SR2 and SR3.

PENDING D176-D18x: environment presets or modules (for example gravity at the default Earth-surface strength, or air resistance at sea level) - whether they exist, how a kernel turns one on, and what each one adds to the kernel. Until that is decided, 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	none
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	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.

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.

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 with dimension T1, so a kernel that uses derivatives declares t 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.

PENDING D176-D18x: TPS 2.2 does not say whether a BOUNDARY's PREDICATE is true where the kernel is asserted or where it is not; this page follows the tutorial until a statement there settles the sense.

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).

PENDING D176-D18x: whether a kernel must declare its equations of motion (in the declared form or otherwise), or whether a first register objective settles them before other work, and what the gate does with a kernel that lacks them. Until then no check asks whether the equations of motion are complete.

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.

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.

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).

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 - 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"],
        "EQUATION": "m * D(v, t) = -k_s * x"
      },
      {
        "NAME": "KIN",
        "STATEMENT": "dx/dt = v",
        "REFS": ["x", "v", "t"],
        "EQUATION": "D(x, t) = v"
      },
      {
        "NAME": "EOM_Z",
        "STATEMENT": "m d2z/dt2 = 0",
        "REFS": ["m", "z", "t"],
        "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. B_small states where the kernel is asserted. The checker reports TPK PASS, and PASS for T2, T5, T4 and T6, for this zone; step by step, it is built on tutorial step 2.

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

---

Previous: The new-container form. Next: The Translation Manifold.