5.22 Environment modules (TPS 0.5.0)
Instruction artifact, machine-optimized text: TPS, section 5.22 Environment modules. Part of TPS and the TPM hub. Human-only edit (TPS 5.13). TPS 0.1.0 was declared final at revision 4 on 2026-09-22, a version declaration recorded in the foundations record; the chain begins at TPX's first landing (TPS 5.6.7). TPS 0.1.1, which changed only the status lines, was declared final on 2026-09-26, TPS 0.3.0, revision 6, on 2026-09-28, and TPS 0.4.0, revision 7, on 2026-09-30. This page is revision 8 of the tree, proposed as version 0.5.0 until H-DECL declares it; revision 7 is carried whole, and revision 5, proposed as 0.2.0, stays undeclared; the section is new at revision 6. The text below is this section of the TPS artifact at 0.5.0 (proposed), verbatim; the whole artifact and its file digest are on The Principia Machina/TPS. Human readers: the contents page is the map.
TPS 5.22 ENVIRONMENT MODULES
purpose: the ENVIRONMENT MODULE and its text; TEST BINDINGS, EXCLUDES
and INTERACTS-WITH; the interview, the answer bound to the
catalogue and the check page; expansion and composition;
MODULES USED; the MODULE DECLARATIONS, the statuses and the
CATALOGUE STATE; the modules page and its checks; the pages;
proposals; a draft whose version changes status; fixed at
inception; the MODULE USE VIEW; the first catalogue; before
TPX; the functions
governs: 5.22 | version: 0.5.0 (proposed) | class: instruction artifact
audience: operator, agent
5.22.1 THE ENVIRONMENT MODULE (D178.1 (b), (f); S5). An ENVIRONMENT
MODULE is a declared, versioned text from which TPX writes
ordinary entries into a draft's TPK at its author's choice: a
CONSTANT for each of its parameters, ASSUMPTION and BOUNDARY
entries, and force terms composed into laws the TPK already has
(5.22.7). It exists only by H-DECL's MODULE DECLARATIONS
(5.22.9). It writes into the TFK only, never into the register,
and within it into the TPK only: no LAW, DOF, TrM or TMS entry.
Nothing it writes names an ENVIRONMENT MODULE or a version, so a
TPK typed by hand to the same entries digests alike (2.5.15), and
its use is recorded outside the TFK as MODULES USED (5.22.8). The
closed world stands: an interaction acts only where an entry
states it, whoever wrote the entry (2.2.19). Bare "module" is not
used for it in rule text. [D178.1] [S5]
5.22.2 THE TEXT (D178.1; S6). An ENVIRONMENT MODULE's text is one JSON
object read by a strict reader (RFC 8259), every field present
and an unknown field refused (2.2.11): ID, capitals, digits and
hyphens; VERSION, three integers compared as such; TITLE, the
interview's label; SOURCE, the standard and edition its declared
values come from, a new edition being a new VERSION (S6);
PREREQUISITES, the slots it binds, each of KIND DOF or CONSTANT
with a DIMENSION and a count of names; PARAMETERS, each written
into the TPK as a CONSTANT, DECLARED with VALUE, UNIT and
OVERRIDABLE, or AUTHOR, with a DIMENSION and no value; SUMS, a
sum over a slot's names; TERMS, each a TARGET slot, a SIGN, an
expression in the grammar of 2.2.13 without D and a LABEL;
ASSUMPTIONS, one claim each; BOUNDARIES, each with a CONDITION;
NOT_CHOSEN and NOT_INCLUDED, the lines the check page shows; and
EXCLUDES, INTERACTS_WITH and TEST_BINDINGS (5.22.3). Every string
passes the text safety rule (2.5.13), and a refusal quotes safely
(2.5.14). The text's digest is TPC module_digest's: digest_fields
(2.5.10) over ["TPC-MODULE", "1", the canonical text], on the
pattern of a BIBLIOGRAPHY ENTRY's canonical serialization
(5.21.5): the value the strict reader gives, strings in NFC, the
fields of the text's schema in their fixed order and every other
object's members in code point order of their keys, lists in
their order, no white space outside strings, integers in decimal,
each string escaped only for the quotation mark, the backslash
and control characters. Every string enters verbatim, so white
space outside strings, key order and NFC give one digest, while a
DIMENSION, a decimal, a UNIT or an expression spelled otherwise,
or the same text at another VERSION, gives another: the digest is
of the text H-DECL declares, byte for byte after the reader. A
change of the zone serialization, the form grammar or the unit
spellings moves no declared digest; a change of the canonical
text or of the schema's fields is a new digest form, made only by
an item that states how the digests of form "1" carry over.
[D178.1] [S6] [S49]
5.22.3 TEST BINDINGS, EXCLUDES AND INTERACTS-WITH (D178.1 (g)). An open
catalogue cannot hard-code which ENVIRONMENT MODULES combine, so
each declares it inside its digest. TEST BINDINGS: one to eight
fixture drafts, each a TPK with the slots' names, the values and
the answers, on which the checks of 5.22.11 expand it; two
ENVIRONMENT MODULES share a TEST BINDING when each has one of the
same name over one D(TPK). EXCLUDES: the IDs, or ID patterns such
as AIR-*, it is never combined with; a pair is refused when
either one's EXCLUDES matches the other, as AIR-QUADRATIC
EXCLUDES AIR-LINEAR, since two drag laws summed into one equation
would pass every mechanical check. INTERACTS-WITH: a question
raised when an ENVIRONMENT MODULE matching it is also chosen,
answered YES or NO in the interview, as GRAV-UNIFORM's buoyancy
question with AIR-*; the answer selects the line the check page
shows and changes no expansion. [D178.1]
5.22.4 THE INTERVIEW (D178.1 (a); S12). Every draft carries an answer to
one required question, "Which of these interactions act on the
system you are modelling?", which lists the OFFERED ENVIRONMENT
MODULES by TITLE in ID order, none pre-selected, and last, set
apart by "or", the exclusive answer "None of these: only the laws
I write act" (NONE). TPX refuses a draft with no answer,
"INTERACTIONS: not answered", and NONE together with any
ENVIRONMENT MODULE. For each one chosen, a page per binding
follows: every slot bound to existing names of its KIND and
DIMENSION, chosen from a list, never typed; every AUTHOR
parameter given a VALUE and UNIT or left symbolic, never
pre-filled; a DECLARED value changed only where OVERRIDABLE, with
VALUE and UNIT; every question raised answered YES or NO, never
defaulted: each INTERACTS-WITH question and, where a term targets
a DOF a FIX CONSTRAINT targets, whether a constraint force
balances the forces the ENVIRONMENT MODULE adds along it. NO is
refused, since a force along a fixed DOF that nothing balances
contradicts the constraint; YES drops the term there and writes
one ASSUMPTION that a constraint force balances it. The DRAFT UWC
API takes the same answer, bindings and question answers in the
same shape, with no default where the form has none, and TPX
checks them alike. The answer and the bindings lie outside the
TFK and enter no digest (5.22.8). [D178.1] [S12]
5.22.5 THE ANSWER AND THE CATALOGUE (D178.1 (a), (g)). The answer is
bound to the CATALOGUE STATE it was given over: TPX records with
each round of it the number of MODULE DECLARATION lines then in
force and the OFFER it covered, from its own state, never from a
client. When the OFFER gains an ENVIRONMENT MODULE after the
answer, TPX asks about the added ones only, on the form and in
the DRAFT UWC API alike (the delta question), and runs no final
pass until the answer covers the OFFER in force. An ENVIRONMENT
MODULE that leaves the OFFER after the answer keeps its NOT
INCLUDED line: the answer stands as given. A claim is admitted
PINNED when its version was OFFERED in the round that chose it,
or CARRIED when COPY-FORWARD brought it from the source
certificate (3.4.10); a new claim of a version not OFFERED is
refused, as are a claim the answer did not choose and a pair
either of which EXCLUDES the other (TPC interview_check). TPX
runs interview_check at the gate over the answer it recorded, the
draft's claims, the declared texts, the carried claims and the
IDs marked MODIFIED (5.22.7), before the final pass starts and
again within it, before the re-expansion (5.22.8), whichever path
made the draft: a draft with no answer, with a new claim of a
version not OFFERED or with an answer that does not cover the
OFFER in force goes no further. A PINNED claim keeps its version
whatever its status becomes (5.22.14). [D178.1] [S48]
5.22.6 THE CHECK PAGE (D178.1 (a); S12, S21, S26). TPX renders the
draft's check page from the stored draft, never from client
state: the closed-world statement of 2.2.19, verbatim; the EOM
MAP, the findings and the class under either value of
STRUCTURE_CHECK (5.5.12); INCLUDED, each chosen ENVIRONMENT
MODULE with its ID, VERSION and every parameter's value, unit and
source, "declared" or "you entered", and each term the author
wrote, marked "written by you"; NOT INCLUDED, the NOT_CHOSEN line
of each covered ENVIRONMENT MODULE not chosen, each chosen one's
NOT_INCLUDED lines, the line of each ENVIRONMENT MODULE marked
MODIFIED (5.22.7), each chosen one's INTERACTS-WITH lines, and
the closing line "Any interaction not listed under INCLUDED is
absent from this kernel." (TPC not_included_lines); DEFAULTS
APPLIED, each value no choice of the author set, marked
"(default, not chosen)"; the inspections owed to H-DECL; and each
claim's status (5.22.14). The page ends with one question,
neither answer pre-selected: "This kernel asserts only the
interactions under INCLUDED. For the system you mean, is every
other interaction absent?"; No returns to the interview's
question. The DRAFT UWC API returns the same summary as data,
H-DECL's staging page shows it whichever path made the draft, and
H-DECL's declaration form asks the same question once per UWC,
the answer on the declaration line. [D178.1] [S12] [S21] [S26]
[S50]
5.22.7 EXPANSION AND COMPOSITION (D178.1 (d)). TPX expands with TPC
(module_bind, module_expand), never an agent or a client. Each
term goes into the one law the EOM MAP names as the equation of
motion of the bound DOF, which carries ROLE EOM(<DOF>) and has
exactly one side of the equation-of-motion shape: the DOF's
equation of motion is the author's, written first, and an
ENVIRONMENT MODULE adds terms to its other side and never writes
a law. A term aimed at a DOF with no equation of motion, a DOF a
REMOVE constraint targets, an INPUT DOF or a D VARIABLE is
refused. Terms are composed in ID order, then term order, then
name order, whatever the order of selection, so one selection
gives one EQUATION and one D(TPK); the composed EQUATION passes
the bounds of 2.2.13; the law keeps its NAME and ROLE, and its
STATEMENT gains, per term, "; with <LABEL>: <term>", naming no
ENVIRONMENT MODULE. An entry two ENVIRONMENT MODULES write
identically is written once; written differently, or named as an
entry of the author's own, it is refused. An AUTHOR parameter two
of them both leave symbolic under one name is one CONSTANT: the
check before a declaration refuses the pair when the two
DIMENSIONs differ and puts the SHARED PARAMETER question to
H-DECL when they are equal (5.22.11). The form shows each entry
before it enters the draft, marked "from <ID> <VERSION>", an
overridden value beside the declared one. An entry the author
edits by hand makes that ENVIRONMENT MODULE's entries the
author's: TPX moves them into the author's own entries, shows
them "modified from <ID> <VERSION>", drops the claim and marks
the ID and VERSION MODIFIED; the answer keeps the ID chosen,
interview_check admits it as MODIFIED, the check page carries
"Modified from <ID> <VERSION>: its entries are the author's own."
(5.22.6), and the re-expansion checks the remaining claims
(5.22.8). The expansion runs no kernel test: the zone checks and
the gate read the expanded TPK as any other (5.5.2). [D178.1]
[S50] [S51]
5.22.8 MODULES USED AND RE-EXPANSION (D178.1 (c)). MODULES USED records,
per claim, the ID, VERSION, digest, bindings, values and answers,
on the DRAFT UWC page and on the candidate certificate, never in
the TFK, so it enters no digest and a TPK typed by hand to the
same entries digests alike (2.5.15). TPX keeps the author's own
entries apart from the expansion. At the final pass it re-expands
every claim from the declared text, whatever its version's
status, and refuses a draft whose TPK differs from that expansion
of the author's own entries, including one submitted through the
API with an expansion already written (TPC module_verify,
MISMATCH). A certificate lands with its MODULES USED (5.6.16).
[D178.1]
5.22.9 THE MODULE DECLARATIONS (D178.1 (b), (g)). An ENVIRONMENT MODULE
exists only by H-DECL's MODULE DECLARATIONS on the DECLARATIONS
page, outside D(IS) (5.6.16): its text generates TFK content, so
the declaring authority holds it. The five acts are MODULE ADD,
MODULE VERSION, MODULE RETIRE, MODULE WITHDRAW and MODULE
REINSTATE (5.22.10). A declared version is never edited: a change
is a new VERSION, the old one kept. No text is deleted: every
declared version stays published on its page (5.22.12) and
re-expandable, whatever its status, so every claim of it can be
checked. An act moves no digest and lapses no certificate.
[D178.1]
5.22.10 THE STATUSES AND THE CATALOGUE STATE (D178.1 (g)). A declared
version is OFFERED, SUPERSEDED, RETIRED or WITHDRAWN (1.1). TPC
catalogue_state computes the CATALOGUE STATE from the MODULE
DECLARATIONS in chain order: MODULE ADD declares a new ID at its
first version, OFFERED; MODULE VERSION a new version of a
declared ID, greater than every version of it, OFFERED, the ID's
OFFERED version becoming SUPERSEDED in the same act; MODULE
RETIRE makes the ID's OFFERED version RETIRED, no version of the
ID then offered; MODULE WITHDRAW makes a version found defective
WITHDRAWN with its reason, final, and, when that version was
OFFERED, may name a SUPERSEDED or RETIRED version of the ID to
offer again; MODULE REINSTATE makes a SUPERSEDED or RETIRED
version OFFERED again, the ID's OFFERED version SUPERSEDED. At
most one version per ID is OFFERED; the OFFER is the OFFERED
versions in ID order with their digests, and a state digest names
it after every line. Refused: an ID, a version or a digest
declared again, so no ID or version is reissued, even after every
version of it is retired; MODULE VERSION of an ID never added;
MODULE RETIRE of a version not OFFERED; MODULE WITHDRAW without a
reason or of a WITHDRAWN version; MODULE REINSTATE of a WITHDRAWN
or an OFFERED version; a line dated earlier than the line before
it. The user's words map so: add is MODULE ADD; modify is MODULE
VERSION; delete is MODULE RETIRE, the content sound, or MODULE
WITHDRAW, the content defective. [D178.1]
5.22.11 THE MODULES PAGE AND THE CHECKS BEFORE A DECLARATION (D178.1
(g)). TPX's modules page, a special page (name VERIFY at build),
lists every declared version with its status, its history and the
number of certified UWCs claiming it, and shows each version's
expansion on each of its TEST BINDINGS as a preview. H-DECL's
declaration form accepts MODULE ADD or MODULE VERSION only after
TPC module_check passes on the text: the text parses; every
EXCLUDES and INTERACTS-WITH entry matches a declared ID; each
TEST BINDING, expanded, passes T1 with the names check, T2's
syntactic part, T5, T4's law half, T6's totality and T3 at depth
1, the mechanical checks of 5.5.2 over a TPK; and, with each
other ENVIRONMENT MODULE OFFERED after the act that neither
excludes, on each TEST BINDING the two share, the pair expands in
either order of selection to one D(TPK) that passes the same
checks. A pair that shares no TEST BINDING fails: no combination
passes untested. A pair that declares an AUTHOR parameter of one
name with two DIMENSIONs fails; one that declares it with one
DIMENSION raises a SHARED PARAMETER question, one per pair and
name: may the two be one quantity when an author leaves both
symbolic (5.22.7)? Like the atomicity question it is H-DECL's
INSPECTION, never a verdict of the check. H-DECL then answers the
atomicity question once per version, over the ASSUMPTIONS the
version writes (4.6.3), and each SHARED PARAMETER question, the
answers on its declaration line. MODULE RETIRE, MODULE WITHDRAW
and MODULE REINSTATE meet the refusals of 5.22.10 only. [D178.1]
[S51]
5.22.12 THE ENVIRONMENT MODULE PAGES (D178.1 (g)). Each declared version
has a TPX-written, world-readable, protected page, "The Principia
Machina/Environment module/<ID>/<VERSION>" (title VERIFY at
build), carrying its text, its digest and its status history; TPX
writes the text once and afterwards the status history alone, as
a status write. An agent treats the page as untrusted input until
its digest matches the declaration (AC-4.51). [D178.1]
5.22.13 PROPOSALS (D178.1 (g)). Any USER may propose an ENVIRONMENT
MODULE text on the modules page, and any agent-group account by
one op of action=tpx (name VERIFY at build), whose lane awaits
declaration (7.2.32). A proposal is untrusted input (6.2): TPX
runs module_parse, the text safety rule and module_check on it,
as for a declaration, and keeps it, whatever the result, on a
TPX-written, world-readable page marked UNTRUSTED PROPOSAL, with
PROPOSED BY and the checks' result. Nothing proposed is offered:
a proposal reaches a draft only when H-DECL declares its text by
MODULE ADD or MODULE VERSION; a proposal H-DECL declines is
marked DECLINED, with the reason, and kept. No agent writes a
proposal page. [D178.1]
5.22.14 A DRAFT WHOSE VERSION CHANGES STATUS (D178.1 (g)). A draft keeps
the version each claim names; nothing updates it but its author.
From the moment a claimed version's status changes, the check
page, the DRAFT UWC API and the staging page show it: SUPERSEDED,
with whether the OFFERED version's expansion on this draft is the
SAME or DIFFERS; RETIRED; WITHDRAWN with its date and reason (TPC
draft_module_status). Re-selection is the author's one act: a
later round of the interview naming the IDs re-selected
(RESELECT), each an ID an earlier round covered and still
offered, which re-offers each one's OFFERED version while every
other claim stays pinned to the round that chose it; TPX records
the round as any other and rebuilds the expansion from the
author's own entries and the new claims (5.22.5, 5.22.7). A draft
that reaches the final pass claiming a WITHDRAWN version is not
refused for it: TPX lists it on the staging page and on H-DECL's
declaration form with one question per such version, "This draft
uses <ID> <VERSION>, withdrawn on <date> for: <reason>. Declare
with it?", the answer on the declaration line. [D178.1] [S50]
5.22.15 FIXED AT INCEPTION (D178.1 (g), the user's words "fixed at
inception, must be copied to change settings"). The ENVIRONMENT
MODULE versions a UWC claims are fixed when H-DECL certifies it:
what they wrote stands in its TFK as ordinary entries, immutable
with the TFK (2.1.2), and the certificate's MODULES USED is never
rewritten (5.6.16). A later act on a version changes its status
only, never a TFK, a certificate or a record: a status is
information, and TPX strikes, holds and regrades no record and
opens no audit block for it; H-DECL may open one. The control
panel shows each claimed version's status (5.12.14) and the
scorecard counts the UWCs on WITHDRAWN versions (5.18.18); no
page of a UWC is written for a status change itself. A UWC takes
another ENVIRONMENT MODULE or version only as a copy: a successor
by COPY-FORWARD, whose draft keeps the source's claims until its
author re-selects and whose certification is its own (3.4.10,
5.5.6). An ENVIRONMENT MODULE itself changes only by a new
VERSION, the old one kept (5.22.9). [D178.1]
5.22.16 THE MODULE USE VIEW (D178.1 (g)). TPX's MODULE USE VIEW, a
special page computed on demand and stored nowhere, lists for
each declared version the certified UWCs whose MODULES USED claim
it, by prefix, with the version's status, sorted by ID, VERSION
and prefix in code point order, and the number of UWCs claiming a
WITHDRAWN version (TPC module_use_view). H-DECL reads it to
decide whether to open an audit block (5.22.15). [D178.1]
5.22.17 THE FIRST CATALOGUE (D178.1 (e); S6). Four ENVIRONMENT MODULES,
each declared by MODULE ADD once its values are re-read (S6),
their texts the fixtures of TPC's vectors (5.1.16): GRAV-UNIFORM,
the weight in a uniform field, g_n = 9.80665 m s-2, exact by the
definition of the 3rd CGPM (1901), with ASSUMPTIONS that the
field is uniform and that local g is taken as g_n, its region a
BOUNDARY, and the buoyancy question INTERACTS-WITH AIR-*;
AIR-QUADRATIC, quadratic drag at the sea-level values of ISO
2533:1975, rho 1.225 kg m-3 and mu 1.7894e-5 Pa s, the drag
coefficient and the reference area and length supplied by the
author and never defaulted, its Reynolds window a BOUNDARY
carrying the guards of 2.2.16, EXCLUDES AIR-LINEAR; AIR-LINEAR,
Stokes drag at the same values, the radius supplied by the
author; MATH, the dimensionless CONSTANT pi_c =
3.141592653589793, the grammar having no pi. The edition of ISO
2533 is VERIFY-HIGH until re-read. [D178.1] [S6]
5.22.18 BEFORE TPX (D178.1 (g)). Until the DECLARATIONS page exists,
each MODULE DECLARATION is H-DECL's own act in the foundations
record's pointer form, its digest from executed TPC-PY and
module_check's result recorded beside it; the lines are carried
to the page at its creation and recomputed by TPX (5.6.16);
nothing is declared by delegation. The interview, the modules
page, the pages and the view wait on TPX (build step 3); the
proposal op also on PRB (build step 4) and on its lane (7.2.32).
[D178.1]
5.22.19 THE FUNCTIONS (D178.1). The reading and the digest of a text,
the binding, the expansion and the re-expansion, the interview's
check and the NOT INCLUDED lines, the CATALOGUE STATE, the checks
before a declaration, a draft's statuses and the MODULE USE VIEW
are TPC functions in both residences with vectors, never an
agent's (5.1.16, 5.1.8); the declaration form's lines, the pages,
the interview's rounds and the panels are TPX's (5.3.48).
[D178.1]
Pages for this section, added by the second help pass: Inputs/Environment modules; Guide/10 Managing the module catalogue.