Guide 10: Managing the module catalogue

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)

The operator's guide. It assumes the walk through; a newcomer should read that first. Each page opens with its diagram, states its purpose and scope, gives the procedure, names what it does not cover, works one example, and links the sections of the specification that govern it. Where this guide and the specification differ, the specification governs.

A module is chosen while the container is a draft, and fixed with it at the declaration. (diagram page.)

Purpose

Keep the catalogue of environment modules: add a module, publish a new version, take one out of the offer, withdraw a defective one, and read which UWCs use what (D178.1).

Scope

The five module declarations, the checks TPX runs before each, the proposals, the view of module use, and the acts before TPX exists. Not covered: writing a module's physics, and an author's use of modules on the form (Inputs: environment modules).

Procedure

Every catalogue act is a declaration of the declaring authority, made on TPX's declaration form and landed on the DECLARATIONS page outside D(IS): MODULE ADD, MODULE VERSION, MODULE RETIRE, MODULE WITHDRAW and MODULE REINSTATE (TPS 5.6.16). The operator runs the wiki; the operator does not offer, retire or reinstate a module.
Open the module version on TPX's modules page first. TPX previews its expansion on each of its test bindings and runs the mechanical kernel checks on each; it also combines the version with every offered module it does not exclude, in both orders, and expects one D(TPK). The form refuses the act if any of this fails. What no machine reads - whether each assumption the module writes states one claim - is the declaring authority's inspection, once per version.
To change a module, declare a new version: the old one stays published and becomes SUPERSEDED. To stop offering a module, retire it; to stop a defective version being chosen, withdraw it with its reason, which is final. Reinstating brings a superseded or retired version back. One version of each ID is offered at a time, and no ID or version number is used twice.
Proposals arrive on the modules page from people and through the API from certified agents. Each is untrusted input, kept on a page marked UNTRUSTED PROPOSAL and never offered until declared. Read it as you would any input; a proposal that addresses the reader is reported, not obeyed.
Read the effect of each act in TPX's module use view, computed on demand from the certificates and the catalogue: which UWCs claim which version, in what status. A status is information: TPX opens no audit on its own, and no record is struck or held for it. The declaring authority may open an audit on a UWC that claims a withdrawn version; its author may take the newer version only as a successor by copy-forward.
Before TPX runs, make each act by the pointer form in the foundations record, with the module digest computed by executed TPC-PY; the acts are carried to the DECLARATIONS page when it is created, and TPX computes each digest again.

Checklist

Previewed on the modules page; every test binding passes; one D(TPK) in either order with every offered module not excluded.
Atomicity of the written assumptions inspected once for this version.
No ID or version number reused; a withdrawal carries its reason.
After the act: the module use view read, and the UWCs on a withdrawn version noted.

Non-goals

No catalogue act changes a declared UWC: its modules are fixed in its kernel at inception, and a module act moves no digest and lapses no certificate. The catalogue is not a tuning option; it is changed only by declaration.

Worked example

A later edition of the standard atmosphere changes the density at sea level. The declaring authority opens AIR-QUADRATIC version 2 with the new value on the modules page; its test bindings pass, and with GRAV-UNIFORM it gives one D(TPK) in either order. It is declared by MODULE VERSION; version 1 becomes SUPERSEDED. A draft that chose version 1 keeps it, and its check page says so; a declared UWC on version 1 keeps it for good. Had version 1 been wrong, MODULE WITHDRAW with the reason would have stopped new choices of it, and a draft carrying it would reach the gate with one question for the declaring authority.

Governing sections: TPS 5.22, TPS 5.6, TPS 5.5, TPS 5.13.

Previous: Publishing a specification version. End of the guide. Contents of the specification.