Lesson 14 · Edges and reverse names

When the IR stops being a tree

You got the whole-program compilation unit, the owning side, the embedded-value flatten and identity ownership without help. What came back blank was both halves of the mechanism: what in the pipeline guarantees one foreign key, and what exactly collides when two models point at each other. Those are the same lesson, because they are both consequences of one broken invariant.

The invariant that broke

Every lesson up to here could assume two things, and relationships kill both.

Both blanks in the diagnostic follow from the second row. Name the vocabulary first.

Act I · One edge, two surface forms

Here is the backend from the diagnostic again, and the answer to what it produces:

const emit = (model: Model) =>
  model.fields.map(f =>
    isIdRef(f.type)  ? fk(f, resolve(f.type)) :
    isIdList(f.type) ? fk(f, resolve(f.type.item)) :
    column(f))

Given User.company: CompanyId and Company.users: list[UserId] it emits two foreign keys — one on User, one on Company — and the second is wrong in two independent ways at once. It is on the one side, so the schema now claims a company has exactly one user; and it duplicates an edge that was already represented, so the two can disagree.

The reason is visible in the type signature: emit takes a Model and maps over fields. A function of that shape cannot decide not to emit, because the fact it would need — that another model already carries this edge — is not in its argument. This is the same diagnosis as lesson 3: a missing IR node showing up as a decision nothing is in a position to make.

Where the fix goes, and why not the other two places

Not the backend. Corrected after your note: the first version of this paragraph claimed the FastAPI backend wants both directions, and you were right that it doesn't — a payload should show one direction too. Which makes the argument simpler and stronger rather than weaker. Every backend wants one edge, so a rule placed in one of them is a rule the others have to reimplement identically: N backends, one fact, N copies. That is the narrow waist failing in the direction it always fails, and the fix is the one you named in session 1 — put the fact in the middle once. Deduplication is a fact about the domain, not about Django.

Worth keeping the corrected version in mind as a general check on placement arguments: “this backend needs it and that one doesn't” is a much weaker reason than “all backends need it, so it should exist once”, and the first is easy to assert without testing. If you cannot name a consumer that genuinely wants the other behaviour, you are not looking at a target-specific decision.

Not the loader. The loader sees one class at a time and by construction cannot know whether UserId resolves; that is the whole reason the compilation unit grew.

A pass in the middle, and it earns its keep by adding a node. The IR grows a Relation, the pass builds the set of them, and the backend maps over relations plus scalar fields rather than over fields alone:

type Relation = {
  readonly owner: ModelName      // the many side; holds the column
  readonly ownerField: FieldName // what the domain author called it
  readonly target: ModelName
  readonly optional: boolean
}

Two passes, in this order, and the order is forced:

// pass 1 — collect. Every model that declares an identity field claims its id type.
//   Company: id: CompanyId  =>  { CompanyId -> Company }
const table = declarations(models)

// pass 2 — resolve. Now every reference has something to resolve against.
const relations = referencesOf(models).map(r => lookup(table, r))

You cannot merge them. User may mention CompanyId before Company is loaded, so any single traversal that resolves as it goes will fail on roughly half the possible file orders — which is a lovely bug, because it passes your tests until someone renames a file. Collect everything, then resolve: the two-phase structure is not a style preference, it is what a forward reference costs.

Both surface forms now normalise onto one node, which is lesson 12 in a new setting — and worth noticing, because in lesson 12 the two spellings were of a type and the canonical form was a rewrite. Here the two spellings are of an edge, the canonical form is a node that neither spelling mentions, and one of the two spellings is not even allowed to produce it. Canonicalisation sometimes means adding a representation rather than choosing between the ones you have.

Act II · Two names you did not write

Question 4, precisely: a bidirectional reference collides in Django's inferred methods is the right instinct and one term short. The thing that collides is a reverse accessor or a reverse query name, and the namespace it collides in belongs to the other model.

One ForeignKey injects two names into its target:

class User(models.Model):
    company = models.ForeignKey("core.Company", on_delete=models.PROTECT)

# Django adds to Company, without being asked:
#   Company.user_set          <- reverse accessor      (related_name)
#   Company.objects.filter(user__...)   <- reverse query name  (related_query_name)

Both default to a function of the source model's name. That is the whole problem, because a generator's naming is systematic: if you name a foreign key field after its target model — the obvious choice, and the one a derived generator makes — then the reverse query name Django derives from the source model is on a collision course with the field name on the other side.

class User(models.Model):
    company = models.ForeignKey("core.Company", on_delete=models.PROTECT)

class Company(models.Model):
    owner = models.ForeignKey("core.User", on_delete=models.PROTECT)
    # reverse query name for Company.owner, on User, is "company"
    # User already has a field called "company"
    # => fields.E303, and Django refuses to start

Django's system checks name all four shapes this takes, and they are worth reading as a taxonomy rather than as error codes — the two axes are which name (accessor or query name) and collides with what (a field, or another reverse name):

Three fixes, and you have seen them before

These are lesson 8's families, unchanged, applied to a namespace you do not own:

The recommendation is rename, unconditionally. Not “rename when a collision is detected” — detection means you have written a global uniqueness check over a namespace Django populates by rules you are reimplementing, and you will get it wrong. Emit the derived name every time, including for the single-relation case where the default would have been fine. A generator's advantage over a human is that it can afford to be uniform.

Exercise A · Generated models, some of them fine

Each is output from a Django backend. Click the line that breaks, or say clean. Two of the six are clean.

Exercise B · Which phase owns it

Six obligations. Place each in the loader (front end), a transformer (middle), or the Django backend. The discriminator is the one from lesson 1: could a second backend need this, and does the decision require facts the phase cannot see.

Exercise C · From memory

The diff

1. Relation joins the IR — owner, ownerField, target, optional. The backend maps over relations and scalar fields, never over raw fields alone.
2. Two passes, in order: collect declarations into a symbol table, then resolve references. Resolution failure is a diagnostic with a span, accumulated rather than raised (lesson 6).
3. A collection field never creates a relation. Unmatched or ambiguous collections are diagnostics — the two errors Django structurally cannot report for you.
4. Every emitted ForeignKey carries an explicit related_name derived from (source model, owning field). No defaults, no collision detection.
5. The property to assert, in the language of lesson 9: for any domain package, the number of ForeignKeys emitted equals the number of scalar id references — invariant under permuting file order, and invariant under adding a collection field.

What this unlocks

Two things, both blank in the diagnostic. Cycles: you now have an edge set, so you can ask whether it has one — and question 11 was the shape of that problem, two non-nullable foreign keys pointing at each other, where no order of construction works and the fix has to come from somewhere other than ordering. Elaboration: on_delete, null, related_name and db_index are all facts the backend invents because the target demands them and the domain never said. That is the name for it, and it is the one gap in your RESOURCES.md that this cluster finally makes worth closing.

status · resources · mission