How it works

This document teaches the machinery. It is written for two readers at once: someone who wants the five-minute version of what the system does, and someone who wants the schema, the predicate grammar and the enum values. Read §1 and stop, or read all of it.

Everything below describes the system as it is today, in this repository. Where something is designed but not built, or built and limited, the limitation is stated in place rather than left for you to discover.

This is not legal advice. The system states what a statute’s own text mechanically yields on stated facts as of a stated date. It never states what anyone should do.

1. The five-minute version

Law is prose, but it behaves like code: defined terms, conditions, consequences, exceptions, cross-references. What law lacks is a compiler — nothing forces a statute to be consistent with its own definitions, so when it isn’t, the inconsistency just sits there. This project builds the missing compiler.

The pipeline, in order:

Three properties are worth having in mind before the detail:

2. The data model

Five tables. Relational, Postgres, SQLAlchemy models in src/codify/models/.

(Primary keys below are shown as <…> descriptions rather than numbers: they are assigned at load time and carry no meaning of their own.)

statutes — one row is one piece of text

One row per addressable unit of the statute: a section, a subsection, a paragraph, a clause. text is verbatim; parent_id nests the row under the one above it.

statute_id      <this row>
citation        "26 USC 3401(c)"
title           "26"
chapter         "24"
section         "3401"
subsection      "(c)"
subchapter      NULL          -- chapter 24 has no subchapters
part            NULL
text            "For purposes of this chapter, the term “employee” includes an officer,
                 employee, or elected official of the United States, ..."
parent_id       <the "26 USC 3401" row>
source_kind     "statute_text"
version         1
effective_date  2018-03-23
superseded_date NULL
enacting_authority
                "Pub. L. 115–141, div. U, title IV, § 401(a)(217), Mar. 23, 2018, 132 Stat. 1194"

subchapter and part are recorded from the source’s own placement line and never inferred from a section number. That matters: 26 USC 6651(a)(1) reaches returns “required under authority of subchapter A of chapter 61 (other than part III thereof)”. 6041, 6041A and 6051 fall outside that span because their rows say “PART III”, not because 6041 is numerically greater than 6031.

source_kind (StatuteSourceKind) says what kind of primary text the row holds:

terms — one row is one definition, with its reach

term_id          <this row>
term             "employee"
definition_text  "For purposes of this chapter, the term “employee” includes ..."
defined_in_statute_id
                 <the 26 USC 3401(c) row>
scope_type       "chapter"
scope_ref        "26 USC ch. 24"
version          1
effective_date   2018-03-23
enacting_authority
                 "Pub. L. 115–141, div. U, title IV, § 401(a)(217), Mar. 23, 2018, 132 Stat. 1194"

term is deliberately not unique. The same word appears many times with different definitions and different scopes — that is expected and important. 26 USC 3401 defines “wages” twice:

Note what the second row does: the definition lives in subsection (f) and governs subsection (a). defined_in_statute_id and scope_ref are different things, and the statute’s own words decide each.

Nothing in definition_text is retyped. Each definition is sliced from the already-loaded statutes rows by two verbatim anchors, and the slice is asserted to be a substring of the row’s subtree before anything is written.

rules — one row is one if-then

rule_id           <this row>
statute_id        <the row the rule comes from>
conditions        <JSONB predicate tree>     -- what must be true
consequence       <JSONB predicate tree>     -- what follows
rule_type         "definition"
overrides_rule_id NULL                       -- set when an exception governs a general rule

conditions and consequence hold a small tree grammar (§3). rule_type is one of general / specific / exception / definition. In 26 USC 3401, the (a) “wages” definition is one definition rule and each of its 23 enumerated exclusions is an exception rule whose overrides_rule_id points at it.

term_usage — one row is one use of a term, and its resolution

This is where type errors surface.

usage_id           <this row>
statute_id         <the row where the word is used>
term_text          "employer"
term_id            NULL
resolution_status  "undefined"
corrected_at       NULL
correction_note    NULL

resolution_status is resolved / undefined / conflict, and a database CHECK constraint enforces the pairing: only a resolved row may carry a term_id. An undefined row cannot point at a definition (none governs), and a conflict row storing one would be exactly the silent guess the first invariant forbids.

term_usage is the one derived table, so a resolution may be corrected — but only through an audited path. A trigger permits an UPDATE to change resolution_status/term_id only when the same statement also sets a fresh corrected_at and a non-empty correction_note.

references — one row is one pointer between provisions

from_statute_id, to_statute_id, reference_type ∈ definition / exception / incorporation / cross_ref / authority. Append-only: a trigger refuses every UPDATE.

authority is a deliberate addition to the spec’s four: it records a statute deriving its power from a constitutional provision (26 USC 3401 → U.S. Const. art. I § 8 cl. 1 / amend. XVI). That is neither an incorporation, nor a definition, nor a neutral cross-reference.

The five columns that do the heavy lifting

Everything hard in this system is carried by five columns.

scope_type values (ScopeType), narrowest to widest:

The spec’s §4 named only five of these (subsection/section/chapter/title/code). Each addition was forced by the words of a real statute: 3401 scopes two of its own definitions “For purposes of this paragraph”, 6651(a)(1) names a subchapter and a part, and an act that is not codified into any code has no title and no chapter at all — its widest internal scope is the act itself. Recording an act-wide definition as chapter-scoped would make the column say something the statute does not say.

There is one more form, for a span with a carve-out:

<base scope_ref> excluding <citation or division>

26 USC ch. 24 excluding 26 USC 3401(a)
26 USC ch. 61 subch. A excluding 26 USC ch. 61 subch. A pt. III

StatuteRepo.list_in_scope resolves the base span and then drops every row in the excluded subtree. A chapter/title/code scope resolves only to rows that have been loaded — an empty result for a well-formed ref means nothing in that span is loaded yet, not that the span is invalid.

Nothing is ever deleted — enforced by the database, not by convention

An audit found this invariant held only by convention: the repositories exposed no delete(), but a raw DELETE FROM statutes worked, an in-place UPDATE on a live row worked, and setting a closed row’s superseded_date back to NULL worked. A Python-side guard would not have closed those holes, because the probes went around the ORM entirely. So it is enforced with real Postgres triggers, on all five tables (models/db_guards.py):

3. How a sentence of law becomes a rule

Worked end to end on one real provision: 26 USC 6051(a), the W-2 duty. It is a good example because a single sentence binds three different classes of person, each described in its own words, and only one of them turns on a defined term.

3.1 The verbatim text

6051(a) opens by naming who is bound. Three disjunctive classes:

Class 1 — “Every person required to deduct and withhold from an employee a tax under section 3101 or 3402”

Class 2 — “who would have been required to deduct and withhold a tax under section 3402 (determined without regard to subsection (n)) if the employee had claimed no more than one withholding exemption”

Class 3 — “every employer engaged in a trade or business who pays remuneration for services performed by an employee, including the cash value of such remuneration paid in any medium other than cash”

and then states the one duty they all bear:

“shall furnish to each such employee in respect of the remuneration paid by such person to such employee during the calendar year, on or before January 31 of the succeeding year, or, if his employment is terminated before the close of such calendar year, within 30 days after the date of receipt of a written request from the employee if such 30-day period ends before January 31, a written statement showing the following:”

3.2 The terms it uses, and where each one is defined

This is the whole point of recording scope. Chapter 24’s definitions say “For purposes of this chapter,” and 6051 is not in that chapter. Nothing in 6051(a) redirects them. So “employer” at 6051(a) is undefined in scope — a fact recorded in term_usage, and a stop when the engine reaches it. It is not resolved by borrowing chapter 24’s meaning (that would be scope expansion), and not by falling back to ordinary meaning (canon 1 forbids that where a definition exists and was scoped elsewhere).

3.3 The predicate grammar

conditions and consequence are JSONB trees in this grammar (src/codify/predicate.py):

node := {"op": "and",  "args": [node, ...]}
      | {"op": "or",   "args": [node, ...]}
      | {"op": "not",  "arg":  node}
      | {"op": "atom", "kind": str, "text": str, "terms": [term_ref, ...],
         "cites": [str, ...], ...extras}
      | {"op": "for_purposes_of", "scope_type": str, "scope_ref": str, "text": str | null}

term_ref := {"term_id": int}                 -- a loaded `terms` row
          | {"external": str, "text": str}   -- "X (as defined in <cite>)", pointing
                                                outside the loaded text

An atom is one test or one effect. Its text is the statute’s own words, verbatim — proved to be a substring of the loaded row it comes from. A for_purposes_of node is the statute’s “for purposes of …” words in the same grammar terms.scope_ref uses, so the engine can ask “does this rule reach here?” exactly the way it asks that of a definition.

In conditions, every atom has kind: "test". In consequence, the kind names what the statute does:

sense matters: means / includes / including / deemed_only_if. “Means” is exhaustive and “includes” is additive, and reading one as the other would make the drafter’s word do nothing — which canon 4 forbids. The same reasoning is why permit exists separately from require: the difference between “may” and “shall” is the entire content of some provisions, and recording a power as a command would state a duty the statute does not impose.

Four optional extras, all verbatim, all recorded so the engine can report them rather than resolve them:

3.4 The loaded rule

Class 3 of 6051(a), as loaders/usc_title26_6051.py builds it. t(word, scope_ref) is a placeholder that bind_terms replaces with the real term_id at load time, so a rule can never name a term that does not exist:

_duty("a.class3", "26 USC 6051(a)", CLASS_3,
      atom(CLASS_3, terms=[EMPLOYER_24, EMPLOYEE_24, TOB],
           note="'employer' is 3401(d)'s, out of scope here: UNDEFINED_TERM"),
      EFFECT_A, cites=["26 USC 6051(f)(1)(B)(i)"])

which lands in the database as one rules row:

{
  "rule_type": "specific",
  "conditions": {
    "op": "and",
    "args": [
      {"op": "for_purposes_of", "scope_type": "section",
       "scope_ref": "26 USC 6051", "text": null},
      {"op": "atom", "kind": "test",
       "text": "every employer engaged in a trade or business who pays remuneration
                for services performed by an employee, including the cash value of
                such remuneration paid in any medium other than cash",
       "terms": [{"term_id": <3401(d) "employer">},
                 {"term_id": <3401(c) "employee">},
                 {"term_id": <7701(a)(26) "trade or business">}],
       "cites": [],
       "note": "'employer' is 3401(d)'s, out of scope here: UNDEFINED_TERM"}
    ]
  },
  "consequence": {
    "op": "atom", "kind": "require",
    "text": "shall furnish to each such employee in respect of the remuneration paid
             by such person to such employee during the calendar year, on or before
             January 31 of the succeeding year, ... a written statement showing the
             following:",
    "terms": [], "cites": ["26 USC 6051(f)(1)(B)(i)"],
    "actor": "every employer engaged in a trade or business who pays remuneration for
              services performed by an employee, including the cash value of such
              remuneration paid in any medium other than cash"
  }
}

Two things to notice.

The actor is the statute’s own class words, not a defined term. 6051(a) does not say “an employer shall furnish”; it describes three classes. So the actor on the consequence atom is the verbatim class phrase, and the corpus declares it an actor class (Corpus.actor_classes): a party resolved by the duty’s own condition atoms, bound to facts, never by a definition (there is none) and never by ordinary meaning (canon 2 is for a word the text leaves undefined, not for a class the text spells out). A forcing function checks that each declared class is the actor of a duty carrying at least one condition atom, so no class resolves vacuously.

cites records the limit, it does not apply it. 6051(f)(1)(B)(i) says (A)’s reporting is “in lieu of” (a) for those payments. It is loaded as a limit each (a) duty cites — so every emitted effect carries it as subject_to — rather than as an exception that switches the duty off, because the engine’s disapplying-exception mechanism names one overridden rule and this one narrows three.

3.5 What the engine does with it

The engine cannot read English. Each condition atom is bound — keyed by its exact verbatim text, in the binding table of the corpus the rule belongs to — to a small expression over that corpus’s typed Facts:

F(path)                fact is True
F(path, ">=", n)       numeric or ISO-date fact compared with the statute's own figure
F(path, "in", items)   fact is one of the statute's enumerated items
NOT(x) / ALL(...) / ANY(...)
T(word, subject)       the defined term applies to the subject -- resolved and evaluated
R(word)                the word is NAMED here, not re-tested ("such employee")
SUBJECT_IS(role) / SUBJECT_FACT(name)
QUARTER_DAYS(op, n)    days of such service in the quarter under test
ALL()                  no factual content: the atom is a judgment or a pointer

The binding carries only the factual content of the words. Everything else the atom says about itself — its discretion, its delegated, its external term refs, its unloaded cites — is read off the atom by the evaluator and never restated in the binding table, so the two cannot drift apart. A test enforces, per corpus, that every condition atom of every live rule is bound and every field of the corpus’s fact schema is read by some binding.

Running 6051(a) class 3 on a case: the condition atom binds to facts about the payer and the payment; the atom names the chapter-24 “employer” term. The engine resolves that word at this usage site, finds that no definition’s scope reaches 26 USC 6051, and returns UNDEFINED_TERM — carried in the trace, with the definition it found and the reason its scope does not reach. The duty is not asserted. The honest result is that the statute’s own text, as loaded, does not mechanically establish that this person is bound by 6051(a) class 3.

3.6 The same provision, run: scenario S33

work/scenarios/S33-w2-duty-6051a-attaches-to-the-withholding-person.json. P employs E, withholds income tax under 3402 and social security tax under 3101, and controls and makes the payment. Question: what does the law require, and of whom? As of 2026-03-01, against the composed chapter 24 + 61 corpus.

Expected result:

{"type": "Consequence",
 "value": {
   "effects": ["26 USC 6051(a)", "26 USC 3403"],
   "blocked": [{"citation": "26 USC 3402(a)(1)", "kind": "DISCRETION_POINT"},
               {"citation": "26 USC 6011(a)",    "kind": "DISCRETION_POINT"},
               {"citation": "26 USC 6051(a)",    "kind": "UNDEFINED_TERM"}],
   "actor_names": {"26 USC 6051(a)": ["P"], "26 USC 3403": ["P"]}}}

Note also what is blocked rather than asserted: the 3402(a)(1) withholding duty stops at a DISCRETION_POINT, because establishing that the payment is wages runs into the same judgment terms §7 describes. The W-2 duty attaches anyway — it turns on P having withheld, which the facts state, not on the engine deciding that the payment was wages.

4. Scope is the hard part

This is the single most important technical idea in the system, and the one most often got wrong in practice — including by courts, which is why the audit layer exists at all.

A definition’s scope is part of the definition. “For purposes of this subsection” is narrower than “for purposes of this title,” and the difference is load-bearing.

4.1 Why 3401’s definitions are unreachable from 6051

26 USC 3401(c) and (d) both open “For purposes of this chapter”. The chapter is 24. So:

terms.scope_type = "chapter"
terms.scope_ref  = "26 USC ch. 24"

StatuteRepo.list_in_scope parses that ref and resolves it to loaded rows by filtering statutes.chapter == "24". 26 USC 6051’s rows carry chapter = "61". They are not in the span. The definition exists, is in force, and does not reach.

What happens next is canon 1’s second branch, and it is the opposite of what intuition expects:

“employer” is defined (term <id> (26 USC ch. 24)) but no definition’s scope reaches 26 USC 6051(a); ordinary meaning may not stand in for a definition the statute scoped elsewhere

canon_1_defined_term_controls, with the term id elided

So the result is a stop, not a fallback. Canon 2 (plain meaning) is available only where a word is undefined, not where it is defined and the drafter scoped the definition somewhere else. Reaching into chapter 24 anyway would be SCOPE_EXPANSION — one of the divergence types the audit layer is built to catch.

The statute can, of course, redirect a word itself, and where it does, the system follows it because the redirection is the statute’s own words. 6051(a)(3) says “wages as defined in section 3401(a)”, and 6051(f)(1)(A) says “wages for purposes of chapter 24”. Those are recorded as express imports and resolve to 3401(a)’s chapter-scoped “wages” row. By contrast, 6051(a)(2) and (a)(5) say “wages as defined in section 3121(a)” — text that is not loaded — so those resolve undefined: an external redirect at the edge of the corpus, reported rather than invented.

4.2 Why 3401(d)(1) cannot operate inside 3401(a), but can at 3402

26 USC 3401(d) defines “employer” chapter-wide, and then two paragraphs carve out a span in the statute’s own words:

“(d)(1) … the term ‘employer’ (except for purposes of subsection (a)) means the person having control of the payment of such wages”

That parenthesis is not decoration. It means that inside subsection (a) — where “wages” is defined — the (d)(1) substitution does not operate; everywhere else in chapter 24 it does. The loader encodes it as a predicate node, not as prose:

EXCEPT_SUBSECTION_A = NOT(
    scope(ScopeType.SUBSECTION, "26 USC 3401(a)", "(except for purposes of subsection (a))")
)

serialized as:

{"op": "not",
 "arg": {"op": "for_purposes_of", "scope_type": "subsection",
         "scope_ref": "26 USC 3401(a)",
         "text": "(except for purposes of subsection (a))"}}

This is why the usage site is a first-class part of a question, not bookkeeping. Every question kind names a default site, the evaluator records the site it used as the first trace step, and --at overrides it. The same word, the same facts, the same date, asked at two different places in the text, can resolve to two different definitions — and therefore to two different people.

Three scenarios pin this down, and S13 and S14 share an identical fact set — a gardener G2 engaged and directed by a surgeon S at S’s private residence, paid $600 in cash by L, a landscaping company that “alone decides the amount and timing of every payment … S has no power to make, stop, or time payments.” Same facts, same date (2024-10-01), different site:

S13 records the trap in its own words: “if (d)(1) were wrongly applied, the employer would be L, gardening is in the course of L’s business, (a)(4) would fail, and the result would fall to DISCRETION_POINT.” The wrong answer is not merely a different name — it changes the outcome of the whole question.

S30 runs the consequence path on the same shape of facts, and the split shows up as a different kind of result. S engages and directs W, but L alone controls and makes the payment. Expected: {"type": "Stop", "kind": "DISCRETION_POINT"}. The scenario’s headline sentence:

“The same term, one fact set, resolves cleanly (S) at 3401(a) and stops at 3402/3403: that scope-sensitivity is the finding.”

Its companion S29 is the aligned case — BuildCo both employs W and controls the payment — and there the consequence run does produce an effect:

{"effects": ["26 USC 3403"],
 "blocked": [{"citation": "26 USC 3402(a)(1)", "kind": "DISCRETION_POINT"}],
 "actor_roles": {"26 USC 3402(a)(1)": ["service_recipient", "payer"],
                 "26 USC 3403":       ["service_recipient", "payer"]},
 "actor_names": {"26 USC 3403": ["BuildCo"]}}

Note actor_roles: the machine-readable role sets are recorded per citation, so two resolutions of “employer” at two sites can be compared as data rather than read as prose. That is the datum the (not yet built) docket is designed around — see §10.

4.3 A span with a carve-out, read rather than guessed: scenario S44

26 USC 6651(a)(1) adds a penalty for failure to file “any return required under authority of subchapter A of chapter 61 (other than part III thereof)”. That is a span with a division carved out, and it is recorded as one:

scope_ref: "26 USC ch. 61 subch. A excluding 26 USC ch. 61 subch. A pt. III"

work/scenarios/S44-6651-does-not-reach-a-missed-1099-but-6721-does.json runs it. P owed a 1099 for a $3,000 payment and never filed it. The result:

{"effects": ["26 USC 6721(a)", "26 USC 6041(a)", "26 USC 6041A(a)"],
 "blocked": [{"citation": "26 USC 6011(a)", "kind": "DISCRETION_POINT"},
             {"citation": "26 USC 6051(a)", "kind": "UNDEFINED_TERM"}],
 "actor_names": {"26 USC 6721(a)": ["P"]}}

6651 does not reach the failure; 6721 does. The scenario states precisely why, and it is the point of recording placement as data:

“The carve-out is READ — the span ‘26 USC ch. 61 subch. A excluding 26 USC ch. 61 subch. A pt. III’ is resolved through each row’s own recorded subchapter and part — so 6041 falls outside it because its rows say PART III, not because 6041 is a bigger number than 6012.”

A system that inferred the part from a section-number range would get the right answer here by luck and the wrong one eventually. And the penalty that does attach is reported in the statute’s own words — “such person shall pay a penalty of $250 for each return” — with the $250 and the $3,000,000 cap as the statute’s own figures, while 6721(f)(1)’s cost-of-living adjustment is recorded as external and never computed.

A companion case, S35, shows a reference walked rather than copied: 6041A(a) reaches remuneration for services on a threshold it does not itself fix — it points at “the dollar amount in effect for such calendar year under section 6041(a)”. The engine walks that as a loaded reference. The scenario’s first must_not is “copy 6041(a)’s dollar figure into 6041A”, which would work today and silently break the next time 6041(a) is amended.

4.4 The scope machinery was USC-only, and that was a bug in the machinery

Until the conformance exercise, every scope grammar regex required the literal string “ USC ” in a fixed position. That was invisible while the only loaded corpus was 26 USC 3401. Asked to record a scope from a statute that is not in the USC, the grammar rejected every well-formed scope_ref such a statute could possibly have. The spec asks scope_ref to name “the exact span the definition governs” and says nothing about whose citation format it is written in — so the grammar is now scheme-aware, with a second scheme for statutes cited as acts. The two are unambiguous: a USC ref always carries “ USC ”, an act ref always carries “ c. ”.

5. Time

Every lookup is time-scoped, and a lookup with no date is refused.

This is not a default that happens to be set; it is a typed error at the data layer. Every read method in every repository calls require_as_of before building any query:

def require_as_of(as_of: date | None, method_name: str) -> date:
    if as_of is None:
        raise MissingAsOfDate(method_name)
    return as_of

and every versioned read is filtered by the version window:

def version_valid_at(model, as_of):
    return and_(
        model.effective_date <= as_of,
        or_(model.superseded_date.is_(None), model.superseded_date > as_of),
    )

The refusal reaches the surface intact. POST /api/run without as_of returns HTTP 400:

“as_of (YYYY-MM-DD) is required. The engine answers only for the statute as it read on a stated date and never defaults to today (spec §6).”

and codify run without --as-of exits 2 with the same refusal.

The reason is substantive, not fastidious: a case decided in 2003 must be judged against the statute as it read in 2003. A system that silently answers “as of today” produces a confident wrong answer for every historical case, and no way to tell which answers those were.

There is a deliberate consequence of this design worth stating plainly: because the ORM models carry no relationship() attributes on versioned tables, you cannot navigate from a statute to its parent or from a usage to its term by attribute access. A lazy load fetches by primary key with no version filter, and an earlier audit found exactly that failure — two versions of the same child both appearing under .children while the same rows read through the repository correctly returned one. Walking the hierarchy goes through StatuteRepo, which never skips the gate.

A worked version window: 26 USC 6041(a), $600 → $2,000

Pub. L. 119–21 (July 4, 2025) amended 6041(a) in three ways with two different effective dates: §70433(a)/(e) substituted “$2,000” for “$600” and “calendar year” for “taxable year”, applicable to payments made after Dec. 31, 2025; §70201(f)(1)(A) and §70202(c)(2)(A) inserted the cash-tips and overtime accounting, applicable to taxable years beginning after Dec. 31, 2024.

The checked-in source fragment carries only the current composite text. So what got loaded is this:

citation            "26 USC 6041(a)"
text                "... of $2,000 or more in any calendar year ..."
effective_date      2026-01-01     -- the first day EVERY word of it is in force
superseded_date     NULL
enacting_authority  "Pub. L. 119–21, title VII, §§70201(f)(1), 70202(c)(2), 70433(a),
                     (b), (e), July 4, 2025"

The alternative — taking the current text and editing “$2,000” back to “$600” to manufacture the earlier version — would have produced a row that looks authoritative and is not. The system would rather have a recorded gap than a plausible fabrication. An empty result for a well-formed query is a statement that this system has not loaded that version, not a statement that the duty did not exist.

Every row in the chapter 61 corpus carries this evidence structure, not just a date:

class RowDate:
    prefix: str              # which row(s) this covers
    effective_date: date
    enacting_authority: str
    verified: bool           # False: the date is a documented FLOOR, not a finding
    basis: str               # WHY -- the evidence, positive or negative. Required.
    exact: bool = False

basis is required; a row whose date has no stated evidence fails to load. Some bases are negative evidence, and say so: several 6051(a) paragraphs are dated “ESTABLISHED NEGATIVELY. No amendment note names this paragraph, and every note on ‘Subsec. (a)’ quotes the words it inserted, struck or substituted …, none of them in this paragraph”. Others are explicit floors: where the fragment carries no effective-date note, the row takes the enacting law’s own date and verified=False, marked “NOT ESTABLISHED — floor.”

A version window is not the same thing as a provision expiring

26 USC 6012(f) (“Special rule for taxable years 2018 through 2025”) is loaded effective 2018-01-01 with no superseded_date, deliberately. The distinction the loader draws:

“a superseded_date means CONGRESS CLOSED THE ROW — a later enactment replaced or repealed the text … (f) is not closed by anything. Its words are still printed in the Code, still enacted, still law. What stops is its CONDITION matching: a taxable year beginning in 2026 is not ‘before January 1, 2026’.

Conflating the two would corrupt the amendment machinery — a diff would report a repeal Congress never made, and a query as of 2030 would find the row missing rather than find it present and inapplicable.”

So the expiry lives in the rule’s conditions, as an explicit date-range test, and a query as of 2030 correctly returns the row and finds it does not attach.

Amendment supersedes; it never deletes

An amendment is never a mutation and never a delete. It closes the old version and opens a new one (amendments/amend.py):

1. repo.supersede(old, superseded_date=amendment_date) — the old row survives, with its superseded_date set.
2. repo.add(...) a fresh row with version = old.version + 1, effective_date = amendment_date, and the enacting_authority that made the change.

enacting_authority is required and must be non-blank; the write is refused otherwise. An amendment_date earlier than the amended version’s effective_date is refused too — a version cannot be superseded before it began. Neither function commits: both writes live in the caller’s transaction, so they land together or not at all.

Diff and ripple

diff answers “what changed between these two dates”. Both dates are required; every read goes through the repositories with an explicit as_of, so diff adds no back door around the gate. Two snapshots are paired by natural key, never by primary key — an amendment gives the new version a new *_id, so pairing by id would read every amendment as a delete plus an unrelated insert. Statutes pair by citation, terms by (defined_in citation, term, scope_ref), rules by (citation, rule_type, canonical(conditions), canonical(consequence)).

There is an honest limitation here, reported rather than papered over: a rule’s predicate is part of its key, because rules has no column tying v2 of a rule to v1. So a rule whose predicate changed does not pair — the old predicate is reported as RULE_RETIRED and the new one as RULE_ADDED, rather than being given an invented lineage id.

ripple answers “what was still running on the old meaning”. Given an amended term, it finds that term’s immediately-preceding version and flags every term_usage site, rule and reference still pointing at it. It only flags — it never corrects a usage, re-binds a rule or edits a reference. The report is the list of things a reviewer must revisit.

Ripple deliberately walks wider than usage sites alone. In 26 USC 3401, all 23 exclusion rules bind “wages” by term_id in their own exclude consequence, but the word “wages” is never spelled in those rows — the anaphor is “such term” — so no term_usage row sits on them, and a usage-only walk would miss the rules that matter most. Ripple therefore also flags any rule whose predicate binds the predecessor term_id, and records which path reached each one.

6. The seven canons, in priority order

The canons of construction are the execution rules. They run in a fixed priority order, and the order is itself data — a tuple the engine walks, not a chain of ifs (engine/canons.py).

Each canon is a pure function. It sees only a Situation — a frozen value describing exactly what is in contest — and returns either None (nothing to say here) or a CanonFired carrying a human-readable reason. A CanonFired with a decision settles the situation and ends the walk; one without a decision is recorded and the walk continues. Nothing in a canon reads the database, the facts, or the clock.

Rank 0 is a documented deviation from the spec’s seven. Lex superior is not a rule for interpreting text — it is the supremacy principle antecedent to them: a statute void for exceeding its authority is never even construed. It is numbered 0 so the order stays strictly increasing and is policed exactly like the rest, and it returns None on every interpretive situation, so its presence leaves ordinary term resolution unchanged.

A canon interaction, worked: scenario S23

work/scenarios/S23-misclassified-1099-common-law-employee.json. A carpenter, W, is issued a Form 1099 by BuildCo, which sets W’s hours, picks the job site, supervises the work, supplies the tools and vehicles; W has no other clients and bears no risk of loss. Question: is W an “employee” within 26 USC 3401(c), as of 2024-10-01?

Expected: {"type": "Answer", "value": {"is_employee": true}}, no stops.

3401(c) says the term “employee” includes an officer, employee, or elected official of the United States, and an officer of a corporation. W is none of those. The naive reading — W is not on the list, therefore W is not an employee — is canon 5 (expressing some excludes the rest) applied to a word the drafter introduced with “includes”.

The scenario records canons 1, 2 and 4 as must-fire and puts canon 5 in canons_must_not_fire, with the reason: it “must not read (c)’s ‘includes’ list as exhaustive (blocked by canon 4)”. Canon 4 — every word counts — is what does the blocking: “includes” is an additive verb and “means” is an exhaustive one, and reading the first as the second makes the drafter’s choice of word do nothing. That is why sense is recorded on every define atom: the distinction has to survive the trip into the database or the canon has nothing to act on.

The paper form BuildCo issued is not evidence of anything in this system. It is not statutory text, no rule tests it, and nothing in the schema reads it.

An inverted order is refused

check_priority runs before any canon runs, and raises CanonInversion if the order puts a lower-priority canon at or ahead of a higher one, repeats one, or contains a function that is not one of the canons:

canon 2 is placed at or after canon 3’s turn in [1, 3, 2]: a lower-priority canon may never be consulted ahead of a higher one

An order may omit canons — that is a legitimate ablation (“what would the text do without canon 3?”) — but it may never invert them. This matters because CANON_INVERSION is itself one of the divergence types the audit layer looks for in rulings: a court using a lower-priority canon to override a higher one. A system that could do the same thing internally could not credibly report it.

7. Stops are results, not failures

A stop is a first-class typed value carried in the trace, never a swallowed exception. “A stop is a valid and informative result.”

There are four (results.StopKind):

ORDINARY_MEANING_USED is deliberately not a stop. It is a trace flag: a weaker footing than a definition, but derivation keeps going.

Two of these the engine can never reach on its own. DISCRETION_POINT on the within-authority path and CONSTITUTIONAL_CONFLICT both require a stipulated determination to have established the conflict first — the engine never decides constitutional fit itself.

How a stop is selected and reported

When a derivation ends with unresolved dependencies, the engine sorts them by STOP_PRECEDENCE — DISCRETION_POINT, then CONSTITUTIONAL_CONFLICT, then DEFINITION_CONFLICT, then UNDEFINED_TERM — and reports the first. The reasoning is that a hand-off to human judgment is reported ahead of a conflict, and both ahead of a gap that loading more text could close. Every load-bearing stop is written into the trace as a STOP step, and the reported detail says how many others there were:

[+3 more load-bearing stop(s) in the trace]

A missing fact is handled differently again. If the answer depends on a fact that was never supplied, the engine raises IncompleteFacts naming exactly which facts — it does not guess them, and it does not pretend to know which stop would have survived them.

The most counter-intuitive result the project has produced

The reason is mechanical. The (a) “wages” definition is qualified by 23 enumerated exclusions. Before the engine can say a payment is wages, it has to establish that no exclusion takes it out. But several of those exclusions are written in judgment language the drafter left open on purpose — “reasonable to believe” appears nine times across 3401’s rules, carried on the atoms as discretion:

“at the time of the payment of such remuneration, it is reasonable to believe that such remuneration will be excluded from gross income under section 911”

26 USC 3401(a)(8)(A)(i)

“at the time of the payment of such remuneration it is reasonable to believe that a corresponding deduction is allowable under section 217 (determined without regard to section 274(n))”

26 USC 3401(a)(15)

“at the time of such payment it is reasonable to believe that the employee will be able to exclude such payment from income under section 106(b)”

26 USC 3401(a)(21)

An ordinary payment reaches those exclusions, and there is no fact in the schema that can close them, because the statute did not write a test — it wrote a judgment. So the honest answer for a plain salary payment is not “yes” and not “no”: it is DISCRETION_POINT, naming exactly where the text stops and a person begins.

S01 is that case run concretely. A CFO elected by the board is paid a $10,000 salary check on 2024-03-15; the question is is-wages; the eight “not” determinations the scenario states are supplied as stipulations. Expected result: {"type": "Stop", "kind": "DISCRETION_POINT"}, with five decisive stop sites recorded — (a)(8)(A)(i), (a)(15), (a)(18), (a)(21), (a)(22) — each carrying the statute’s words "reasonable to believe".

The scenario suite’s own headline finding puts it this way:

“Under A1-A4, no ordinary payment to an employee can come out Answer is_wages=true from 3401’s text. Every such payment reaches the ‘reasonable to believe’ exclusions at (a)(15), (a)(18), (a)(21) and (a)(22), and at (a)(8)(A)(i) as well when the employee is a US citizen working for a non-US-government employer. … The wages definition hands every positive case to human judgment.”

work/scenarios/00-assumptions.json

The scenarios in work/scenarios/ were written by hand from the loaded statute text, blind to src/codify/engine/ — the 00-assumptions.json file says so and names the eight assumptions (A1–A8) the expectations rest on.

One honesty note that belongs with the finding: S01 is marked contested: true. Its contest_note records what would flip it — “If the owner rules that reached-but-unengaged discretion conditions do not stop, this becomes Answer is_wages=true with the five sites still listed.” That is an open owner decision about how strictly a reached-but-unengaged judgment condition should bind, not a defect. Either way the five sites are reported; what is contested is whether reporting them should also halt the answer.

The other findings from the first statute

• “Wages” carries two live definitions at once. The general chapter-wide definition in 3401(a), and a narrower one in 3401(f) about tips that is scoped back onto subsection (a) by its own words. Their spans genuinely overlap inside (a), and the statute’s own text does not say which yields when they disagree.
• The base concepts are undefined. “Remuneration” — what the entire “wages” definition is built from — and “person” — what the entire “employer” definition is built from — are defined nowhere in the loaded chapter-24 text. Both are load-bearing; neither has a definition to stand on. (“Person” is defined title-wide at 7701(a)(1), which is loaded for the chapter 61 corpus; that reach is a property of where the definition was scoped, not a patch.)

8. What it refuses to do

The refusals are as much the design as the capabilities.

No opinion, regulation or commentary in the codification layer

The loader is a closed allowlist, not a blocklist (src/codify/load.py):

ACCEPTED_KINDS = frozenset({
    SourceKind.STATUTE_TEXT,
    SourceKind.STATUTORY_DEFINITION,
    SourceKind.CONSTITUTION,
})

Anything else — opinion, regulation, commentary, an unrecognized string, an empty string, None, an integer — raises RejectedSourceKind. An earlier version checked membership in a rejected set and let everything unnamed through unchanged; that was the bug the allowlist fixes.

This is deliberate and it is the foundation of the whole project. Opinions and rulings enter later, in the audit layer, as the thing being measured — never as the measuring stick. If interpretation goes into the foundation, there is nothing left to check against.

Amounts delegated to the Secretary are recorded, never computed

26 USC 3402(a)(1) fixes the withholding amount “in accordance with tables or computational procedures prescribed by the Secretary”. That content lives in regulations, which this layer refuses. So the delegation is carried verbatim on the atom as external, emitted on the Effect as external, and logged in the trace as an EXTERNAL_EDGE step.

Crucially, it is not a stop. A delegation of the amount does not negate a duty that otherwise attaches. The scope of the answer is whether and who — not how much.

A related boundary: the engine compares numbers the statute itself states — 6041(a)’s threshold, 6012(a)’s “$600 or more”, 3401(a)(4)’s day counts — because those figures are in the statute’s own words. It never computes one. No penalty is calculated, no tax is determined, no dollar figure is produced. 6721(a)(1)’s “$250 for each return” and 6651(a)(1)’s “5 percent of the amount of such tax” are carried as the statute’s verbatim words in an Effect, not as arithmetic.

A missing fact is never read as “no”

Every fact in the schema is | None and defaults to unknown. Unknown is left out of a request, and it is never treated as “no”. If an answer depends on a fact that was not supplied, the engine says which fact, rather than assuming the convenient value.

This matters because in a statute built on exclusions, “unknown” and “no” point in opposite directions: treating an unanswered exclusion as inapplicable would manufacture “is wages: true” answers that the text does not support — the exact error §7 describes.

Fiction never sits beside law

The synthetic act used to measure the engine (§9) is quarantined at three levels, not one:

• load.SourceKind.SYNTHETIC_CONFORMANCE is deliberately absent from ACCEPTED_KINDS, so the production loader has no door for it at all.
• forbid_corpus_contamination makes a database holding synthetic rows and real rows impossible at the trigger level, in either insertion order.
• corpora.register() refuses a synthetic corpus, so the CLI and API cannot select one; compose() refuses to join a synthetic corpus to a real one in either order; and the evaluator checks at run time that a real corpus only ever evaluates real rows.

The reason is the same one behind the allowlist: fiction on the real engine’s evaluation path is indistinguishable from law to everything downstream.

The engine never finds anyone guilty

26 USC 7203 creates a criminal offense, and its mens rea word — “willfully” — is a judgment term carried as discretion. The engine reports where the text hands the question to a court. It does not answer it. Likewise, a duty conditioned on a judgment term is not emitted as an Effect at all: it stops at DISCRETION_POINT, carried in the trace and named in the consequence value, rather than being asserted with a caveat attached.

9. How we know it’s right

Two independent checks, because “the tests pass” is not evidence that the content is faithful to the source. One of them exists specifically because a green test suite once failed to catch a fabrication.

9.1 Provenance: the text is fetched, never transcribed

work/sources/usc/title26/MANIFEST.md records twelve statutory fragments. Its opening sentence is the rule:

“Every file in this directory was fetched, never transcribed. No statutory word in any of these files was typed from memory, paraphrased, or corrected by hand.”

Each fragment carries seven recorded fields:

The source for all twelve is the Office of the Law Revision Counsel — the publisher of record, not a mirror — and the manifest records the source’s own currency statement (“Text contains those laws in effect on September 19, 2026”) alongside the retrieval date and the granule URL. The saved files are verifiable in one command:

cd work/sources/usc/title26 && shasum -a 256 *.md

The manifest also records what it does not resolve. 7701.md carries an open source anomaly: the OLRC prelim HTML serves an+d where §7701(a)(1)’s definition of “person” reads “mean and include”. GPO’s typeset 2023 edition reads and. The saved file preserves the OLRC bytes verbatim, records both readings with their URLs, and does not pick a winner — the anomaly blocks codifying “person” from that row rather than being quietly resolved in the loader.

The rendering conventions (fenced blocks, indentation taken from OLRC’s own class names, HTML entities unescaped to Unicode) are all listed with the note that “these affect presentation only; no word is changed by any of them” — down to preserving a stray space before punctuation in a source-credit line, noted explicitly “so no one later ‘tidies’ it and calls the file edited.”

9.2 The 3403 fabrication — why a green suite is not evidence

This is the most instructive failure in the project’s history, and it is recorded in the code rather than in a changelog.

26 USC 3403 reads, in full, that the employer “shall be liable for the payment of the tax required to be deducted and withheld under this chapter, and shall not be liable to any person for the amount of any such payment.”

An earlier revision of the loader’s transcription ended:

“…the amount of any such payment except as otherwise provided by law.”

Why the test suite was green. The fidelity test — test_every_effect_word_is_verbatim_from_its_own_row — asserts that every word an effect atom claims is a substring of its own loaded row. But 26 USC 3402/3403 had no checked-in authoritative fragment; their text came from a hand-transcribed constant in the same module. So the test proved the transcription agreed with itself. The test module’s own header now says so:

“The substring check therefore proves INTERNAL CONSISTENCY between an effect’s words and the loader’s transcription — it CANNOT prove the transcription is the statute. It did not catch an earlier revision that appended the invented words ‘except as otherwise provided by law’ to 26 USC 3403.”

This is the difference between 3401 and 3402/3403 at the time: 3401’s loader parses a checked-in authoritative USLM fragment, so its verbatim claims are checkable against a file in the repository. A verbatim claim is only as good as the artefact it can be checked against.

The rule the failure produced, now permanent in the loader docstring:

“an instruction that a duty must never be stated UNCONDITIONED is about not OMITTING a real condition. It is never a licence to SUPPLY one. Where a needed condition does not exist in the text, the answer is to say so — never to write it.”

What was put in place:

1. A standing regression guard, test_3403_has_no_invented_trailing_qualifier, checking the invented tail across three layers: the loaded row text, every rule consequence atom, and every Effect.text / Effect.subject_to the consequence run emits.
2. Provenance recorded as data — module constants naming the source, the retrieval date and the authoritative publisher, asserted by a test, including the explicit admission that a mirror is not the publisher of record and that checking in an OLRC fragment “remains the real fix”.
3. date_basis required on every row, under the rule “no row may carry a date — verified or not — without saying why”, because “a bare date is the same unfalsifiable claim that let the 3403 fabrication through.”
4. Eventually, the real fix: 3403.md fetched from OLRC and checked in. The manifest names it “the direct replacement for the transcription that had six words appended to it.”

Two details worth keeping: removing the invented clause changed no scenario outcome — what changed is that 3403’s effect now carries exactly one qualifier, the real 3402(d), instead of two. And the same pass fixed a citation imprecision in the same family: the withholding command is 26 USC 3402(a)(1), the paragraph carrying the command, not bare 3402(a), which is only the subsection heading.

9.3 The blind conformance suite

The second check answers a different question. 26 USC 3401’s correct answers are contested — that is the project’s own premise — so the real corpus cannot tell you whether the interpreter is right. The conformance exercise builds a statute whose correct answers are known, by having them written down first, by someone who could not see the engine.

The instrument. The Tidewater Moorage Registration Act, 2019 (Act No. 14 of 2019, Province of Kelbrook), cited internally as KEL 2019 c. 14. Neither the act nor the province exists; every word was invented for this exercise. It deliberately contains the hard cases: “a definition confined to one subsection and then used in another; an exclusion disapplied at exactly one site; two definitions of one term for the same span, enacted the same day by the same act; a list whose items carry qualifiers that are easy to read out; a period defined so that it cuts across the calendar; a cross-reference to an act nobody supplied.”

The blind separation is the whole design. Three roles, walled off from each other:

The author’s reason for staying blind: “the exercise proves nothing if the prose is shaped to whatever happens to be convenient to encode. The act is written as law and the encoder has to cope with it as law.”

Finding 1 → issue #14 (a real engine bug)

Pattern p04 asks whether a person is an “operator” for purposes of s. 4(3). Answering it requires reaching a definition limb that uses the term “berth licence”, which is defined at s. 4(4) and scoped to section 4. The site of application is s. 4(3) — inside section 4 — so the term is in scope and resolves. The authoritative answer is Answer, applies=True. The engine returned Stop UNDEFINED_TERM, because it resolved the nested term at the textual location of the words (s. 2(1)(e), outside section 4) instead of at the site the question was asked.

This is not a toy defect. It is the same error, in miniature, as the live 26 USC question of whether “employer” is resolved at 3402’s site or at 3401(a)’s — the distinction 3401(d)(1) and (d)(2) turn on, and the subject of §4.2 above. A blind synthetic act found it in a form that can be tested deterministically. Left unfixed, it would make every definition that leans on a section-scoped term permanently unresolvable from outside that section — which would make cross-referencing definitions dead text, and canon 4 forbids that.

Finding 2 → issue #15 (a genuine gap in the spec, pre-registered)

Pattern p09 has two definitions that both apply to the same text and happen to produce the same result. The author’s authoritative outcome is Stop DEFINITION_CONFLICT — “the spec conditions the stop on two definitions APPLYING, not on their diverging.” The engine instead answered, because canon 6 (whole-text consistency) selected one meaning. The control, p08 — the same conflict where the two definitions diverge — passes; the engine does stop there. So the disagreement is precisely and only about the agreeing case.

Both readings are defensible, which is why this is a spec question for the owner rather than a bug. The argument for “Stop” is an asymmetry: under “Answer”, the same statutory defect is reported or not reported depending on the facts of the case — the conflict becomes invisible exactly when nobody is harmed by it, and mapping latent bad law is part of the job.

Ruled (issue #15, 2026-09-21): “show both.” Where two applicable definitions agree on the facts the engine answers — but it applies both and reports both: the result carries a concurrences record naming each definition in full (where it is defined, its scope, its effective date, its text, its verdict), the trace gains a DEFINITIONS_CONCUR entry beside the DEFINITION_USED entry each definition already had, and canon 6’s decision is recorded as a concurrence, never a selection. Where they diverge, the DEFINITION_CONFLICT stop is unchanged (p08). The measuring stick was amended on the record: OUTCOMES.md pattern 9 now carries the ruling, the previous expectation and the reasoning, with the original entry preserved beneath it. The conformance suite ends at 35 passed, 0 failed, 9 xfail; no 26 USC result changed.

What makes this adjudicable rather than a post-hoc rationalisation is that the author pre-registered p09 in OUTCOMES.md, before any run, as the suite’s weakest-supported outcome and the first to re-litigate.

The 9 xfails are themselves one structural finding (issue #13)

No question kind in the Tidewater corpus can reach a deem or a permit rule, so both of the act’s DISCRETION_POINT sites could not be asked at all. Plus no date arithmetic, no fee computation, and enacting_authority dropped on the way through one record type. The engine, in other words, was shaped around 26 USC 3401, and encoding a second act found seven representation failures.

The suite is deselected from the default test run, deliberately:

markers = ["conformance: blind conformance suite -- failures are findings, not regressions"]
addopts = "-m 'not conformance'"

The reasoning is stated in pyproject.toml itself: the suite is a measuring instrument, not a regression guard, and a failure there is its product. Keeping it in the default run would make “tests green before every commit” mean discarding findings.

“On a statute whose answers ARE known, it is right 31/35, wrong once in a way that matters, and once the spec itself is silent. That is a working instrument.”

work/conformance/RUN.md

10. What is not built, and what is limited

A teaching document that oversells is useless. Here is the honest boundary.

Not built

• The audit layer. Nothing in this system yet compares an answer to what a court actually held. There is no rulings table, no divergence scoring, no scoreboard. The spec’s §7 specifies all of it — the per-ruling record, the seven divergence types (CONSISTENT, REDEFINITION, SURPLUS, SCOPE_EXPANSION, CANON_INVERSION, RECORD_GAP, DISCRETION_EXERCISED) — and it is tracked as open work, not done work.
• The docket. The cross-site, cross-ruling comparison the project is ultimately for is designed but not built. Its shape is visible in the code: results.Actor carries machine-readable roles, names and resolved_at specifically so that “the same term resolving to a DIFFERENT roles set at a different resolved_at on the same facts” can be compared mechanically. That consumer does not exist yet. The data structure is waiting for it.
• Numeric computation of any amount. The engine compares figures the statute itself states; it computes none. No penalty amount, no tax, no cost-of-living adjustment. 6041(h) increases the $2,000 threshold for years after 2026 by the adjustment under section 1(f)(3): that is recorded as external content and cited from the threshold atom, and for a year after 2026 the engine’s comparison runs against the unadjusted base while the trace walks (h). The adjusted figure is not in the loaded text and is not invented.
• A real case, end to end. No complete case record — transcript and entered evidence — has been run through the system. The spec is explicit that assembling one is the first hard milestone, and that access, not logic, is the constraint.

Limited, by design or by circumstance

• 26 USC 6012’s express imports resolve to nothing. 6012(a)(1)(D)(ii) says “The term ‘exemption amount’ has the meaning given such term by section 151(d).” Section 151 is not loaded. So nothing resolves: no terms row is written (the definition is 151’s, not 6012’s), the references row comes back PENDING, and the usage is recorded undefined carrying the citation the statute named. The loader’s rule: “An express import to text that is not here is an EDGE, and the honest record of an edge is that it is one — never a same-word definition that happens to be loaded.” The same applies to 6012(a)(1)(B), which raises an amount by “1 additional standard deduction (within the meaning of section 63(c)(3))” — both the base and the increment live in section 63, and there is nothing here to add them to. What is missing is named: 26 USC 63.
• Version history is thin. Most loaded rows have exactly one version. The amendment machinery (amend / diff / ripple) is built and tested, but the corpus it operates on is mostly current text, and 6041(a)’s pre-2026 window is a recorded gap rather than a loaded version (§5).
• A rule whose predicate changed does not pair across a diff. It is reported as RULE_RETIRED plus RULE_ADDED, because rules has no lineage column — reported honestly rather than given an invented id.
• Two corpora, two chapters. What is loaded is 26 USC chapter 24 (3401, 3402, 3403) and chapter 61 (6011, 6012, 6041, 6041A, 6051, with 6651, 6721, 6722, 7203 and 7701(a)), plus constitutional text for the authority edge. Everything else a statute points at is an edge.
• The nested-term resolution bug (issue #14) is open. It is described in §9.3, it is known, it is reproducible, and it has not been fixed. It affects exactly the scope machinery §4 describes as the system’s most important idea.
• Whether two agreeing definitions should still stop (issue #15) is an open owner decision, not a settled behaviour.
• Which stop kind to report first when several are equally load-bearing is set by STOP_PRECEDENCE, and that ordering is a recorded decision rather than something the statute’s own text settles.

What it is not

Not a robot judge, and not a courtroom weapon. It will not tell you how a case comes out and it is not built to win one. The same discretion that lets a court stray is the discretion that lets it ignore an audit. Its power is in aggregate and in public — a pattern across many cases that cannot be explained as coincidence.

And it is built to find two things, not one: bad rulings, where a court bent a term its own statute had already defined, and bad law, where every court has to improvise the same way because the text itself is broken. The second may end up mattering more.

Where to look in the code

Every claim in this document is a claim about the code as it stands. The map:

Running it:

./scripts/up.sh                       # Postgres (codify-db, port 5433)
./scripts/migrate.sh                  # alembic upgrade head
./scripts/test.sh                     # the full suite
./scripts/test.sh -m conformance      # the measuring instrument (failures are findings)

codify run    --question is-wages --facts case.json --as-of 2024-03-15 --json
codify diff   --citation "26 USC 3401" --as-of-a 2018-03-23 --as-of-b 2026-03-01
codify ripple --term wages --scope-ref "26 USC ch. 24" --as-of 2026-03-01

Every one of those commands refuses without its date. run exits 0 for an answer, 3 for a stop, and 2 for a refusal — a stop is a result, so it does not share an exit code with a malformed request. Every command reads DATABASE_URL and refuses to guess a database.

The web UI is the same engine: POST /api/run calls the identical codify.engine.evaluate() the CLI wires up and reuses its trace serializer, so the JSON trace shape is the same one codify run --json prints. A Stop comes back as HTTP 200 with "type": "Stop" — it is a successful result. Only a malformed or unanswerable request is a 400.

← Run a case through the codified statute  ·  Try the one-question-at-a-time interview