ernster.dev

Engineering Principles

The same few rules recur across the applications on this site. They are not a house style; each one is written into the code that ships.

A promise the architecture can break is only a sentence.

Every example below is held by a test, a code boundary or a statement in the project's own documentation, read from the repository rather than from the marketing and checked against it again after a full audit of every application. Each says what its guard covers and no more. Where the practice still falls short of the principle, the last section says so.

A claim is a structure, not a sentence

"Read only" is not true because the README says it. A promise about what software will never do belongs in a test that fails the build the moment the promise is broken.

  • PlainSight reads the syntax tree of every module in its package against an allowlist. Three named modules may write a file and two more hold one narrow grant each; any other write, process launch or dynamic import fails the build.
  • Stellody fails the build if a module that imports a tag library calls by name a method that saves, deletes or adds tags; only named modules that own Stellody's own records may write to disk by the forms the guard recognises.
  • SymDiary fails the build if any Go file in the repository, setup program included, imports Go's network packages; a second test requires the page to declare a content policy that forbids connections.
  • Postal Gambit fails the build if anything it installs, setup program included, imports a listed network library or one of the indirect routes to one; a single named module is granted the update check and nothing else.

Outbound traffic fits on a page

If an application calls itself local-first, everything it sends off the machine should be listable: each host, each purpose, ideally each field.

  • EarthNow gives each of its five sources an HTTP client that admits that source's host alone over https, on the first request and on every redirect. A test fails a client that admits two; the README names all five.
  • Stellody lets four named modules hold network machinery, one of them a local channel that never leaves the machine. Tests pin every address and field a discovery run sends and check that none names the listener or the machine.
  • TimeRibbon lets one package import Go's network packages: the update check. Further tests hold every program it starts and every Windows library it loads to named lists and forbid the page a request of its own.
  • Postal Gambit makes exactly one outbound call, disclosed in full in its README; your own mail client carries the games.
  • PigeonPost lets seven packages open a connection: IMAP, POP3, SMTP, CalDAV, Microsoft sign-in, the images you choose to load and the update check. A test fails any other package that imports a listed network root; another fails a page script that makes a request of its own.
  • ClearBudget and Decitect each open one connection themselves, the update check. A test fails any module of the application, its setup program or its entry point that imports a listed networking module; a second holds the update check to one standard library call.
  • Meridian names six ways out and pins five of them to one home each: the feed fetcher, which also carries Feedly's search, the update check, the one component that asks Wikipedia for suggestions and the one that draws YouTube's player. Its parsers hold the images a feed points at to https.

Leaving is always possible

Standard formats, local files and data that stays with its provider. Nothing here should be harder to leave than it was to start.

  • PigeonPost removes mail from your provider's server only when you delete it or a rule you wrote does so; syncing only reads. Events travel as ICS and contacts as vCard or CSV, each format with a test that writes a record, reads it back and compares the fields.
  • SymDiary exports its record as versioned JSON and imports it again; a test fails unless every format version it has written has a reader and a frozen sample that still reads back.
  • ClearBudget backs up every account and every budget to one file. A damaged or truncated backup is refused before any live file changes; a restore that fails part way puts the originals back.
  • Decitect exports a plan as JSON that a test reads back with the same organisation and moves; it also writes the report as one HTML file with nothing fetched from elsewhere.

Failure is visible; partial success is reported as partial

Software that hides a failure moves the cost to the moment you discover it. Saying what did not happen is part of the job.

  • AudioDeck names each device a profile switch could not set and why, in the window and on the command line's error stream.
  • ScreenState lists every application in a profile after a restore as satisfied or not with the reason, naming any application whose state it could not read.
  • EarthNow keeps the other days of its burnt-area map drawn when one day fails to arrive; the status panel names each failed day with the error and when it will try again.
  • PigeonPost reports a partly refused move as an error naming how many messages the server accepted, keeps those moved and counts only the rest as failed.
  • Stellody names each artist a discovery run could not answer for by the reason it went unanswered; a stopped scan says it stopped and the next launch says the last scan did not finish.
  • Meridian ends every import with a report naming what was added, what you already had and each refused feed with its reason, up to ten named and the rest counted.

Automation removes work, not agency

The software does the counting and proposes; a person decides. Nothing destructive happens behind a default.

  • PigeonPost counts what a rule would change before applying it to mail you already have; the run refuses without that preview and touches only the messages it counted. Importing rules lists what would be added, replaced or disabled and saves nothing.
  • ScreenState holds a capture in memory until you confirm it. Apply only minimises windows the profile does not name and never asks one to close, whatever the settings say.
  • Stellody never writes a tag to your music. It describes each damaged tag, lets you lay a correction over it in its own records and leaves the lasting repair to a tagger you choose.
  • NarrateX opens its remove-book confirmation on Cancel; declining removes nothing.

Damaged data is kept aside, never saved over

A file the application cannot read is still somebody's data. It is moved to a name of its own before anything is written; a second damaged file never replaces the first copy.

  • Stellody moves a library database that will not open aside with its log files, starts a fresh one and tells you what the old one held.
  • TimeRibbon keeps an unreadable settings file under the first free name and refuses every save for the rest of the run if it cannot.
  • NarrateX moves a damaged bookmark or preferences file aside before any save and names it when the book opens; a file it cannot read is never written over.
  • FancyClock copies a damaged alarms file aside before the first save and names the copy in its warning.
  • Decitect keeps an autosave that will not load and seals the store if it cannot move it, so a later save never lands on the original.
  • ClearBudget moves stray budget files to a quarantine folder of their own rather than adopting or deleting them.

Same input, same answer

A number someone will act on should come out the same the second time. Randomness is seeded, time is injected and the output is pinned.

  • Decitect lets its model layer import only an allowlist of pure standard-library modules, so randomness and the clock are refused by default; a structural test fails if either appears.
  • Simquence runs a hundred seeded simulations twice and requires them to match; a golden snapshot pins the first five runs to the last digit.
  • MMSP deploys its specification only after the conformance suite passes; pull requests run the same suite. The 300-second poll floor is pinned by a test; Meridian raises any shorter interval to it.

A guard is proved by planting the breach it forbids

A test that has never been seen to fail proves nothing. Each structural rule ships with a test that writes the forbidden line into a scratch file and fails if the rule stays quiet.

  • Decitect plants sixteen escapes into its model layer, from opening a file to importing the user interface; each must be caught. Sister tests do the same for the application, interface and network rules.
  • Simquence plants eight escapes past its pure core, among them a dynamic import, a process launch and a raw file open; its allowlist must catch every one.
  • Postal Gambit plants indirect routes to the network, such as Qt's networking classes, asynchronous sockets and an import spelled at run time; its scan must flag each while passing the local sockets it does use.

Say what it does not do

The most useful line in a README is often the one a reader would otherwise have assumed.

Where the practice is behind the principle

Measured against the repositories as they stand, these gaps remain.