You're viewing the readable version of this site. The interactive extras (search, diagrams, read-aloud) need JavaScript and a current browser. Enable JavaScript; if it is already enabled, update your browser.

Learn · Interactive book

budding

Hidden Machines

From spaghetti to structure — finding the mathematics already inside your code.

software-design, discrete-math, refactoring, formal-methods, learn

The machinery was there before it had a name.

Working code can remain easy to break because its states, relationships, ownership, and laws are implicit. This book teaches a repeatable recovery: inventory what the program can do, find the contradictions, choose the smallest adequate formal object, separate the pure mechanism from effects, and preserve the observations that matter.

This is a budding first edition. Its dependency chain and structural claims are checked, but delayed reader validation is still pending. The chapters favor a complete compact argument over encyclopedic coverage.

The companion Retrieval Route schedules one-day, one-week, and one-month practice without accounts, streaks, or tracking.

Part I — Seeing the machinery

  1. Too Many Switches for One Light — Boolean flags, result types, and narrowed boundaries.
  2. Independent Lifecycles Need Independent State — state machines and product automata.
  3. A Refactor Must Say What Stays the Same — carriers, laws, observations, and equality domains.
  4. Run the Recovery Yourself — the structure-recovery procedure.

Part II — Programs that remember

  1. The Newest Messenger Holds the Seal — generation fences and stale-result rejection.
  2. A Lost Reply Is Not Permission to Repeat — idempotence, operation identity, and reconciliation.
  3. Await Stores the Rest of the Function — coroutines, suspension frames, and liveness.
  4. Every Child Needs an Owner — structured concurrency, capabilities, and error kernels.

Part III — Capacity

  1. Capacity Is Something You Can Spend — semaphores, bounded queues, and resource credit.

Part IV — Lifetimes

  1. Leave the Room, Clear the Table — regions, arenas, borrowing, and lifetime geometry.

Part V — Change without starting over

  1. A Change Is Something You Can Carry — deltas, event folds, checkpoints, and replay limits.
  2. Recompute Only the Dependency Cone — incremental invalidation and affected frontiers.
  3. Summaries Compose — monoids and measured structures.
  4. Different Arrival Orders Can Reach the Same State — partial orders and convergent merge.

Part VI — Navigating data and decisions

  1. A Cursor Carries Its Path — zippers and structural navigation.
  2. The Conversation Has a Grammar — scopes, typestate, and protocol automata.
  3. Let the Relationships Solve Together — constraints, decision diagrams, and bounded languages.
  4. Answers Can Carry Their Reasons — provenance semirings and proof objects.

Part VII — The geometry of interaction

  1. Every Number Needs a Unit and a Home — quantity types, affine frames, and region algebra.

Part VIII — Teaching tools to see

  1. The Smell Is Evidence — advisory structure recognition and a complete recovery.
  2. Leave the Tangle Standing — when recognition does not justify refactoring.

The recovery card

For any unfamiliar tangle, write down eight things before naming an abstraction:

  1. admissible states;
  2. events and operations;
  3. owners and lifetimes;
  4. observable effects;
  5. impossible combinations;
  6. carrier, operations, and candidate laws;
  7. a counterexample to each law; and
  8. the case where the abstraction should be refused.

Then apply the adequacy tiebreak: choose the larger structure only if it eliminates a reachable mistake, uses laws the behavior depends on, and has enough honest consumers to justify a shared abstraction.