Concepts — Production Source Apprenticeship: React and Vue

Phase 5 · Spec areas §28, §32, §44 Levels 2–3, §46. Prerequisites: fw-02, fw-03, fw-04, fw-05 — all of them built first.

§45 is explicit: "Do not begin with production source. First derive a simple design. Then use production source to discover the constraints that forced additional complexity." This module is the second half of that sentence, and it is worthless without the first.

0. Orientation

The 60-second version

You have built five runtimes. This module is where you read the production versions and answer one question for every difference:

What did production have to handle that my version did not?

Three answers are possible, and classifying correctly is the entire skill:

Most engineers classify everything as the first. Being able to identify the third — with evidence from git history — is what separates reading source from understanding it, and it is the specific skill that lets you argue for removing complexity in systems you own.

Why the order matters

§45 is explicit: "Do not begin with production source. First derive a simple design. Then use production source to discover the constraints that forced additional complexity." This module is the second half of that sentence and it is worthless without the first. Reading Fiber before deriving it produces someone who can recite field names.

The procedure that terminates

React and Vue are large. Reading without a method does not converge:

1. Start from your own implementation's file, not theirs. "Where is their reconcileChildren?"
2. Find the entry point by searching the public API name, then follow one call inward.
3. Read the type definitions first — a Fiber's field list tells you more in two minutes than an hour of following calls.
4. Skip the bailout paths on the first pass. In most production functions, the majority of the lines are cases your implementation does not have. Read the main path first, then come back and the extra cases become legible as answers to specific questions.
5. Keep a deferred list (bi-01). The names you chose not to follow are your map.
6. Stop when you can explain the difference from your version. That is the deliverable — not full comprehension.

What you should be able to do after this module

1. The method

For every area you read, you are answering one question: what did production have to handle that my version did not?

Three outcomes are possible per difference, and classifying them is the actual skill:

• Essential architecture — my design cannot meet a real requirement without it.
• Production hardening — my design works but fails on scale, edge cases, or hostile input.
• Accreted complexity — historical, and a greenfield implementation would omit it.

Most engineers classify everything as the first. Being able to identify the third — with evidence from git history — is what separates reading source from understanding it.

2. React reading list

Read in this order; each maps to something you built.

3. Vue reading list

3.5 Deep dive: the three classifications, with worked examples

The method asks you to classify every difference as essential architecture, production hardening, or accretion. That is only useful if you can tell them apart, so here are worked examples from this track's own material.

Essential architecture — the requirement forces it

Fiber's explicit work loop. Interruptibility requires the stack to be a data structure (fw-04 §4.5). There is no simpler design that yields the same capability. Your own derivation proves it: you tried to pause recursion and could not.

Property trees in Blink (bi-09). Without them, a transform change re-records display items. The capability "change position without repainting" is impossible otherwise.

Two-phase render/commit. Discardable work cannot have side effects; consistent output requires atomic application. Two statements of one requirement.

Production hardening — works in the small, fails in the large

Redux's listener snapshotting (fw-01). The naive version is correct until a listener unsubscribes during notification. Not an architectural insight — a bug that had to be closed.

Blink's fragment-parsing fast path (bi-03). The general algorithm is correct; the fast path exists because innerHTML is hot. It bails out to the general path, which is the tell: a fast path that falls back is hardening, not architecture.

Style sharing (bi-07). Correctness does not require it; 10,000-row tables do.

Accretion — historical, and a greenfield design would omit it

The script-escaping tokenizer states (bi-03). kScriptDataDoubleEscaped* exists because 1990s pages wrapped scripts in HTML comments. Nobody would design it.

<input type=hidden> inside <table> (the parsing lab). A compatibility fossil, not a principle — as the answer key argues.

[LegacyLenientThis], [LegacyUnforgeable] and friends in Web IDL (bi-05). The Legacy prefix is the platform labelling its own accretion, which is unusually honest and makes them easy to find.

The tell for accretion: the code has a name containing Legacy, Compat, Quirks, or a comment citing a specific site or year. The tell for essential architecture: removing it makes a capability impossible, not merely a case wrong. The tell for hardening: it is a fast path or a guard around an otherwise-correct implementation.

Being able to say "this is accretion and here is the CL that introduced it" is what separates reading source from understanding it — and it is the specific skill that lets you argue for removing complexity in systems you own.

3.6 Deep dive: reading production source without drowning

React and Vue are large. A procedure that terminates:

1. Start from your own implementation's file, not theirs. "Where is their version of my reconcileChildren?"
2. Find the entry point by searching for the public API name, then follow one call inward.
3. Read the type/flow definitions first if they exist — a Fiber's field list tells you more in two minutes than an hour of following calls.
4. Skip the bailout paths on the first pass. Production code is mostly early returns for cases you do not have. Read the main path, then come back.
5. Keep a deferred list (bi-01). Names you chose not to follow are your map.
6. Stop when you can explain the difference from your version. That is the deliverable, not full comprehension.

Point 4 deserves emphasis: in most production functions, the majority of the lines are cases your implementation does not have. Reading them in order makes the function look incomprehensible; reading the main path first makes the extra cases legible as answers to specific questions.

3.7 Deep dive: specific questions worth carrying into the source

Not "read the scheduler" — these:

React

• Why does a Fiber initialise every field in the constructor, even to null? (bi-05, hidden classes — you now know the answer, so confirm it.)
• What exactly is a "lane," and why lanes rather than a numeric priority?
• Where is the double buffer (current / alternate), and what happens to the discarded tree?
• What does bailout check, and how does it skip a subtree?
• Why do effects have separate passive and layout phases? When does each run relative to paint?
• How is hydration mismatch detected, and what is recoverable versus fatal?
• What does the scheduler use as its host callback, and what changes with scheduler.yield()?

Vue

• How are dependency sets stored — per target, per key? What is the memory shape at 10,000 reactive objects?
• What exactly does effect cleanup remove, and when? (You built this; compare.)
• How does the scheduler order pre / post / sync jobs, and why does flush: 'post' exist?
• How are patch flags consumed in patchElement? Find the switch.
• Where is the LIS computation, and what does it do with the unmatched middle?

Each has a specific answer you can find and check against your own implementation. A question you can answer wrongly is worth ten times a topic you can read about.

4. The gate (§44)

For each area, all eight questions in writing: why it exists, what invariant it maintains, who calls it, what it calls, which thread runs it, what happens if removed, how it is tested, what simpler design fails and why.

Log every reading in LEARNING-LOG.md §3.

5. Complexity notebook (§46)

Required entries, using the template in PROGRESS.md:

• Fiber — the flagship entry
• The Vue scheduler
• Hydration
• Event delegation / synthetic events
• Concurrent rendering

For each, classify the complexity per §1 above and defend the classification with evidence — a commit message, an issue, a test that exists only because of a specific bug.

Core terminology

Mental models

"What did production have to handle that my version did not?" is the only question. It converts an unbounded reading task into a bounded diffing task, and it terminates.

The tells are reliable enough to use as a first pass.

• Essential: removing it makes a capability impossible, not merely a case wrong.
• Hardening: it is a fast path that bails out to a general path, or a guard around otherwise- correct code. The bail-out is the giveaway — Blink's fragment-parsing fast path (bi-03) is hardening precisely because it falls back.
• Accretion: the name contains Legacy, Compat, Quirks, or a comment cites a specific site or year. Web IDL's [LegacyLenientThis] is the platform labelling its own accretion, which is unusually honest and makes it easy to find.

A question you can answer wrongly is worth ten times a topic you can read about. "Read the scheduler" is not a task. "What does the scheduler use as its host callback, and what changes with scheduler.yield()?" is — it has an answer, you can be wrong about it, and being wrong teaches you something.

Most of a production function is cases you do not have. Reading it top to bottom makes it look incomprehensible. Reading the main path first makes the remainder legible as a list of answers to specific questions — which is also how you should write code you expect others to read.

Building first is not a warm-up. It is what makes the differences visible at all. Someone who reads Fiber without having failed to pause a recursive render sees a data structure; someone who derived it sees a set of forced consequences.

Common misconceptions

1. "Reading the source is how you learn a framework." Reading source after deriving a simple version is how you learn it. Reading first produces transcription — recitable field names with no model of why they exist.

2. "All this complexity is necessary; it's production code." Some is accretion, and identifying it is the skill. The Legacy prefix exists because implementers agree with you.

3. "I should understand the whole file." Stop when you can explain the difference from your version. Full comprehension of a production reconciler is not a deliverable anyone needs.

4. "A fast path is an architectural insight." A fast path that bails out to a general path is hardening — the general path is the architecture.

5. "Git history is noise." It is the evidence. "This is accretion and here is the CL that introduced it" is a categorically stronger claim than "this looks historical."

6. "Synthetic events are obviously right." Reconstruct the original justification, then check whether it still holds after React 17's delegation change. Several original reasons have expired.

7. "Whichever framework I read last is the better design." Both ship at enormous scale, which is itself evidence about how much these choices matter relative to what else you could work on.

Interview talking points

• "When I read production source I'm answering one question per difference from my own implementation: is this essential architecture, production hardening, or accretion? Most people classify everything as essential. Being able to point at accretion with a CL behind it is what lets you argue for removing complexity in systems you own."
• "The tells are pretty reliable. Essential means removing it makes a capability impossible. Hardening is usually a fast path that bails out to a general path — the bail-out is the giveaway. Accretion has Legacy or Compat in the name, or a comment citing a site or a year. Web IDL's [LegacyLenientThis] is the platform labelling its own accretion, which is unusually honest."
• "My reading procedure starts from my file, not theirs — 'where's their version of my reconcileChildren?' — reads types first, and skips bailout paths on the first pass. In most production functions the majority of lines are cases my implementation doesn't have, and reading them in order makes the function look incomprehensible."
• "I carry specific questions rather than topics. Not 'read the scheduler' but 'what does it use as its host callback and what changes with scheduler.yield()?' A question you can answer wrongly is worth ten times a topic you can read about."
• "Building first isn't a warm-up. Someone who reads Fiber without having tried and failed to pause a recursive render sees a data structure. Someone who derived it sees a set of forced consequences — and can tell you which fields they didn't derive, which is the interesting list."

6. Principal Engineer Review

1. Name one piece of React complexity you classify as accreted rather than essential. Defend it with evidence, and say what a greenfield implementation would do instead.

2. Synthetic events: reconstruct the original justification, then evaluate whether it still holds.

3. Hydration mismatches are recoverable in some cases and not others. What is the rule, and what does that imply for how you write SSR components?

4. Vue's scheduler and React's scheduler solve overlapping problems differently. Name the deepest difference, and what each optimises.

5. After reading both: which architecture would you choose for a new product, and what is the strongest argument against your choice?

6. You now have mini-implementations and production source for both. What did building first teach you that reading first would not have?

Connections to other modules

• fw-02 / fw-03 / fw-04 / fw-05 — hard prerequisites, all of them. Each production area in the reading lists maps to something you built; without the counterpart the diff is invisible.
• fw-01 — where the classification method is first practised, on a system small enough to be exhaustive.
• fw-06 — React's compiler is the answer to the positional-storage constraint; read it against what you built.
• bi-01 — the deferred-list technique, and the navigation skills this module reuses at framework scale.
• bi-03 — the fragment-parsing fast path and the script-escaping states are the worked examples of hardening and accretion.
• bi-05 — Web IDL's Legacy* extended attributes: accretion the platform labels itself.
• bi-11 — the scheduling constraints React's scheduler answers to.
• fe-03 — why a Fiber initialises every field in its constructor, even to null. You already know the answer; confirm it in the source.