Skip to content
C.W.K.
Stream
More →
Lesson 05 of 06 · published

The Edges the Paragraph Missed

~13 min · imports, records, drift, verification

Level 0Loose Parts
0 XP0/48 lessons0/13 achievements
0/100 XP to next level100 XP to go0% complete

The Record Said One

The previous lesson's rule — no queue module imports another — carries its exceptions in a paragraph beside the rule, each with its reason, so that the next candidate has to make an argument rather than cite a precedent. For a while that paragraph said exactly one: the rows-backed registry importing the plain registry.

Here is what the code did in the following seven weeks.

  • A command layer for the two generic workshops arrived importing the workshops' command plumbing and the review kernel at load — two edges from one module. Its reason is the same shape as the first exception: injecting either would only make both generic workshops pass the same modules — ceremony, not decoupling.
  • The review kernel began importing the family-settings reader, lazily, inside the one function that resolves a local-model reviewer's model. It is lazy because only that reviewer needs it, and it shows how late a missing file bites: when the edge was found, a consumer that had not vendored the reader would have ended the whole round with an import error the moment that reviewer was chosen, because the round only caught runtime errors at that point. The same review changed the code so a missing reader now raises a runtime error, and the round skips that one reviewer with the reason instead.
  • When reviewer routing moved to the system that owns multi-brain calls, the review kernel began importing the brain-call client at load.

The command layer's two edges and the settings reader's edge were written into the record about three weeks after the first of them appeared — by a review that found them in the code while the paragraph still said one. So the record now holds three exceptions covering four edges. The brain-call edge is in the code today, and the record's list does not include it yet: five edges in the code, four in the record. There is also a carve-out that is deliberately not counted as an edge: the queue modules import the generated brain catalog, because it is the catalog root, and a module that kept its own brain list would be exactly the shadow roster the family's guard exists to catch.

What Kept the Field Safe

Nothing broke in any consumer. That is because a second rule sits beside the first, and it is the one that is mechanically checkable: the manifest keeps every edge whole. Every repository that receives an importing module also receives the module it imports. The review kernel's consumers all receive the settings reader and the brain-call client; the command layer's consumers receive both of its imports. So an import the paragraph forgot was still an import the deploy honored.

The two rules have different shapes. "Every edge has a written reason" lives in prose, read by people when they happen to look. "Every importing module's targets are a subset of its import's targets" is a property of two files that a test can compute on every run. The first drifted. The second held.

Outside the Queue, the Kit Became a Graph

The no-import rule was always stated for the queue kernel. Elsewhere in the Python half, the kit now has edges on purpose. The shared-state layer from track 6 is a composition: its authority module assembles six stores and route sets, and the provider authority builds on the family authority. The encryption helper reads its key through the shared keychain reader. The image-job client builds on the cover-image client. Every one of those edges ships whole, too — checked edge by edge on the day this lesson was written.

That matters for the distribution model in track 3. The copy mechanism is right for a dependency-free leaf, and the kit's own record names the next reason to revisit it: a vendored Python leaf that grows a dependency its consumers do not already have. The wholeness rule is what has kept that trigger from firing. It is the first thing to test when the Python half grows another edge.

A recorded exception is a claim about the code; check it against the code, or the record becomes the precedent it was written to prevent. A list of exceptions that nobody derives from the source decays exactly like a hand-kept table: adding the import is one line in one file, updating the record is an edit somewhere nobody is looking. Derive the edge list from the code, compare it with the record, and fail when they disagree — the reasons stay prose, but the list must be computed.

Why the Obvious Check Would Miss One

A quick check would scan the top of each module for import lines. It would find most of the edges and miss the lazy one, because that import sits inside a function body and only runs when a particular kind of reviewer is resolved. That is exactly the edge whose absence cost the most: until the import error was converted, a consumer without the settings reader would have lost a whole round at the moment that reviewer was chosen, far from any deploy. Today it loses that one reviewer, with a reason. A real check walks the whole syntax tree, not the first lines of the file.

Code

Derive the edges from the code; hold the record and the manifest to them·python
import ast
from pathlib import Path

KIT = Path("kit/python")
MODULES = {p.stem for p in KIT.glob("kit_*.py")}
CATALOG_ROOT = {"kit_pippa_brains"}       # generated: a root, not an edge


def kit_imports(module: str) -> set[str]:
    """Every kit module this one imports - ANYWHERE in the file.
    A lazy import inside a function is still an edge; a scan of the
    first lines of the file would miss exactly that one."""
    tree = ast.parse((KIT / f"{module}.py").read_text())
    found: set[str] = set()
    for node in ast.walk(tree):
        if isinstance(node, ast.ImportFrom):
            names = [node.module or ""] + [a.name for a in node.names]
        elif isinstance(node, ast.Import):
            names = [a.name for a in node.names]
        else:
            continue
        for name in names:
            leaf = name.rsplit(".", 1)[-1]
            if leaf in MODULES and leaf != module:
                found.add(leaf)
    return found - CATALOG_ROOT


def code_edges() -> set[tuple[str, str]]:
    return {(m, dep) for m in MODULES for dep in kit_imports(m)}


def test_every_queue_edge_has_a_written_reason(recorded_queue_edges):
    """The RULE is scoped to the queue kernel; so is its record."""
    queue = {(a, b) for a, b in code_edges() if a.startswith("kit_queue_")}
    missing = queue - recorded_queue_edges
    assert not missing, f"queue edges with no written reason: {sorted(missing)}"


def test_every_edge_ships_whole(manifest_targets):
    """The rule that held, for EVERY edge in the kit: whoever receives
    the importer also receives what it imports."""
    for importer, dep in code_edges():
        assert manifest_targets[importer] <= manifest_targets[dep], (
            f"{importer} reaches a repo that lacks {dep}"
        )

External links

Exercise

Find a rule in your codebase that is documented together with a list of its exceptions — allowed imports, permitted dependencies, approved bypasses. Derive the actual list from the code, including anything that happens lazily or conditionally. Compare the two. For every difference, decide whether the code or the record is wrong, and add a test that fails the next time they disagree.
Hint
Search for imports inside function bodies and behind conditionals first. Those are the edges most likely to be missing from a record, because they were added to handle one path, by someone who was thinking about that path and not about the rule.

Progress

Progress is local-only — sign in to sync across devices.
← PreviousNo Module Imports AnotherNext →Slots, Props, and the Thing You Didn't Anticipate
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign in — Please sign in to comment.

No comments yet — be the first.