TyPy domain model¶
| Field | Value |
|---|---|
| Document | TyPy domain model |
| Version | 1.3 |
| Status | Approved |
| Owner | typy-lang contributors |
| Last updated | 2026-11-17 |
1. Purpose¶
This document names the concepts TyPy is built from, says what kind each one is, and states the rules that always hold for it. It builds on the approved use case model, version 1.0, the software requirements specification, version 1.0, and the decision records ADR-0001 to ADR-0005.
The names here are the names in the code, the documents and the diagrams. The software architecture, which comes next, places these concepts in building blocks.
Each concept has one of four kinds:
| Kind | Meaning |
|---|---|
| Value object | Defined by its value, never changed after it is made, compared by value |
| Entity | Has an identity that stays the same while its contents change |
| Aggregate | An entity that owns a group of objects and is the only way to change them |
| Domain service | An operation on several concepts that belongs to none of them |
2. Bounded contexts¶
TyPy has seven bounded contexts. Each one hands the next a single object, so a context depends only on the object it receives and never reaches back into an earlier context. The compiler stages follow from this: the pipeline in the architecture is the chain from Source to Build.
| Context | Responsibility | Receives | Hands on |
|---|---|---|---|
| Source | Find, read and parse the program's modules | A file path and typy.toml |
A SyntaxTree per Module |
| Checking | Resolve names, check types and the subset rules, report diagnostics | SyntaxTree per Module |
TypedProgram |
| Lowering | Build TyIR, decide representations, insert and remove reference counts | TypedProgram |
TyirModule |
| Code generation | Turn TyIR into LLVM IR and object code for one target | TyirModule |
ObjectFile |
| Build | Link object files, the runtime and C libraries into an artifact | ObjectFile and BuildRequest |
Artifact |
| Runtime | Allocate, count, collect and free objects; carry exceptions | Code linked into the artifact | Behaviour at run time |
| Conformance | Compare TyPy builds with the CPython oracle | ConformanceTest |
Verdict |
Code generation and Runtime share one contract: the layout of
ObjectHeader and TypeDescriptor. Code generation emits objects in that
layout, and the runtime reads them.
3. Source and checking¶
3.1 Source context¶
| Concept | Kind | Description |
|---|---|---|
Project |
Aggregate | The program being built: its settings and every module it contains. |
ProjectSettings |
Value object | The settings read from typy.toml, with command line flags applied, including the program's Python floor. |
Module |
Entity | One Python module, identified by its qualified name, such as app.models. |
SourceFile |
Value object | The path and the text of one .py file. |
Span |
Value object | A range of text in one SourceFile, from a start Position to an end Position. |
Position |
Value object | A line and a column in a SourceFile. |
SyntaxTree |
Value object | The parsed form of one module, as ruff_python_parser produces it. |
Rules that always hold:
ProjectSettingsis built once, when a command starts, and every key in it has been checked (UC-11). A command never readstypy.tomlagain.- A
Projecthas exactly one main module, and no two modules share a qualified name. - A
SourceFileholds valid UTF-8 text (LEX-01). - A
Positioncounts lines and columns from 1, and columns in code points (DIA-01). - A
Spanlies inside itsSourceFile, and its start is not after its end. - A
SyntaxTreeis the only form of the source that later contexts see. Its types fromruff_python_parserdo not leave the Source context (ADR-0005).
3.2 Checking context¶
| Concept | Kind | Description |
|---|---|---|
TypedProgram |
Aggregate | Every module with names resolved and every expression typed. |
Scope |
Entity | A region where names are bound: a module, class, function or comprehension. |
Symbol |
Entity | A name bound in one Scope, with its Type. |
Type |
Value object | The static type of a value, such as int, list[str], Point or int \| None. |
ClassDefinition |
Entity | A class with its fields, methods and at most one base class. |
FunctionSignature |
Value object | The parameter names, parameter types and return type of a function. |
Diagnostic |
Value object | One error or warning, with its DiagnosticCode, Span, message, optional fix and optional Rule. |
DiagnosticCode |
Value object | A stable code such as E0401 or W0501. |
Rule |
Value object | A requirement of the specification that a program can fall outside, identified by its ID, such as TYP-03. |
TypeChecker |
Domain service | Resolves names, infers and checks types, and builds the TypedProgram. |
SubsetChecker |
Domain service | Finds valid Python that TyPy cannot compile with CPython's meaning and reports it against its Rule. |
Rules that always hold:
- A
TypedProgramexists only for a program with no errors. Nothing after the Checking context ever receives a program with errors. - Every expression in a
TypedProgramhas exactly oneType(TYP-11), and noTypeisAny(TYP-10). - A
Symbolkeeps oneTypefor its whole life (TYP-03). - A union
Typeis kept in one canonical form: nested unions are flattened, duplicates removed, and members put in a fixed order, soint | NoneandNone | intare equal. - A
ClassDefinitionhas at most one base, and the chain of bases has no cycle (CLS-04). - A
Diagnosticalways has a code, a span and a message (DIA-01). ADiagnosticthat rejects valid Python always names itsRule(DIA-03). - A
DiagnosticCodeis never reused, and a retired code stays reserved (DIA-06).
4. Lowering, code generation and build¶
4.1 Lowering context¶
| Concept | Kind | Description |
|---|---|---|
TyirModule |
Aggregate | The whole program in TyIR, TyPy's intermediate form in static single assignment. |
TyirFunction |
Entity | One function in TyIR, with a flag saying whether it may raise. |
BasicBlock |
Entity | A straight sequence of Instruction values that ends in one branch, return or raise. |
Instruction |
Value object | One operation, such as a call, an arithmetic operation, a count increment or a count decrement. |
ValueRepresentation |
Value object | How one value is held: inline, on the stack, or boxed on the heap (ADR-0001). |
RaiseAnalysis |
Domain service | Works out which functions may raise (ADR-0004). |
EscapeAnalysis |
Domain service | Finds objects that do not outlive their function, so they go on the stack. |
OwnershipAnalysis |
Domain service | Inserts reference count operations, then removes those that borrows and moves make unnecessary. |
CycleAnalysis |
Domain service | Finds the types whose references could lead back to an object of the same type. |
Rules that always hold:
- A
TyirModulepasses the TyIR verifier after every pass. A failure is an internal error,E9xxx(NFR-09). - Generics are expanded: a
TyirModulehas oneTyirFunctionper concrete instance of a generic function (GEN-03). - A
TyirFunctionthat is not marked as may-raise contains no raise, and calls only functions that are also not marked as may-raise. - An
intvalue has an inlineValueRepresentationonly while it fits in 63 bits (DAT-01). - A stack
ValueRepresentationis chosen only whenEscapeAnalysisproves that the object does not outlive its function (MEM-03). - On every path through a function, each heap reference it owns is released exactly once, also on paths that raise.
4.2 Code generation context¶
| Concept | Kind | Description |
|---|---|---|
ObjectFile |
Value object | The machine code for one TyirModule and one Target. |
Target |
Value object | A target triple, such as x86_64-unknown-linux-musl, from the supported list (section 2.3 of the specification). |
Rules that always hold:
- An
ObjectFiledepends only on itsTyirModule, itsTarget, the build mode and the compiler version, so it is byte-identical when they are the same (NFR-06).
4.3 Build context¶
| Concept | Kind | Description |
|---|---|---|
BuildRequest |
Value object | What a command asks for: the main file, the BuildMode, the Target, an optional EmitStage and the LinkPlan. |
BuildMode |
Value object | debug, release or release-small (CLI-05). |
EmitStage |
Value object | The stage whose output is written instead of an executable: ast, typed-ast, tyir, tyir-mem, llvm-ir, asm or obj (CLI-04). |
LinkPlan |
Value object | The C libraries to link, each static or dynamic, and the functions to export (FFI-04, FFI-05). |
ExportSpec |
Value object | One exported function and its C signature. |
Artifact |
Value object | The written output: an executable, a static or shared library, a C header, or stage output. |
Rules that always hold:
- A
BuildRequesthas exactly oneBuildModeand oneTarget. - An
ExportSpecnames a module-level function of the program, and its C signature matches the function's annotations (UC-07). - An
Artifactis written completely or not at all. A failed build leaves no partial file (UC-02, flow 5a).
5. Runtime and conformance¶
5.1 Runtime context¶
| Concept | Kind | Description |
|---|---|---|
HeapObject |
Entity | An object allocated on the heap, identified by its address while it lives. |
ObjectHeader |
Value object | The 8 bytes at the start of every HeapObject: a 32-bit reference count and a 32-bit type ID (NFR-12). |
TypeDescriptor |
Value object | What the runtime knows about one type: its size, how to release its fields, and whether it may form a cycle. |
TypeObject |
Value object | An immortal object that names a type, its base and the functions that test, hash, compare and write its objects (ADR-0012). |
ExceptionObject |
Entity | A HeapObject whose class is an exception class: it carries the arguments it was built with, its traceback, its cause and its context (ADR-0013). |
HandledException |
Entity | The exception an except clause is handling, kept by the runtime while the clause runs. |
TracebackEntry |
Value object | One frame an exception passed through: the function and the line. |
Allocator |
Domain service | Hands out and takes back memory, through three replaceable functions (MEM-08). |
CycleCollector |
Domain service | Frees cycles of objects whose type may form a cycle, by trial deletion (ADR-0001). |
Rules that always hold:
- A live
HeapObjecthas a reference count of at least 1, and its count equals the number of references to it, except while theCycleCollectorruns. - A
HeapObjectis freed exactly once (NFR-07). - Only an object whose
TypeDescriptorsays it may form a cycle is ever given to theCycleCollector. - The
TypeDescriptorof a type is generated by the compiler and never changes while the program runs. - An
ExceptionObjectgains oneTracebackEntryper frame it passes through, in the order of the frames. - No
ExceptionObjectcrosses a function exported to C (EXC-05). - The chain of bases of every
TypeObjectends atobject, and the chain of every exception class passes throughBaseException. - An
ExceptionObjectraised while aHandledExceptionis kept takes it as its context, unless that would form a cycle (EXC-04). - Every way out of an
exceptclause ends itsHandledException.
5.2 Conformance context¶
| Concept | Kind | Description |
|---|---|---|
ConformanceTest |
Entity | One test program, the requirement IDs it covers, its Python floor, and whether it is expected to be accepted or rejected. |
OracleRun |
Value object | The standard output, exit status and last line of standard error of one CPython version on the program. |
Verdict |
Value object | The outcome of a test: passed, failed, invalid or not covered (UC-09). |
Rules that always hold:
- A
ConformanceTestnames at least one requirement ID (NFR-10). - An accepted-program test has one
OracleRunfor each oracle version from its Python floor up to 3.15 (ADR-0008). - When the
OracleRunvalues of one test disagree with each other, itsVerdictis invalid, never failed (STD-03).
6. Lifecycles¶
6.1 Heap object¶
A HeapObject starts live with a count of 1. While live, increments and
decrements move its count, and it is freed as soon as the count reaches 0.
An object whose type may form a cycle has one more state. When a decrement
leaves its count above 0, the object becomes a possible root: it might now
be held only by a cycle. When the CycleCollector runs, it subtracts the
references that come from inside the group of possible roots and the
objects reachable from them. An object whose count from outside the group
is still above 0 is live, and its counts are restored. An object whose
count from outside is 0 is part of a garbage cycle, and it is freed.
| State | Meaning |
|---|---|
| Referenced | Live, and not a candidate for cycle collection |
| PossibleRoot | Live, and might be held only by a cycle |
| Gray | Being examined by the CycleCollector |
| Black | Found to be held from outside; returns to live |
| White | Found to be garbage |
| Dropping | Its fields are being released |
| Freed | Its memory is back with the Allocator |
6.2 Exception¶
An exception is created as an ExceptionObject and raised. While it
propagates, each frame it leaves runs its cleanup and its finally blocks,
adds a TracebackEntry and returns the exception to its caller (ADR-0004).
An except clause matches it when the clause names its class or one of
the bases of its class (ADR-0013). A bare raise in the clause sends it on
again. It ends in one of three
ways: an except clause handles it and it is released; it leaves the main
module uncaught and is reported, with exit status 1 (STD-05); or it reaches
a function exported to C and the program aborts (EXC-05).
| State | Meaning |
|---|---|
| Created | Allocated, not yet raised |
| Propagating | Moving up the call stack, one frame at a time |
| Handled | Caught by a matching except clause |
| Released | The handler has ended, and the exception's last reference is gone |
| Uncaught | Returned from the main module |
| Reported | Printed to standard error, ending with the same last line as CPython |
| AtExportBoundary | Reached the wrapper of a function exported to C |
6.3 Module in the compiler¶
A Module is discovered when the main file names it or an import reaches
it. It is then parsed, resolved, checked and lowered. A failure at any step
moves it to failed, and its diagnostics are reported. A failed module stops
the build before code generation, but the other modules are still checked,
so one command reports every error it can (UC-01).
| State | Meaning |
|---|---|
| Discovered | Its SourceFile has been found |
| Parsed | It has a SyntaxTree |
| Resolved | Its names and imports are bound to Symbol values |
| Checked | Its types and subset rules hold |
| Lowered | Each of its functions has a TyirFunction |
| Failed | A step reported an error |