Encoding the world's rules

# RAC file specification

Self-contained statute encoding format for tax and benefit rules.
Parsed by a recursive descent parser into a typed AST.

## File Structure

```
# path/to/section.rac - Title

# Statute text in comments
# (a) In general.— ...

param_name:
    from 2024-01-01: 100
    from 2023-01-01: 95

var_name:
    entity: TaxUnit
    from 2024-01-01: param_name * input_value
```

## Top-level declarations

| Declaration | Syntax | Purpose |
|-------------|--------|---------|
| Comment | `# ...` | Statute text, section headers |
| Definition | `name:` | Parameter or computed value (inferred from fields) |
| `entity` | `entity name:` | Entity type with fields |
| `amend` | `amend path:` | Override for reform modeling |

## Entity declarations

Define entity types with typed fields and relationships:

```
entity Person:
    age: int
    income: float
    tax_unit: -> TaxUnit

entity TaxUnit:
    members: [Person]
```

## Definitions (parameters and computed values)

No keyword prefix needed — the parser infers type from fields.
Definitions without `entity:` are parameters (pure scalar values).
Definitions with `entity:` are computed per-entity.

Optional metadata fields: `source`, `label`, `description`, `unit`.

```
# Parameter: "30 per centum of household income"
income_contribution_rate:
    from 1977-10-01: 0.30

# Computed value
snap_allotment:
    entity: Household
    from 1977-10-01:
        max(0, thrifty_food_plan_cost -
            snap_net_income * income_contribution_rate)
```

Definitions earlier in a file are in scope for later ones.

## Temporal values

Use `from YYYY-MM-DD:` for effective dates.
Use `from DATE to DATE:` for sunset provisions:

```
ctc_base_amount:
    from 1998-01-01: 400
    from 1999-01-01: 500
    from 2001-01-01: 600
    from 2003-01-01: 1000
    from 2018-01-01: 2000  # TCJA
    from 2025-01-01: 2200  # P.L. 119-21

# Sunset clause
arpa_bonus:
    from 2021-01-01 to 2025-12-31: 1600
```

## Expression syntax

Python-like with restrictions:
- Conditionals: `if cond: expr else: expr`
- Pattern matching: `match expr: pattern => result`
- Logic: `and`, `or`, `not`
- Built-ins: `max`, `min`, `abs`, `round`, `sum`, `len`, `clip`
- Field access: `person.income`
- **No magic numbers** — only -1, 0, 1, 2, 3 in formulas

```
applicable_percentage:
    entity: TaxUnit
    from 2026-01-01:
        if is_joint_return: joint_rate else: single_rate

threshold:
    entity: TaxUnit
    from 2026-01-01:
        match filing_status:
            "SINGLE" => single_threshold
            "JOINT" => joint_threshold
```

## Amendments (Reform Modeling)

```
amend gov/tax/personal_allowance:
    from 2025-04-06: 15000
```

## File Naming

Filepath = legal citation:
```
statute/7/2017/a.rac      -> 7 USC 2017(a)
statute/26/24/d/1/B.rac   -> 26 USC 24(d)(1)(B)
statute/26/32/b.rac       -> 26 USC 32(b)
```