Source: law/LAW-DSL.md
# LAW DSL v0 — a statute decomposed into elements, rules, alternatives, exceptions, and defenses
A `.law` file is the LAW-side counterpart to `neov2/cases/CASE-DSL.md`. Where a `.case` file
records a single judicial opinion as an *instance* of a statute, a `.law` file defines the
**statutory and doctrinal schema** that cases instantiate: the causes of action (`claim`),
the elements and sub-elements (`element`), statutory carve-outs (`exception`), affirmative or
doctrinal defenses (`defense`), and cross-element relational rules (`constraint`).
One file per statute: `neov2/law/<law>.law` (`18usc1962.law`, `42usc1983.law`, `15usc1.law`,
`21usc841.law`, `42usc2000e-2.law`). It is line-oriented, non-JSON, diff-friendly, and every
statutory quote (`text`) and citing-case quote (`rule`) is machine-verified against the
read-only corpus.
## The source-text contract (HARD RULE)
* Canonical text of a statute = the `text` field of its IR record
(`neochartdocroot/docroot/ir/usc/title<N>.jsonl`, record `id` = `title<N>_sec<S>`), which is
also verified byte-for-byte identical to the stripped `<pre class="linked-text">` of its
catalog page (`neochartdocroot/docroot/catalog/.../index.html`).
* Canonical text of an interpretive case = the `text` field of its IR record
(`neochartdocroot/docroot/ir/caselaw/<reporter>_<vol>.jsonl`, record `id` = `<case_path>`).
* Offsets (`@<start>..<end>`) are Python `str` indices: Unicode code points, 0-based,
end-exclusive. `text[start:end] == quote`, byte-for-byte, with zero normalization.
* The `law` header pins the statutory text version via `sha1=<source_sha1> chars=<len(text)>`.
* Source text is **never** modified. All decomposition and doctrinal synthesis live in
structured blocks and `gloss` lines around the verbatim quotes.
## Grammar
```
# comment
law <law_id> e.g. 18usc1962
cite <official citation> e.g. 18 U.S.C. § 1962
title <short title / heading>
url <full catalog url from statute_ranking.json>
address <docroot-relative catalog html path> must equal IR address
source ir/usc/title<N>.jsonl#<ir_id> sha1=<source_sha1> chars=<n>
claim <claim_id> : <boolean formula over element/exception/defense ids>
gloss <free text explaining the subsection, cause of action, or remedial posture>
constraint <id>(<el1>, <el2>[, ...]) : <summary of inter-element relation>
rule <case_path> @<start>..<end> | <verbatim quote from citing case>
gloss <free text>
element <id>[.<sub>] : and | or
name <short human-readable title>
parent <parent_id> (optional; defaults to prefix before last `.`)
text @<start>..<end> | <verbatim quote from canonical statute text>
xref <external cite> | <cross-referenced statutory definition or remedial text>
rule <case_path> @<start>..<end> | <verbatim test/rule quote from citing case>
not-required <feature expressly held NOT required for this element>
variant <genus/species> | <short description of recurring doctrinal/factual variant>
gloss <free text: doctrinal synthesis, circuit splits, burden shifting>
exception <id>[.<sub>] : exception statutory carve-out / proviso (same body as element)
defense <id>[.<sub>] : defense affirmative or doctrinal defense / immunity (same body)
```
## Semantics & Constructs
* **Hierarchy (`element <id>.<sub>`)**: Dotted IDs (`pattern.relatedness`, `pattern.continuity`,
`enterprise.continuing-unit`, `restraint.per-se`, `color-of-law.state-actor`) automatically
inherit the prefix before the last `.` as their `parent_id` if that prefix is defined in the
same `.law` file (or an explicit `parent <id>` line may override it).
* **Combinators (`and` / `or` / `exception` / `defense`)**:
* `and`: conjunctive requirement of the claim or parent element.
* `or`: alternative branch or mode of proof (e.g., `pattern` vs `debt` in RICO; `restraint.per-se`
vs `restraint.rule-of-reason` in Sherman § 1; `because-of` vs `motivating-factor` vs `impact`
in Title VII; `act.distribute` vs `act.dispense` vs `possession` in 21 U.S.C. § 841).
* `exception`: statutory proviso/exemption carved out in the text of the statute itself
(e.g., open-market securities exception in § 1962(a); judicial-officer injunctive-relief
proviso in § 1983; BFOQ / bona fide seniority system in § 2000e-2(e),(h)).
* `defense`: affirmative or judge-made defense/immunity (e.g., `qualified-immunity`,
`absolute-immunity`, `eleventh-amendment`, `statute-of-limitations`, `state-action-immunity`,
`same-decision`). Even when judge-made or cross-sectional, every `defense` and `element`
carries at least one `text @<start>..<end> | <quote>` anchored to the statutory text hook
that courts construe (plus `xref` where a companion section supplies additional text).
* **Cross-Element Constraints (`constraint`)**: Captures holdings that govern the *relationship*
between two or more elements rather than a single element in isolation (e.g.,
`distinct(person, enterprise)` under § 1962(c); `non-bootstrap(policy, deprivation)` under
§ 1983; `mode-governs-intent(restraint.per-se, intent)` under 15 U.S.C. § 1).
* **Negative Checklists (`not-required`)**: Captures judicial holdings that reject a proposed
extra requirement (e.g., no economic motive required in *NOW v. Scheidler*; no hierarchy or
chain of command required in *Boyle*; no abuse-of-governmental-power requirement in *Collins*;
no direct evidence required in *Desert Palace*).
## CLI (`neov2/tools/lawdsl.py`)
```
lawdsl.py fill <file.law>... resolve `@?` offsets in `text` and `rule` lines
lawdsl.py check <file.law|dir>... verify statutory & case quotes, headers, hierarchy, and case coverage
lawdsl.py dump <file.law> print parsed AST / SQLite loader records
```