Principles

NumericalOS is developed under a stated set of commitments, drawn from Catholic social teaching. Each one that can be enforced by a test is enforced by a test. A principle that nothing checks is decoration.

1. Truthfulness

CCC 2469 — "Men could not live with one another if there were not mutual confidence that they were being truthful to one another." The virtue of truth gives another his just due.

Software that runs as PID 1 asks for a great deal of trust, and the only thing that makes that trust reasonable is an accurate account of what has and has not been established. This commitment predates its articulation here.

• The status line reads "bootstrap logic tested; x86_64 QEMU self-init PASS (degraded=0) on kernel+initrd and hybrid ISO/GRUB serial; fleet bare-QEMU PASS-degraded; metal and non-x86_64 unverified." Dual-claim shape: what is proven, what is not. It is not softened into an unscoped “it boots” claim.
• Only numericalos-verify-boot may claim a boot, and only for the one artifact on the one architecture it observed. A prior QEMU observation does not license the next build.
• The status page enumerates every known residual, including the unflattering ones. Understating a limitation is the same class of defect as overstating a capability.

Enforced: the scoped status line must be present in both the README and the published status page, and no source file may claim unscoped boot victory across all arches or on bare metal.

2. Respect for the person, including privacy

CCC 1907 — the common good "presupposes respect for the person as such", including the right "to safeguard . . . privacy".

The owner of a machine is not this project's data source. A boot fetches what it needs to boot and nothing else.

• No telemetry. No beacon, no identity ping, no usage report, no phone-home on failure.
• Every outbound request goes through one function, numos_fetch, so there is exactly one place to audit.
• Requests carry no query parameters and the boot path issues no POST.
• The base URL is a parameter. Point a machine at your own mirror, or at nothing.

Enforced: a real boot runs against a recording HTTP server, and the exact set of requested paths is asserted — along with the absence of query strings, of POSTs, and of any network tool used outside numos_fetch.

The topology join, and why it is not a beacon

The join contract sends a capability document to a coordinator — an outbound signal. The distinction has to be principled rather than convenient: telemetry is the project harvesting from the operator's machine; a join is the operator's machine reporting to the operator's own coordinator. The principle protects the person from the project; it does not put a machine beyond the reach of its owner.

1. Off by default. No NUMOS_COORDINATOR means no network contact, ever. The capability is still written to disk, so the node stays observable without anything leaving it.
2. Never to this project. The destination is whatever the operator named. numericalos.com is not a fallback.
3. Inspectable before sending. The exact bytes land in $NUMOS_RUNDIR/capability first.
4. Refusal is a state, not an error.

Enforced: the join runs with a live coordinator listening and NUMOS_COORDINATOR unset, and the coordinator must receive nothing; a second test asserts the bytes sent are byte-identical to the file written first.

3. Subsidiarity

CCC 1883 — "a community of a higher order should not interfere in the internal life of a community of a lower order, depriving the latter of its functions, but rather should support it in case of need and help to co-ordinate its activity with the activities of the rest of society, always with a view to the common good."

This is not an overlay on the architecture — it describes the architecture that was already there, and explains why several decisions went the way they did.

• A machine boots with no network, always. A verified on-disk artifact is used without contacting anything.
• Remediation is local first. A health predicate's local_action runs with no network at all.
• Escalation is help, not dependency. An on_fire reference is queued and drained later; nothing about a tick waits on reachability.
• A degraded node stays in the fleet and says so, rather than dropping out or pretending to be healthy.
• The curl | sh installer does not replace PID 1, even when asked.

Enforced: a node with an unreachable base must still fire its health predicate, still apply local remediation, and still persist the escalation rather than dropping it.

4. The common good, and what we publish

CCC 1906 — the common good is "the sum total of social conditions which allow people, either as groups or as individuals, to reach their fulfillment more fully and more easily."

The project ships knowledge and reproducible build paths rather than a default “download the OS ISO” product. The skills drive a build on your own machine (or via Cloudflare Sandbox + R2 when you have no local Linux/WSL), from a repository you can clone and read first. Artifacts produced that way remain under your control and your hash checks.

Enforced: no build output and no tooling cache may be tracked. Both failed once — 917 files of generated site output were committed and republished before the ignore rule was found too narrow, and a wrangler cache carrying an account id and an email-derived account name was published before it was caught. The tests exist because of those, not in anticipation of them.

5. Stewardship

The machine belongs to its operator, and its resources are not ours to waste. Restart backoff doubles to a ceiling so a crash-looping unit is throttled — a real defect once, since the shipped defaults truncated to sleep 0 and throttled nothing. The bootstrap is zero-compile-first so old and slow hardware is not excluded by a toolchain requirement.

resource_envelope fields are enforced or refused on the shell floor:

Unset fields use -. Declaring an unenforceable limit is a named halt, not a silent no-op.

6. The universal destination of goods

CCC 2452 — "The goods of creation are destined for the entire human race. the right to private property does not abolish the universal destination of goods."

This project publishes source rather than binaries and argues for that on common-good grounds. That argument does not survive publishing source under no grant. Until a licence is chosen, a clone of this repository gives its recipient no legal right to copy, modify or redistribute it — readable but not usable, which is the withholding the principle names, one layer down from where the project was looking.

Found by audit, not volunteered: no LICENSE, no copyright statement, no SPDX identifier anywhere — while the site invited people to clone and shipped skills telling them to build and run the result.

Resolved. The project is licensed MIT (SPDX-License-Identifier: MIT). A clone now grants what the common-good argument above assumes: use, copy, modify, merge, publish, distribute, sublicense.

The choice was surfaced rather than defaulted — selecting a licence is a grant of the owner's property made in the owner's name, so the options went to the owner and MIT was chosen. Recording that it was a decision rather than an inference is part of the point: the gap existed precisely because nobody had ever decided.

The grant travels with the thing granted. LICENSE and NOTICE are published, index.json advertises the licence, every footer links it, and the files that end up inside somebody's initramfs — where the repository's LICENSE does not follow — carry an SPDX identifier in their own header.

Enforced: the licence must exist and actually grant each right it claims, and every redistributed file must carry an SPDX identifier.

7. Solidarity

CCC 1939 — "The principle of solidarity, also articulated in terms of 'friendship' or 'social charity,' is a direct demand of human and Christian brotherhood."

Solidarity governs what this project owes to commons it draws from — a different question from what it grants to others. The two were being confused.

The concrete case: busybox. The build skills fetch busybox and bundle it into an initramfs or container image. busybox is GPLv2, and handing that image to anyone is redistribution carrying obligations — licence text, corresponding source or a written offer, notices intact — about which the skills said nothing. The project was taking from a commons and returning nothing. Unlike the licence question this is not the owner's choice to make: it is an obligation to other people's work, so it was discharged rather than surfaced.

And it makes one finding worse. The architecture registry lists s390x, mips64el, loongarch64 and armv6 — and busybox.net publishes prebuilt binaries for i686 and x86_64 only. The architectures likeliest to belong to older or cheaper hardware were exactly the ones with no working build path, while a code comment asserted the fallback kept "all chip infrastructures" honest. That is a truthfulness failure compounding a stewardship one, not a new principle: an untested feature is silent, and this one made a claim. Corrected in both places.

Principles deliberately not claimed

Asserting completeness "according to the Magisterium" while silently omitting principles would claim something unearned; stretching every principle onto a shell script would be worse. So the omissions are named: the preferential option for the poor gets no section of its own, because stewardship and solidarity already carry that ground concretely and a second citation restating the first in more devotional language is the decoration this page opens by forbidding; the dignity of work and the rights of workers have no referent, since this is a userspace init and not an employer; teaching on sexual ethics, just war and the sacraments has no referent and is not invoked.

Declining these is not modesty. A principle with nothing to govern cannot be enforced by a test, and an unenforced principle here is exactly what the opening line says this page must not contain.

On applying these

These principles constrain design decisions. They are not a claim that the resulting software is virtuous, nor that disagreement with them is wrong. Where a principle and a convenience have conflicted so far — offline-first over a simpler always-fetch, no telemetry over easier debugging, publishing residuals over a cleaner-looking status page — the principle has won, and the tests are what keep that from quietly reversing.