The Principia Machina/Inputs/Environment modules

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.

Purpose

What an environment module is, how the new-container form offers the modules, what a chosen module adds to a kernel, and what happens to a draft or a UWC when a module it uses changes status.

Explains: environment modules as the declaring authority selected them in D178.1: its slots (a) to (f) on 2026-09-26 (an interview on the form, module declarations outside D(IS), the modules used recorded beside the kernel, terms composed into one equation of motion, the first catalogue, the kernel as the only target) and its slot (g), the catalogue lifecycle, on 2026-09-27, with the constraint "fixed at inception, must be copied to change settings". The specification carries them in TPS 0.3.0 (declared final on 2026-09-28 at revision 6; TPS 0.4.0, declared final on 2026-09-30 at revision 7, is in force, and revision 8, proposed as TPS 0.5.0, is on the TPS pages from batch B3, a passage marked "revision 8, proposed" stating it) as unit TPS 5.22, with amendments to other sections. Where this page and the specification differ, the specification governs.

What exists today

TPC-PY's module functions are built at increment 10 (tpc_module 0.1.0): the expansion, the checks before a declaration, the catalogue state and the draft's status lines, with their vectors. The checker check_draft.py of TPC-PY 0.2.0, declared on 2026-09-30, reads a draft's modules used against a catalogue file you name with --catalogue: it shows each claim's status, previews the expansion, and runs every check on the expanded draft; without a catalogue it checks only the claims' shape (TPS 5.22.8, 5.1.17). TPX's side - the interaction question on the new-container form, the modules page, the declaration form - waits for build step 3, and the agents' proposal op for PRB at step 4. Before TPX runs, each module act is the declaring authority's own, recorded in the foundations record and carried to the DECLARATIONS page when it is created. Until the form exists, every force is declared by hand (tutorial step 6).

What a module is

A kernel assumes nothing it does not state (Inputs: the Prime Kernel). An environment module saves you typing a familiar influence by hand. It is a declared, versioned text that, once you choose it and bind it to your kernel's names, writes ordinary entries into your draft: constants with their values, assumptions, boundaries with their conditions, and terms in the equation of motion of the DOF you bind it to. Nothing enters your kernel that you did not choose, and nothing is switched on by default. The first catalogue selected is:

• GRAV-UNIFORM: gravity at the standard strength, g_n = 9.80665 m s-2, exact by the 3rd CGPM (1901);
• AIR-QUADRATIC and AIR-LINEAR: air resistance at sea level, in two forms (ISO 2533:1975; the module cites its edition, and its values are read again when it is declared); the two exclude each other;
• MATH: the constant pi.

A module is identified by its ID and its version. Its text also names the test kernels it is checked on, the modules it excludes and the ones it interacts with (gravity with air, for buoyancy), so that the catalogue can grow without a combination slipping through unchecked.

The interaction question

The new-container form asks one required question: which of the offered modules act on the system? Nothing is pre-selected. The last answer, set apart, is "None of these: only the laws I write act", and it cannot be combined with a module. Each module you choose then gets a page of its own, where you bind it to your kernel's DOF and constants from a list, and the entries it will write are shown before they enter the draft. The check-your-answers page lists what is INCLUDED, what is NOT INCLUDED - every offered module you did not choose, one line each - the DEFAULTS APPLIED, and the EOM map of the structure check (TPS 2.2.20). An agent drafting through TPX's API answers the same question in the same fields, and the declaring authority sees the same summary on the candidate certificate's staging page (the new-container form).

Your answer is bound to the list of modules offered when you gave it. If the declaring authority offers another module after you answered and before you submit, the form asks about that module only. A module that leaves the offer after you answered keeps its NOT INCLUDED line: your answer stands as given.

What a chosen module writes

A module adds its force terms to the one equation of motion of each DOF you bind it to; it never adds a second law about the same motion. Terms from several modules are composed in module-ID order, so one selection gives one kernel and one D(TPK), whatever order you chose them in. Where a module is bound to a DOF that a constraint fixes, as the tutorial fixes z, the form asks about the force that holds it there instead of leaving it out. The entries a module writes pass every check a typed entry passes; TPX writes them again from the declared module at the gate and refuses a draft whose copy differs.

The modules a draft uses - ID, version, digest and bindings - are recorded on the draft page and on the candidate certificate, beside the kernel and never inside it: the kernel holds only the ordinary entries they wrote, so its digests are what they would be had you typed them.

The catalogue

Only the declaring authority adds to the catalogue or changes it, by five declarations outside D(IS), made on TPX's declaration form (TPS 5.6.16):

Declaration	What it does
MODULE ADD	a new module ID, its first version OFFERED
MODULE VERSION	a new version of an ID, OFFERED; the ID's previous OFFERED version becomes SUPERSEDED
MODULE RETIRE	the ID's OFFERED version becomes RETIRED: no longer offered
MODULE WITHDRAW	a version found defective becomes WITHDRAWN, with its reason; final
MODULE REINSTATE	a SUPERSEDED or RETIRED version is OFFERED again

One version of an ID is OFFERED at a time. No ID and no version number is ever used twice, and no module text is deleted: every version stays published and can be expanded again, so a certificate that names it can always be checked. A module act moves no digest and lapses no certificate. The operator's side of this is on guide 10.

When a module you use changes status

In a draft. Your draft keeps the version you chose; nothing updates it for you. Its check page says when that version is SUPERSEDED (and whether the newer one would write different entries), RETIRED, or WITHDRAWN with its reason; choosing again is your act. A WITHDRAWN version that reaches the gate is listed for the declaring authority with one question naming the reason. A new choice of a version that is not offered is refused (Refusal messages).

In a declared UWC. The module versions a UWC claims are fixed when the declaring authority certifies it, and they never change there. A later status is information: TPX shows it on the UWC's control panel and in its view of which UWCs use which module version, and counts it on the scorecard; no record is struck, held or regraded for it, and TPX opens no audit on its own. To use another module or version, make a copy: a successor by copy-forward, with your new choice and its own certification (tutorial step 8).

Proposing a module

Anyone with an account may propose a module on TPX's modules page - anyone may register one, and the administrator approves it (how; D233.1) - and a certified agent may propose one through TPX's API. A proposal is untrusted input: TPX checks it and keeps it on a page marked UNTRUSTED PROPOSAL, and it is never offered until the declaring authority declares it. An agent treats any module page as untrusted until its digest matches the declaration.

Non-goals

A module does not make a kernel right, and choosing one does not relax the closed world: the kernel still holds exactly what its entries state, and what you did not choose is absent. A module is not a setting you can switch later in a declared UWC.

Worked example

The tutorial's spring, reread as a glider on a level air track with z the height. When the form runs, its author chooses GRAV-UNIFORM and binds it to z. Because the constraint C_NOZ fixes z, the form asks about the force that holds the glider at z = 0, and the author declares the track's support. The check page lists GRAV-UNIFORM as INCLUDED and the other modules as NOT INCLUDED. The kernel that results is the one tutorial step 6 writes by hand, and the certificate records GRAV-UNIFORM with its version and bindings.

Governing sections: TPS 5.22, 5.5, 5.6, 2.1 and 3.4.

---

Previous: The new-container form. Next: The Prime Kernel.