The master invariant

One rule on the Portal's web chapter does more work than any other. It draws the boundary the whole layer stands on, and it holds for every caller.

The master invariant is a single universal rule, stated once: the web layer calls only the Portal facade and renders only the closed error set. Read it as the canonical example of what an invariant is. Select a web-layer caller on the right and watch the rule hold for each.

The rule, verbatim Why it is an invariant On the Portal References

The boundary the invariant draws · pick a caller

The controller calls only the Portal facade. Under the master invariant, no web-layer module names Portal.Engine, a repo, or GenServer.call — the rule holds for this caller, as it holds for every caller.

The rule, verbatim

The Portal's web chapter (F6) carries one invariant that governs the whole layer. It is named the master invariant, settled at F6.1 · Bootstrap the Phoenix Portal, and it reads exactly as below. Nothing on this page paraphrases it: an invariant is a precise rule, and a paraphrase is a different rule.

# f6.1.md — Invariants · F6.1-INV1 (master). Quoted verbatim.
#
#   The web layer calls only the Portal facade and renders only the closed
#   %Portal.Error{} set. No controller, LiveView, plug, or template names
#   Portal.Engine, a repo, or GenServer.call.
#
# In the file's own words: "This single rule is what makes the whole ladder safe."

Two universal claims sit inside that one rule. First: every call from the web layer goes through the Portal facade — no controller, LiveView, plug, or template names Portal.Engine, a repo, or GenServer.call. Second: the error set the web layer renders is closed — a fixed set, extended only by an explicit mapping. Both hold for every value, not for one scenario.

facade-only: Every web-layer call reaches the domain through the one Portal facade. No module under the web layer names the engine, a repo, or a raw process call.
closed error set: The web layer renders only %Portal.Error{} with a code one of :already_enrolled, :course_not_found, :lesson_locked, :invalid_progress — extended only by an explicit, no-catch-all mapping.
universal: Both claims quantify over every caller and every request. There is no scenario for which the rule is allowed to fail — that is what makes it an invariant rather than a check.

This is the one A4 page that names Portal.Engine and %Portal.Error{} — only inside this verbatim rule and the closed-error-set fact. Everywhere else, the Portal is discussed at the spec level.

Why it is an invariant, not a check

The master invariant is universal: it quantifies over every module in the web layer and every request. A check is one sample of it. The story F6.1-US3, from F6.1 · Bootstrap the Phoenix Portal, carries such a check — “search apps/portal_web/lib/, find no module references Portal.Engine.” That search exercises the invariant, but it is one scan at one moment; the invariant is the rule that must hold for every module the chapter ever adds.

Toggle below between the rule and the check that samples it. The rule is the universal claim, named once in the Invariants section. The check is one static search. Passing the search raises confidence; it does not make the rule true for a module added next week.

The rule, and the check that samples it · toggle

The master invariant covers every web-layer module, now and later — one universal rule, named once in the Invariants section. It is the claim the check samples.

The master invariant is the universal rule; the static search is one sample of it — passing the sample does not close the rule for every future module.

On the Portal: the rule that makes the ladder safe

On the Portal — the learning platform this course builds — the master invariant is what lets the whole web chapter grow safely. Because no web-layer module names the engine, a repo, or a raw process call, each new rung adds pages without reaching past the facade. The boundary is an architectural fact the spec states once and every later rung inherits.

The closed error set is the second half of the rule. The web layer renders only %Portal.Error{} values whose code is one of the four known kinds, extended only by an explicit mapping — so an unexpected failure can never leak a raw crash to a page. One universal rule, two universal claims, named once and inherited everywhere.

The principle

A master invariant is a single universal rule, stated once, that an increment may never break — the architectural fact every later slice inherits.

On the Portal

F6.1-INV1 — the web layer calls only the Portal facade and renders only the closed %Portal.Error{} set — holds for every web-layer module and every request.

The master invariant is one universal rule, named once — and it holds for every caller, which is exactly what makes it an invariant.

Recap — one rule, every caller

The master invariant is the Portal web chapter's canonical invariant: the web layer calls only the Portal facade and renders only the closed %Portal.Error{} set. It is universal — it holds for every controller, template, LiveView, and request — and it is named once, in the Invariants section, with a static-search check that samples it without replacing it. With the canonical invariant read, the closing dive looks at what “always” really demands.

Next in A4.5: A4.5.3 · Always true — why a finite set of passing checks samples a universal rule but never closes it.

References

Primary sources for the architectural invariant as a stated, inherited rule, and where it connects in the course.

Sources

Humble & Farley — Continuous Delivery — an architectural rule held continuously over every change to the system.
Adzic, G. — Specification by Example — the rule stated once, with examples that sample it.
Gherkin reference — Given/When/Then as the one-scenario check that exercises a rule.

Related in this course

A4.5 · Invariants — the module hub.
A4.5.1 · Invariant vs check — the previous dive.
A4.5.3 · Always true — the next dive.
A1.04 · Two layers: roadmap and specs — the spec layer the invariant lives in.
Companion · Phoenix (F6) — the chapter where the master invariant is implemented.