CiteNet v1.5: legal-citation checker with hand-written weights (Core ML)

README.md

@@ -0,0 +1,90 @@
+---
+license: apache-2.0
+tags:
+- coreml
+- legal
+- citation-verification
+- hallucination-detection
+- apple-neural-engine
+- hand-written-weights
+datasets:
+- ai-law-society-lab/Legal_Phantom_Citation
+- harvard-lil/cold-cases
+---
+
+# CiteNet: a legal-citation checker whose weights were written by hand
+
+A 397,250-parameter network (13,871 nonzero) that flags legal citations that cannot exist: an invented reporter series (`F.5th`, `S.W.4th`), a court the reporter never prints (`88 F. Supp. 3d 412 (5th Cir. 2015)`), a state the regional reporter doesn't cover, or a year that doesn't fit the volume (`912 F.3d 455 (9th Cir. 1998)`; vol 912 is from 2018).
+
+**No training.** Claude (Anthropic) wrote `citenet/spec.py`: the reporters and their real series, which courts each reporter prints, the West regional map, and approximate volume→year timelines. It also wrote `citenet/net.py`, which compiles each entry into specific weights:
+
+- a conv filter that fires only when the characters spell `<digit> F.3d<space>`
+- digit decoders with weight k·10^i on digit k
+- a shared ReLU "volume thermometer" that every volume→year curve reads from
+- AND gates like `relu(8·[federal appellate reporter] + [state court] − 8)`
+
+Every nonzero weight has a name, and there was no gradient step.
+
+## Results (LePhantomCite, held-out eval split, citation level)
+
+[ai-law-society-lab/Legal_Phantom_Citation](https://huggingface.co/datasets/ai-law-society-lab/Legal_Phantom_Citation) (Liu, Stammbach & Henderson 2026, CC BY 4.0). The network was designed using only the `aux_train` split. `eval` was scored once with frozen weights.
+
+| | phantom citations caught | real citations flagged |
+|---|---|---|
+| v1.0, first and only blind run | 31 / 31 | 3 / 983 |
+| v1.5 (this release; later fixes were not blind) | 31 / 31 | 1 / 983 |
+
+- **The remaining flag** is `652 A.2d 634 (D.C. Cir. 1995)`. A.2d never prints D.C. Circuit opinions, so it is likely an error in the source brief.
+- **Out of scope:** other hallucination types (case-name mismatch, wrong pincite, misquote) need the case text. They are flagged 2 / 276 times.
+- **Hand-written vs trained:** trained from scratch, the same architecture (v1.1) ties on this benchmark, with 0 / 983 false flags. It caught 1 of 5 planted fakes of kinds the training data never shows, against 5 / 5 for the hand-written net. That 5-fake set is tiny and I wrote it, so treat it as illustrative. A naive fine-tune starting from the hand-written weights made it worse. See `results/`.
+
+**Limits.** A string-only network can tell that a citation *could* exist, not that it does. LePhantomCite's non-existent citations are structurally impossible, so it catches all of them. Real LLM fakes, such as the six citations ChatGPT invented in *Mata v. Avianca* (e.g. `925 F.3d 1339 (11th Cir. 2019)`), copy valid formats and pass. Use this as a fast first filter in front of a case-law lookup.
+
+**Real case law.** On 3.30 GB of US court opinions (291,339 decisions, COLD Cases shard 0), 0.134% of citations are flagged. Most flags look like real errors in the opinions, e.g. `387 U.S. 1 (1887)` for In re Gault (1967). They are unverified, and some are the model's own mistakes.
+
+## Speed (Core ML, Apple M5 Pro, native Swift)
+
+| | |
+|---|---|
+| 1 citation (`CiteNet_b1`, CPU) | ~50 µs |
+| 32 citations (`CiteNet_b32`, Neural Engine) | 170 µs |
+| bulk, Neural Engine (`CiteNet_lean_b512`) | ~430k citations/s |
+| bulk, GPU (`CiteNet_lean_b8192`) | ~1.38M citations/s |
+| Neural Engine + GPU together | **~1.82M citations/s** |
+| raw text, end to end: native scanner + ANE + GPU | **3.30 GB of opinions in 2.3 s** (1.44 GB/s, 1.68M citations/s) |
+
+Every build is fp16, and the labels match the fp32 PyTorch model on all 4,383 LePhantomCite citations. Fixed batch shapes matter: with `EnumeratedShapes`, Core ML ran everything on the CPU.
+
+## Files
+
+- `models/`: `CiteNet_b{1,32,512}.mlpackage` output `p_fake`, the 7 `evidence` values and the named `concepts`. `CiteNet_lean_b{512,8192}.mlpackage` output only `p_fake` and `evidence`, for bulk work. `meta.json` names every neuron; `weights.npz` holds the raw weights.
+- `citenet/`: the spec, the weight compiler and the tokenizer (`text.py`: citation extraction and normalization to 64 char codes).
+- `bench/`:
+  - `CiteScan.swift`: a byte-level Swift port of the tokenizer, byte-identical to Python (`scripts/scan_parity.py`).
+  - `stream/main.swift`: the multithreaded raw-text pipeline.
+  - `firehose.swift`, `bench.swift`: benchmarks.
+- `demo/`: a local web demo (`python demo/server.py`, localhost:8025).
+  - a live checker
+  - `/wall`: a scrolling text wall that highlights citations as they arrive, with a planted-fakes mode that reports planted, caught and missed counts
+  - `/live`: the full-speed scan
+  - `/inspect`: the neuron and filter view
+- `results/`: the v1.0 blind eval log, v1.5 eval logs, the training comparison and benchmark logs.
+
+## Use
+
+```python
+import numpy as np, coremltools as ct
+from citenet import text
+
+m = ct.models.MLModel("models/CiteNet_b32.mlpackage")
+cites = [c for _, _, c in text.extract("See Henley v. Northwind, 412 F.5th 1187 (2d Cir. 2023); "
+                                       "Bell Atl. Corp. v. Twombly, 550 U.S. 544, 570 (2007).")]
+x = np.zeros((32, 1, 1, 64), np.float16)
+x[:len(cites)] = text.encode(cites)
+p = m.predict({"codes": x})["p_fake"][:len(cites), 0]
+print(list(zip(cites, p.round(3))))   # F.5th -> ~0.99, Twombly -> ~0.02
+```
+
+To rebuild every model from the spec: `python scripts/convert.py` (torch + coremltools). The demo server expects the models in `build/`.
+
+Data: LePhantomCite (CC BY 4.0) and COLD Cases (CC0) are not included; download them from the Hub.

bench/CiteScan.swift

@@ -0,0 +1,323 @@
+// Native citation scanner + encoder: a byte-level port of citenet/text.py
+// (CITE_RE, normalize, encode). scanparity.swift checks it against Python.
+import Foundation
+
+let SEQ = 64
+let MAXCHARS = 46
+
+@inline(__always) func isDigit(_ b: UInt8) -> Bool { b >= 0x30 && b <= 0x39 }
+@inline(__always) func isUpper(_ b: UInt8) -> Bool { b >= 0x41 && b <= 0x5A }
+@inline(__always) func isLower(_ b: UInt8) -> Bool { b >= 0x61 && b <= 0x7A }
+@inline(__always) func isAlpha(_ b: UInt8) -> Bool { isUpper(b) || isLower(b) }
+
+struct Text {
+    let p: UnsafePointer<UInt8>
+    let n: Int
+    @inline(__always) subscript(_ i: Int) -> UInt8 { i < n ? p[i] : 0 }
+
+    /// Length in bytes of the whitespace character at i (Python str `\s`), or 0.
+    @inline(__always) func ws(_ i: Int) -> Int {
+        let b = self[i]
+        if b == 0x20 || (b >= 0x09 && b <= 0x0D) || (b >= 0x1C && b <= 0x1F) { return i < n ? 1 : 0 }
+        if b < 0x80 { return 0 }
+        let b1 = self[i + 1], b2 = self[i + 2]
+        if b == 0xC2 && (b1 == 0x85 || b1 == 0xA0) { return 2 }
+        if b == 0xE1 && b1 == 0x9A && b2 == 0x80 { return 3 }
+        if b == 0xE2 && b1 == 0x80 && ((b2 >= 0x80 && b2 <= 0x8A) || b2 == 0xA8 || b2 == 0xA9 || b2 == 0xAF) { return 3 }
+        if b == 0xE2 && b1 == 0x81 && b2 == 0x9F { return 3 }
+        if b == 0xE3 && b1 == 0x80 && b2 == 0x80 { return 3 }
+        return 0
+    }
+    @inline(__always) func skipWS(_ i: Int) -> Int { var j = i; while true { let w = ws(j); if w == 0 { return j }; j += w } }
+    @inline(__always) func isRSQ(_ i: Int) -> Bool { self[i] == 0xE2 && self[i + 1] == 0x80 && self[i + 2] == 0x99 }
+    @inline(__always) func isEnDash(_ i: Int) -> Bool { self[i] == 0xE2 && self[i + 1] == 0x80 && self[i + 2] == 0x93 }
+
+    /// Python `\w` for the character ending just before i (ASCII exact; non-ASCII letters count as word chars).
+    func wordBefore(_ i: Int) -> Bool {
+        if i <= 0 { return false }
+        let b = p[i - 1]
+        if b < 0x80 { return isAlpha(b) || isDigit(b) || b == 0x5F }
+        var s = i - 1
+        while s > 0 && (p[s] & 0xC0) == 0x80 { s -= 1 }
+        guard let sc = String(bytes: UnsafeBufferPointer(start: p + s, count: i - s), encoding: .utf8)?.unicodeScalars.first else { return false }
+        return sc.properties.isAlphabetic || sc.properties.numericType != nil
+    }
+    /// Python `\w` for the character starting at i.
+    func wordAt(_ i: Int) -> Bool {
+        if i >= n { return false }
+        let b = p[i]
+        if b < 0x80 { return isAlpha(b) || isDigit(b) || b == 0x5F }
+        var e = i + 1
+        while e < n && (p[e] & 0xC0) == 0x80 { e += 1 }
+        return wordBefore(e)
+    }
+
+    /// TOKEN = [A-Z][A-Za-z'’&]*\.?  |  \d+(?:d|th|st|nd|rd)\b   -> end index or -1
+    @inline(__always) func token(_ i: Int) -> Int {
+        let b = self[i]
+        if isUpper(b) {
+            var q = i + 1
+            while q < n {
+                let c = p[q]
+                if isAlpha(c) || c == 0x27 || c == 0x26 { q += 1 } else if isRSQ(q) { q += 3 } else { break }
+            }
+            if self[q] == 0x2E { q += 1 }
+            return q
+        }
+        if isDigit(b) {
+            var q = i
+            while isDigit(self[q]) { q += 1 }
+            let c0 = self[q], c1 = self[q + 1]
+            var e = -1
+            if c0 == 0x64 { e = q + 1 }                                   // d
+            else if (c0 == 0x74 && c1 == 0x68) || (c0 == 0x73 && c1 == 0x74) ||
+                    (c0 == 0x6E && c1 == 0x64) || (c0 == 0x72 && c1 == 0x64) { e = q + 2 }   // th st nd rd
+            return (e >= 0 && !wordAt(e)) ? e : -1
+        }
+        return -1
+    }
+
+    /// (?:at\s+)?\*?\d{1,8}  -> end or -1
+    @inline(__always) func starDigits(_ s: Int, _ m: Int) -> Int {
+        var t = s
+        if self[t] == 0x2A { t += 1 }
+        let d0 = t
+        while isDigit(self[t]) && t - d0 < m { t += 1 }
+        return t > d0 ? t : -1
+    }
+    @inline(__always) func pageAt(_ i: Int, maxDigits: Int) -> Int {
+        if self[i] == 0x61 && self[i + 1] == 0x74 {
+            let k = skipWS(i + 2)
+            if k > i + 2 { let r = starDigits(k, maxDigits); if r >= 0 { return r } }
+        }
+        return starDigits(i, maxDigits)
+    }
+
+    /// One CITE_RE match starting at i (i must be at a digit). Returns (end, accept) or nil;
+    /// accept = the reporter has an uppercase letter and does not open with a STOP word.
+    func match(_ i: Int) -> (Int, Bool)? {
+        var j = i
+        while isDigit(self[j]) { j += 1 }
+        if j - i > 4 { return nil }
+        let k = skipWS(j)
+        if k == j { return nil }
+        // greedy maximal tokens, at most 5, separated by at most one whitespace char
+        var ends = [Int](); ends.reserveCapacity(5)
+        var upper = [Bool](); upper.reserveCapacity(5)
+        var t = k
+        while ends.count < 5 {
+            let e = token(t)
+            if e < 0 { break }
+            ends.append(e); upper.append(isUpper(self[t]) || (upper.last ?? false))
+            t = e + ws(e)                       // \s? : at most one whitespace char
+        }
+        if ends.isEmpty { return nil }
+        for c in stride(from: ends.count - 1, through: 0, by: -1) {
+            let e = ends[c]
+            let s = skipWS(e)
+            var pg = -1
+            if self[s] == 0x2C {                                 // \s*,\s*at\s+ page  ("976 F. 2d, at 540")
+                let q = skipWS(s + 1)
+                if self[q] == 0x61 && self[q + 1] == 0x74 {
+                    let r = skipWS(q + 2)
+                    if r > q + 2 { pg = starDigits(r, 8) }
+                }
+            } else if s > e {                                    // \s+(?:at\s+)? page
+                pg = pageAt(s, maxDigits: 8)
+            }
+            if pg < 0 { continue }
+            var end = pg
+            // pincites: (?:\s*,\s*(?:at\s+)?\*?\d+(?:\s*[-–]\s*\*?\d+)?)*
+            while true {
+                var q = skipWS(end)
+                if self[q] != 0x2C { break }
+                q = skipWS(q + 1)
+                let d = pageAt(q, maxDigits: Int.max)
+                if d < 0 { break }
+                var e2 = d
+                var r = skipWS(d)
+                if self[r] == 0x2D || isEnDash(r) {
+                    r = skipWS(r + (self[r] == 0x2D ? 1 : 3))
+                    if self[r] == 0x2A { r += 1 }
+                    let d0 = r
+                    while isDigit(self[r]) { r += 1 }
+                    if r > d0 { e2 = r }
+                }
+                end = e2
+            }
+            // paren: \s*\([^()]{0,60}?\d{4}\)
+            let po = skipWS(end)
+            if self[po] == 0x28 {
+                var q = po + 1, chars = 0
+                while q < n && p[q] != 0x28 && p[q] != 0x29 && chars <= 64 {
+                    if (p[q] & 0xC0) != 0x80 { chars += 1 }
+                    q += 1
+                }
+                if q < n && p[q] == 0x29 && chars >= 4 && chars - 4 <= 60 &&
+                    isDigit(p[q - 1]) && isDigit(p[q - 2]) && isDigit(p[q - 3]) && isDigit(p[q - 4]) {
+                    end = q + 1
+                }
+            }
+            let first = Array(UnsafeBufferPointer(start: p + k, count: ends[0] - k))
+            return (end, upper[c] && !STOP.contains(first))
+        }
+        return nil
+    }
+
+    /// finditer over [lo, hi): calls emit(start, end) for each accepted citation.
+    func scan(_ lo: Int, _ hi: Int, _ emit: (Int, Int) -> Void) {
+        var i = lo
+        while i < hi {
+            if isDigit(p[i]) && !wordBefore(i) {
+                if let (e, up) = match(i) {
+                    if up { emit(i, e) }
+                    i = e
+                    continue
+                }
+                while i < hi && isDigit(p[i]) { i += 1 }   // \b fails inside the rest of this run
+                continue
+            }
+            i += 1
+        }
+    }
+}
+
+/// citenet/text.py STOP: words that open a match but never a reporter
+let STOP: Set<[UInt8]> = Set("""
+No. Nos. No Id. Id Ibid. Section Sec. In On At Page Pages Rule Rules Cir. Supp. Tr. Year Years
+East West North South And Or The Of To CA Art. Article Para. Count Counts Exhibit Ex. Doc. Dkt. ECF
+January February March April May June July August September October November December
+Jan. Feb. Mar. Apr. Jun. Jul. Aug. Sep. Sept. Oct. Nov. Dec.
+C Civ Civ. Cr Cr. Crim. Crim CV CR
+""".split(whereSeparator: { $0 == " " || $0 == "\n" }).map { Array($0.utf8) })
+
+// ---------------------------------------------------------------- normalize + encode
+let OTHERB: UInt8 = 0xFF
+
+/// Map the match bytes to one byte per character (normalize() steps 1-3: NFKC-ish,
+/// quote/dash/section mapping, whitespace collapse + strip, lowercase).
+@inline(__always) func charsOf(_ t: Text, _ s: Int, _ e: Int, into out: inout [UInt8]) {
+    out.removeAll(keepingCapacity: true)
+    var i = s
+    var pendingSpace = false
+    while i < e {
+        let w = t.ws(i)
+        if w > 0 { pendingSpace = !out.isEmpty; i += w; continue }
+        var c: UInt8
+        let b = t.p[i]
+        if b < 0x80 {
+            c = isUpper(b) ? b + 32 : (b == 0x60 ? 0x27 : b); i += 1
+        } else {
+            let b1 = t[i + 1], b2 = t[i + 2]
+            if b == 0xE2 && b1 == 0x80 && (b2 == 0x98 || b2 == 0x99) { c = 0x27; i += 3 }
+            else if b == 0xE2 && b1 == 0x80 && (b2 == 0x93 || b2 == 0x94) { c = 0x2D; i += 3 }
+            else if b == 0xC2 && b1 == 0xA7 { c = 0x73; i += 2 }
+            else {
+                c = OTHERB
+                i += 1
+                while i < e && (t.p[i] & 0xC0) == 0x80 { i += 1 }
+            }
+        }
+        if pendingSpace { out.append(0x20); pendingSpace = false }
+        out.append(c)
+    }
+}
+
+@inline(__always) func isWordB(_ c: UInt8) -> Bool { isLower(c) || isDigit(c) || c == 0x5F || c == OTHERB }
+
+let EXPL: [[UInt8]] = ["quoting", "citing", "internal", "alteration", "emphasis", "quotation", "affirmed", "aff'd",
+                       "rev'd", "cert", "vacated", "overruled", "abrogated", "superseded", "modified"].map { Array($0.utf8) }
+
+/// _EXPL: \s*\((?:quoting|citing|...|\d+ )  -> cut the string at the leftmost match
+@inline(__always) func cutExplanatory(_ s: inout [UInt8]) {
+    let n = s.count
+    var i = 0
+    while i < n {
+        if s[i] == 0x28 {
+            var hit = false
+            for w in EXPL where i + 1 + w.count <= n && s[(i + 1)..<(i + 1 + w.count)].elementsEqual(w) { hit = true; break }
+            if !hit {
+                var q = i + 1
+                while q < n && isDigit(s[q]) { q += 1 }
+                if q > i + 1 && q < n && s[q] == 0x20 { hit = true }
+            }
+            if hit {
+                var cut = i
+                while cut > 0 && s[cut - 1] == 0x20 { cut -= 1 }
+                s.removeSubrange(cut..<n)
+                return
+            }
+        }
+        i += 1
+    }
+}
+
+func normalizeChars(_ s: inout [UInt8], _ tmp: inout [UInt8]) {
+    cutExplanatory(&s)
+    // _TRAIL: (?<=[\d)])[\s.,;:]+$ | [\s,;:]+$   (leftmost position where either matches)
+    var k = s.count
+    while k > 0 && (s[k - 1] == 0x20 || s[k - 1] == 0x2E || s[k - 1] == 0x2C || s[k - 1] == 0x3B || s[k - 1] == 0x3A) { k -= 1 }
+    if k < s.count {
+        var cut = -1
+        for pos in k..<s.count {
+            let prev = pos > 0 ? s[pos - 1] : 0
+            if isDigit(prev) || prev == 0x29 { cut = pos; break }
+            var allNoDot = true
+            for q in pos..<s.count where s[q] == 0x2E { allNoDot = false; break }
+            if allNoDot { cut = pos; break }
+        }
+        if cut >= 0 { s.removeSubrange(cut..<s.count) }
+    }
+    // _JOIN: \.\s+(?=(?!at\b)[a-z]|\d+(?:d|th|st|nd|rd)\b) -> "."
+    tmp.removeAll(keepingCapacity: true)
+    var i = 0
+    let n = s.count
+    while i < n {
+        let c = s[i]
+        tmp.append(c)
+        if c == 0x2E && i + 1 < n && s[i + 1] == 0x20 {
+            let j = i + 2
+            var join = false
+            if j < n && isLower(s[j]) {
+                let isAt = s[j] == 0x61 && j + 1 < n && s[j + 1] == 0x74 && !(j + 2 < n && isWordB(s[j + 2]))
+                join = !isAt
+            } else if j < n && isDigit(s[j]) {
+                var q = j
+                while q < n && isDigit(s[q]) { q += 1 }
+                var e = -1
+                if q < n && s[q] == 0x64 { e = q + 1 }
+                else if q + 1 < n && ((s[q] == 0x74 && s[q + 1] == 0x68) || (s[q] == 0x73 && s[q + 1] == 0x74) ||
+                                       (s[q] == 0x6E && s[q + 1] == 0x64) || (s[q] == 0x72 && s[q + 1] == 0x64)) { e = q + 2 }
+                if e >= 0 && !(e < n && isWordB(s[e])) { join = true }
+            }
+            if join { i += 2; continue }
+        }
+        i += 1
+    }
+    swap(&s, &tmp)
+    if s.count > MAXCHARS {
+        let head = Array(s[0..<24]), tail = Array(s[(s.count - (MAXCHARS - 24))...])
+        s = head + tail
+    }
+}
+
+let CODE: [UInt8] = {
+    var t = [UInt8](repeating: 47, count: 256)
+    for d in 0..<10 { t[0x30 + d] = UInt8(3 + d) }
+    for l in 0..<26 { t[0x61 + l] = UInt8(13 + l) }
+    t[0x20] = 39; t[0x2E] = 40; t[0x2C] = 41; t[0x28] = 42; t[0x29] = 43; t[0x27] = 44; t[0x26] = 45; t[0x2D] = 46
+    return t
+}()
+
+/// Write BOS + codes + EOS + PAD (SEQ Float16 values) for citation bytes [s, e).
+@inline(__always) func encode(_ t: Text, _ s: Int, _ e: Int, _ dst: UnsafeMutablePointer<Float16>,
+                              _ buf: inout [UInt8], _ tmp: inout [UInt8]) {
+    charsOf(t, s, e, into: &buf)
+    normalizeChars(&buf, &tmp)
+    dst[0] = 1
+    var k = 1
+    for c in buf where k < SEQ - 1 { dst[k] = Float16(CODE[Int(c)]); k += 1 }
+    dst[k] = 2
+    k += 1
+    while k < SEQ { dst[k] = 0; k += 1 }
+}

bench/bench.swift

@@ -0,0 +1,79 @@
+// Native Core ML benchmark for the hand-written CiteNet builds.
+// usage: bench <build dir>
+import CoreML
+import Foundation
+
+let dir = URL(fileURLWithPath: CommandLine.arguments[1])
+let seq = 64
+let raw = try Data(contentsOf: dir.appendingPathComponent("bench_codes.f16"))
+let nCites = raw.count / (seq * 2)
+
+func load(_ b: Int, _ units: MLComputeUnits) throws -> MLModel {
+    let cfg = MLModelConfiguration()
+    cfg.computeUnits = units
+    return try MLModel(contentsOf: dir.appendingPathComponent("CiteNet_b\(b).mlmodelc"), configuration: cfg)
+}
+
+func batch(_ b: Int, offset: Int) throws -> MLDictionaryFeatureProvider {
+    let arr = try MLMultiArray(shape: [NSNumber(value: b), 1, 1, NSNumber(value: seq)], dataType: .float16)
+    raw.withUnsafeBytes { src in
+        let dst = arr.dataPointer
+        for i in 0..<b {
+            let c = (offset + i) % nCites
+            memcpy(dst + i * seq * 2, src.baseAddress! + c * seq * 2, seq * 2)
+        }
+    }
+    return try MLDictionaryFeatureProvider(dictionary: ["codes": arr])
+}
+
+func now() -> UInt64 { DispatchTime.now().uptimeNanoseconds }
+
+func pct(_ v: [Double], _ p: Double) -> Double { v.sorted()[min(v.count - 1, Int(Double(v.count) * p))] }
+
+let unitsName: [(String, MLComputeUnits)] = [("cpu", .cpuOnly), ("ane", .cpuAndNeuralEngine), ("gpu", .cpuAndGPU)]
+let only = CommandLine.arguments.count > 2 ? CommandLine.arguments[2] : "all"
+for b in [1, 32, 512, 2048, 8192] where only == "all" {
+    for (uname, units) in unitsName {
+        if b == 1 && uname == "gpu" { continue }          // b1/b32 plans stay on CPU for GPU units
+        if b >= 2048 && uname == "cpu" { continue }
+        let m = try load(b, units)
+        let inputs = try (0..<8).map { try batch(b, offset: $0 * b) }
+        for i in 0..<50 { _ = try m.prediction(from: inputs[i % 8]) }
+        let iters = b == 1 ? 5000 : (b == 32 ? 3000 : max(40, 300_000 / b))
+        var lat = [Double]()
+        let t0 = now()
+        for i in 0..<iters {
+            let s = now()
+            _ = try m.prediction(from: inputs[i % 8])
+            lat.append(Double(now() - s) / 1e3)
+        }
+        let total = Double(now() - t0) / 1e9
+        print(String(format: "b%-4d %@  p50 %7.1f us  p99 %7.1f us  %8.0f cites/s", b, uname,
+                     pct(lat, 0.5), pct(lat, 0.99), Double(iters * b) / total))
+    }
+}
+
+// ---- concurrent: one thread per compute unit, each with its own model, for a fixed time
+func concurrent(_ lanes: [(String, Int, MLComputeUnits)], seconds: Double) throws {
+    let models = try lanes.map { try load($0.1, $0.2) }
+    let inputs = try lanes.map { l in try (0..<4).map { try batch(l.1, offset: $0 * l.1) } }
+    for (i, m) in models.enumerated() { for j in 0..<20 { _ = try m.prediction(from: inputs[i][j % 4]) } }
+    var counts = [Int](repeating: 0, count: lanes.count)
+    let lock = NSLock()
+    let start = now(), deadline = start + UInt64(seconds * 1e9)
+    DispatchQueue.concurrentPerform(iterations: lanes.count) { i in
+        var n = 0, j = 0
+        while now() < deadline {
+            _ = try! models[i].prediction(from: inputs[i][j % 4]); j += 1; n += lanes[i].1
+        }
+        lock.lock(); counts[i] = n; lock.unlock()
+    }
+    let total = Double(now() - start) / 1e9
+    let parts = zip(lanes, counts).map { String(format: "%@ b%d %.0fk/s", $0.0.0, $0.0.1, Double($0.1) / total / 1e3) }
+    print(String(format: "concurrent %@ -> %.0f cites/s", parts.joined(separator: " + "), Double(counts.reduce(0, +)) / total))
+}
+try concurrent([("ane", 512, .cpuAndNeuralEngine)], seconds: 3)
+try concurrent([("gpu", 8192, .cpuAndGPU)], seconds: 3)
+try concurrent([("ane", 512, .cpuAndNeuralEngine), ("gpu", 8192, .cpuAndGPU)], seconds: 3)
+try concurrent([("ane", 2048, .cpuAndNeuralEngine), ("gpu", 8192, .cpuAndGPU)], seconds: 3)
+try concurrent([("ane", 512, .cpuAndNeuralEngine), ("ane", 512, .cpuAndNeuralEngine), ("gpu", 8192, .cpuAndGPU), ("gpu", 8192, .cpuAndGPU)], seconds: 3)

bench/firehose.swift

@@ -0,0 +1,78 @@
+// Firehose: push N citations through CiteNet on the ANE, the GPU, or both at once.
+// usage: firehose <build dir> <ane|gpu|ane+gpu> <n> [threads per unit, default 2]
+// Prints one JSON line. Model loading is excluded from the timing.
+import CoreML
+import Foundation
+
+let dir = URL(fileURLWithPath: CommandLine.arguments[1])
+let lanesArg = CommandLine.arguments[2]
+let target = Int(CommandLine.arguments[3]) ?? 1_000_000
+let seq = 64
+let raw = try Data(contentsOf: dir.appendingPathComponent("bench_codes.f16"))
+let nCites = raw.count / (seq * 2)
+
+struct Lane { let name: String; let batch: Int; let units: MLComputeUnits }
+let all: [String: Lane] = [
+    "ane": Lane(name: "ane", batch: 512, units: .cpuAndNeuralEngine),
+    "gpu": Lane(name: "gpu", batch: 8192, units: .cpuAndGPU),
+]
+// each unit gets `threads` lanes (own model instance each) so one lane's CPU-side
+// work overlaps the other's time on the accelerator
+let threads = CommandLine.arguments.count > 4 ? Int(CommandLine.arguments[4])! : 2
+let lanes = lanesArg.split(separator: "+").flatMap { name in (0..<threads).map { _ in all[String(name)]! } }
+
+func input(_ b: Int, offset: Int) throws -> MLDictionaryFeatureProvider {
+    let arr = try MLMultiArray(shape: [NSNumber(value: b), 1, 1, NSNumber(value: seq)], dataType: .float16)
+    raw.withUnsafeBytes { src in
+        for i in 0..<b {
+            memcpy(arr.dataPointer + i * seq * 2, src.baseAddress! + ((offset + i) % nCites) * seq * 2, seq * 2)
+        }
+    }
+    return try MLDictionaryFeatureProvider(dictionary: ["codes": arr])
+}
+
+func flagged(_ out: MLFeatureProvider, _ b: Int) -> Int {
+    // ANE outputs come back with padded rows, so walk the batch axis by its stride
+    let p = out.featureValue(for: "p_fake")!.multiArrayValue!
+    let stride = p.strides[0].intValue
+    var n = 0
+    if p.dataType == .float16 {
+        let ptr = p.dataPointer.bindMemory(to: Float16.self, capacity: b * stride)
+        for i in 0..<b where ptr[i * stride] >= 0.5 { n += 1 }
+    } else {
+        let ptr = p.dataPointer.bindMemory(to: Float.self, capacity: b * stride)
+        for i in 0..<b where ptr[i * stride] >= 0.5 { n += 1 }
+    }
+    return n
+}
+
+let models = try lanes.map { l -> MLModel in
+    let cfg = MLModelConfiguration(); cfg.computeUnits = l.units
+    return try MLModel(contentsOf: dir.appendingPathComponent("CiteNet_lean_b\(l.batch).mlmodelc"), configuration: cfg)
+}
+let inputs = try lanes.map { l in try (0..<4).map { try input(l.batch, offset: $0 * 977) } }
+for (i, m) in models.enumerated() { for j in 0..<8 { _ = try m.prediction(from: inputs[i][j % 4]) } }
+
+let lock = NSLock()
+var done = 0
+var perLane = [Int](repeating: 0, count: lanes.count)
+var flags = 0
+let t0 = DispatchTime.now().uptimeNanoseconds
+DispatchQueue.concurrentPerform(iterations: lanes.count) { i in
+    var j = 0
+    while true {
+        lock.lock()
+        if done >= target { lock.unlock(); break }
+        done += lanes[i].batch
+        lock.unlock()
+        let out = try! models[i].prediction(from: inputs[i][j % 4]); j += 1
+        let f = flagged(out, lanes[i].batch)
+        lock.lock(); perLane[i] += lanes[i].batch; flags += f; lock.unlock()
+    }
+}
+let secs = Double(DispatchTime.now().uptimeNanoseconds - t0) / 1e9
+let total = perLane.reduce(0, +)
+var byUnit: [String: Int] = [:]
+for (l, n) in zip(lanes, perLane) { byUnit[l.name, default: 0] += n }
+let laneJSON = byUnit.keys.sorted().map { "\"\($0)\": {\"batch\": \(all[$0]!.batch), \"threads\": \(threads), \"cites\": \(byUnit[$0]!)}" }.joined(separator: ", ")
+print("{\"n\": \(total), \"seconds\": \(String(format: "%.4f", secs)), \"per_sec\": \(Int(Double(total) / secs)), \"flagged\": \(flags), \"lanes\": {\(laneJSON)}}")

bench/scanparity.swift

@@ -0,0 +1,31 @@
+// scanparity <text file> <out prefix>: run the native scanner, write codes (.f16) and cites (.txt, one per line)
+import Foundation
+
+@main struct ScanParity {
+    static func main() throws {
+        let a = CommandLine.arguments
+        let data = try Data(contentsOf: URL(fileURLWithPath: a[1]), options: .alwaysMapped)
+        var cites = [String](), codes = [Float16]()
+        var buf = [UInt8](), tmp = [UInt8]()
+        let row = UnsafeMutablePointer<Float16>.allocate(capacity: SEQ)
+        let t0 = Date()
+        var n = 0
+        data.withUnsafeBytes { raw in
+            let t = Text(p: raw.bindMemory(to: UInt8.self).baseAddress!, n: raw.count)
+            t.scan(0, raw.count) { s, e in
+                encode(t, s, e, row, &buf, &tmp)
+                n += 1
+                if a.count > 2 {
+                    codes.append(contentsOf: UnsafeBufferPointer(start: row, count: SEQ))
+                    cites.append(String(decoding: UnsafeBufferPointer(start: t.p + s, count: e - s), as: UTF8.self))
+                }
+            }
+        }
+        let dt = Date().timeIntervalSince(t0)
+        print(String(format: "%d citations, %.1f MB in %.3f s -> %.0f MB/s single thread", n, Double(data.count) / 1e6, dt, Double(data.count) / 1e6 / dt))
+        if a.count > 2 {
+            try codes.withUnsafeBufferPointer { try Data(buffer: $0).write(to: URL(fileURLWithPath: a[2] + ".f16")) }
+            try (cites.map { $0.replacingOccurrences(of: "\r", with: "\\r").replacingOccurrences(of: "\n", with: "\\n") }.joined(separator: "\n")).write(toFile: a[2] + ".txt", atomically: true, encoding: .utf8)
+        }
+    }
+}

bench/stream/main.swift

@@ -0,0 +1,213 @@
+// stream: raw text -> native scanner threads -> CiteNet on the ANE and GPU, live.
+//
+// usage: stream_bin <build dir> <corpus.txt> [--loop] [--scan-threads N] [--scan-only]
+//
+// Scanner threads take ~1 MB blocks of the memory-mapped corpus, find citations
+// (CiteScan.swift, byte-identical to citenet/text.py) and pack their codes into
+// 512-row batches. Two ANE lanes (lean b512) and two GPU lanes (lean b8192, 16 batches at a
+// time) run the model. Every 100 ms a JSON line with counters, a few sampled
+// citations and newly flagged ones goes to stdout.
+import CoreML
+import Foundation
+
+let args = CommandLine.arguments
+let dir = URL(fileURLWithPath: args[1])
+let corpusURL = URL(fileURLWithPath: args[2])
+let loop = args.contains("--loop")
+let scanOnly = args.contains("--scan-only")
+let scanThreads = args.firstIndex(of: "--scan-threads").map { Int(args[$0 + 1])! } ?? 4
+let B = 512
+
+let corpus = try Data(contentsOf: corpusURL, options: .alwaysMapped)
+let base: UnsafePointer<UInt8> = corpus.withUnsafeBytes { $0.bindMemory(to: UInt8.self).baseAddress! }
+let N = corpus.count
+let T = Text(p: base, n: N)
+
+// ~1 MB blocks split on blank lines (the corpus separates opinions with "\n\n")
+var blocks = [(Int, Int)]()
+do {
+    var s = 0
+    while s < N {
+        var e = min(N, s + 1 << 20)
+        while e < N && !(base[e - 1] == 0x0A && base[e] == 0x0A) { e += 1 }
+        e = min(N, e + 1)
+        blocks.append((s, e)); s = e
+    }
+}
+
+// ---------------------------------------------------------------- batches + queue
+final class Batch {
+    let codes = UnsafeMutablePointer<Float16>.allocate(capacity: B * SEQ)
+    var start = [Int](repeating: 0, count: B)
+    var len = [Int32](repeating: 0, count: B)
+    var count = 0
+}
+
+final class Queue {
+    let cv = NSCondition()
+    var ready = [Batch]()
+    var free = [Batch]()
+    var producersLeft = scanThreads
+    init(_ n: Int) { free = (0..<n).map { _ in Batch() } }
+    func take() -> Batch {
+        cv.lock(); defer { cv.unlock() }
+        while free.isEmpty { cv.wait() }
+        return free.removeLast()
+    }
+    func push(_ b: Batch) { cv.lock(); ready.append(b); cv.broadcast(); cv.unlock() }
+    func recycle(_ bs: [Batch]) { cv.lock(); for b in bs { b.count = 0 }; free.append(contentsOf: bs); cv.broadcast(); cv.unlock() }
+    /// Up to k ready batches; waits for k unless the producers are done. Empty = finished.
+    func pop(_ k: Int) -> [Batch] {
+        cv.lock(); defer { cv.unlock() }
+        while ready.count < k && producersLeft > 0 { cv.wait() }
+        let n = min(k, ready.count)
+        let out = Array(ready.prefix(n)); ready.removeFirst(n)
+        return out
+    }
+    func producerDone() { cv.lock(); producersLeft -= 1; cv.broadcast(); cv.unlock() }
+}
+let Q = Queue(scanOnly ? 64 : 512)
+
+// ---------------------------------------------------------------- shared stats
+final class Stats {
+    let lock = NSLock()
+    var bytes = 0, cites = 0, checked = 0, flagged = 0, ane = 0, gpu = 0, passes = 0
+    var ticker = [(Int, Int32, Bool)]()           // sampled (start, len, flagged)
+    var caught = [(Int, Int32, Int, Float)]()     // (start, len, top evidence, p)
+}
+let S = Stats()
+var nextBlock = 0
+let blockLock = NSLock()
+
+// ---------------------------------------------------------------- scanner threads
+func producer() {
+    var buf = [UInt8](), tmp = [UInt8]()
+    var cur = Q.take()
+    while true {
+        blockLock.lock()
+        let idx = nextBlock; nextBlock += 1
+        blockLock.unlock()
+        if !loop && idx >= blocks.count { break }
+        let (lo, hi) = blocks[idx % blocks.count]
+        var found = 0
+        T.scan(lo, hi) { s, e in
+            encode(T, s, e, cur.codes + cur.count * SEQ, &buf, &tmp)
+            cur.start[cur.count] = s; cur.len[cur.count] = Int32(e - s)
+            cur.count += 1; found += 1
+            if cur.count == B {
+                if scanOnly { cur.count = 0 } else { Q.push(cur); cur = Q.take() }
+            }
+        }
+        S.lock.lock(); S.bytes += hi - lo; S.cites += found; S.passes = max(S.passes, idx / blocks.count); S.lock.unlock()
+    }
+    if cur.count > 0 && !scanOnly { Q.push(cur) } else { Q.recycle([cur]) }
+    Q.producerDone()
+}
+
+// ---------------------------------------------------------------- model lanes
+func lane(_ name: String, _ modelBatch: Int, _ units: MLComputeUnits) throws {
+    let cfg = MLModelConfiguration(); cfg.computeUnits = units
+    let m = try MLModel(contentsOf: dir.appendingPathComponent("CiteNet_lean_b\(modelBatch).mlmodelc"), configuration: cfg)
+    let arr = try MLMultiArray(shape: [NSNumber(value: modelBatch), 1, 1, NSNumber(value: SEQ)], dataType: .float16)
+    let input = try MLDictionaryFeatureProvider(dictionary: ["codes": arr])
+    let per = modelBatch / B
+    var sampleEvery = 0
+    while true {
+        let bs = Q.pop(per)
+        if bs.isEmpty { return }
+        let dst = arr.dataPointer.bindMemory(to: Float16.self, capacity: modelBatch * SEQ)
+        var rows = 0
+        for b in bs { memcpy(dst + rows * SEQ, b.codes, b.count * SEQ * 2); rows += b.count }
+        if rows < modelBatch { memset(dst + rows * SEQ, 0, (modelBatch - rows) * SEQ * 2) }
+        let out = try m.prediction(from: input)
+        let p = out.featureValue(for: "p_fake")!.multiArrayValue!
+        let ev = out.featureValue(for: "evidence")!.multiArrayValue!
+        let ps = p.strides[0].intValue, es = ev.strides[0].intValue, ec = ev.strides[1].intValue
+        let pp = p.dataPointer.bindMemory(to: Float16.self, capacity: modelBatch * ps)
+        let ep = ev.dataPointer.bindMemory(to: Float16.self, capacity: modelBatch * es)
+        var nflag = 0
+        var newCaught = [(Int, Int32, Int, Float)]()
+        var r = 0
+        for b in bs {
+            for i in 0..<b.count {
+                if pp[r * ps] >= 0.5 {
+                    nflag += 1
+                    if newCaught.count < 8 {
+                        var best = 0
+                        for k in 1..<7 where ep[r * es + k * ec] > ep[r * es + best * ec] { best = k }
+                        newCaught.append((b.start[i], b.len[i], best, Float(pp[r * ps])))
+                    }
+                }
+                r += 1
+            }
+        }
+        sampleEvery += 1
+        S.lock.lock()
+        S.checked += rows; S.flagged += nflag
+        if name == "ane" { S.ane += rows } else { S.gpu += rows }
+        if S.caught.count < 64 { S.caught.append(contentsOf: newCaught.prefix(64 - S.caught.count)) }
+        if S.ticker.count < 32, let b = bs.first, b.count > 0 {
+            let i = (sampleEvery * 131) % b.count
+            S.ticker.append((b.start[i], b.len[i], pp[i * ps] >= 0.5))
+        }
+        S.lock.unlock()
+        Q.recycle(bs)
+    }
+}
+
+// ---------------------------------------------------------------- JSON out
+func jstr(_ s: Int, _ e: Int) -> String {
+    let lo = max(0, s), hi = min(N, e)
+    var str = String(decoding: UnsafeBufferPointer(start: base + lo, count: max(0, hi - lo)), as: UTF8.self)
+    str = str.replacingOccurrences(of: "\\", with: "\\\\").replacingOccurrences(of: "\"", with: "\\\"")
+    str = str.unicodeScalars.map { $0.value < 0x20 ? " " : String($0) }.joined()
+    return "\"" + str + "\""
+}
+func ctxStart(_ s: Int) -> Int { var i = max(0, s - 90); while i < s && (base[i] & 0xC0) == 0x80 { i += 1 }; return i }
+func ctxEnd(_ e: Int) -> Int { var i = min(N, e + 90); while i < N && (base[i] & 0xC0) == 0x80 { i += 1 }; return i }
+
+let t0 = DispatchTime.now().uptimeNanoseconds
+func elapsed() -> Double { Double(DispatchTime.now().uptimeNanoseconds - t0) / 1e9 }
+
+let group = DispatchGroup()
+for _ in 0..<scanThreads { group.enter(); Thread { producer(); group.leave() }.start() }
+var laneErr: Error?
+if !scanOnly {
+    for (name, mb, units) in [("ane", 512, MLComputeUnits.cpuAndNeuralEngine), ("ane", 512, .cpuAndNeuralEngine),
+                              ("gpu", 8192, .cpuAndGPU), ("gpu", 8192, .cpuAndGPU)] {
+        group.enter()
+        Thread { do { try lane(name, mb, units) } catch { laneErr = error }; group.leave() }.start()
+    }
+}
+var finished = false
+DispatchQueue.global().async { group.wait(); finished = true }
+
+print("{\"start\": true, \"corpus_bytes\": \(N), \"blocks\": \(blocks.count), \"scan_threads\": \(scanThreads), \"scan_only\": \(scanOnly)}")
+fflush(stdout)
+var last = (0.0, 0, 0, 0)
+while true {
+    usleep(100_000)
+    let t = elapsed()
+    S.lock.lock()
+    let (bytes, cites, checked, flagged, ane, gpu, passes) = (S.bytes, S.cites, S.checked, S.flagged, S.ane, S.gpu, S.passes)
+    let ticker = S.ticker; S.ticker.removeAll()
+    let caught = S.caught; S.caught.removeAll()
+    S.lock.unlock()
+    let dt = t - last.0
+    let mbps = Double(bytes - last.1) / dt / 1e6, cps = Double(checked - last.2) / dt
+    let sps = Double(cites - last.3) / dt
+    last = (t, bytes, checked, cites)
+    let tick = ticker.suffix(8).map { (s, l, f) in
+        "{\"before\": \(jstr(ctxStart(s), s)), \"cite\": \(jstr(s, s + Int(l))), \"after\": \(jstr(s + Int(l), ctxEnd(s + Int(l)))), \"flag\": \(f)}"
+    }.joined(separator: ", ")
+    let cg = caught.prefix(8).map { (s, l, ev, p) in
+        "{\"cite\": \(jstr(s, s + Int(l))), \"before\": \(jstr(ctxStart(s), s)), \"ev\": \(ev), \"p\": \(String(format: "%.3f", p))}"
+    }.joined(separator: ", ")
+    let done = finished
+    print("{\"t\": \(String(format: "%.2f", t)), \"bytes\": \(bytes), \"cites\": \(cites), \"checked\": \(checked), \"flagged\": \(flagged), " +
+          "\"ane\": \(ane), \"gpu\": \(gpu), \"pass\": \(passes), \"mbps\": \(String(format: "%.1f", mbps)), \"cps\": \(Int(cps)), \"sps\": \(Int(sps)), " +
+          "\"ticker\": [\(tick)], \"caught\": [\(cg)], \"done\": \(done)}")
+    fflush(stdout)
+    if done { break }
+}
+if let e = laneErr { FileHandle.standardError.write("lane error: \(e)\n".data(using: .utf8)!); exit(1) }

citenet/net.py

@@ -0,0 +1,391 @@
+"""CiteNet: a char-level conv + ReLU MLP whose weights are all written by hand.
+
+build() compiles spec.py into weight tensors. No gradient step ever touches
+them. Layer by layer:
+
+  codes [B,1,1,64]   char codes from text.encode()
+  onehot             relu(1 - |code - k|) for k in 0..47      (no weights)
+  conv_rep  K=15     one filter per reporter abbreviation; it fires (=1) only when
+                     every character of "<digit> <abbr><space>" lines up. Anchored right
+                     after the volume, so it only scans the first ANCHOR_W columns
+  conv_float K=15    series ordinals, LEXIS, law reviews: anywhere in the string
+  conv_court K=8     circuit / district / bankruptcy / 48 state parentheticals
+  conv_num  K=6      gated digit decoders: volume (anchored at BOS) and the year
+                     before ')'; the value filter has weight k*10^i on digit k
+  max over positions -> one binary feature per filter, plus the numbers
+  fc1 concepts       reporter classes, court classes, a shared ReLU "volume
+                     thermometer", phantom-series detectors
+  fc2 rules          conjunctions such as relu(SCOTUS + circuit - 1) and the
+                     curve residuals relu(|year - curve(volume)| - tol)
+  fc3 evidence       sums each rule group; fc3b saturates it at its cap
+  fc4 logit          bias + weighted evidence -> sigmoid
+"""
+from collections import OrderedDict
+
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+from . import spec
+
+K_REP, K_COURT, K_NUM = 15, 8, 6
+ANCHOR_W = 5 + K_REP - 1      # BOS + up to 4 volume digits: template starts at columns 0..4
+GATE = 400.0        # big-M for gating curve residuals (residuals stay < 400 years)
+VGATE = 1024.0      # big-M for gating volume > vmax (3-digit volumes stay < 1000)
+AND_N = 8.0         # at most a few court detectors ever fire on one citation
+YEAR0 = 1700.0      # years are carried as (year - 1700) so they stay small in fp16
+
+
+# ------------------------------------------------------------------ helpers
+def template_filter(t, k):
+    sets = spec.parse_template(t)
+    assert len(sets) <= k, (t, len(sets), k)
+    w = np.zeros((spec.NCHAR, k), np.float32)
+    for o, allowed in enumerate(sets):
+        for c in allowed:
+            w[c, o] = 1.0
+    return w, -(len(sets) - 1.0)
+
+
+def rep_template(abbr):
+    if "_" in abbr:                      # the entry carries its own right context ("us_#", "us_at_")
+        return "#_" + abbr
+    return "#_" + abbr + "~"
+
+
+class Layer:
+    """Named-neuron builder for one dense layer: in_names -> out_names."""
+
+    def __init__(self, in_names):
+        self.idx = {n: i for i, n in enumerate(in_names)}
+        self.rows = OrderedDict()
+
+    def add(self, name, terms, bias=0.0, sat=False):
+        row = np.zeros(len(self.idx), np.float32)
+        for n, w in terms.items():
+            row[self.idx[n]] += w
+        self.rows[name] = (row, bias)
+        if sat:     # companion neuron relu(x - 1): the next layer reads min(x, 1) = x - x^hi
+            self.rows[name + "^hi"] = (row.copy(), bias - 1.0)
+
+    def tensors(self):
+        names = list(self.rows)
+        W = np.stack([self.rows[n][0] for n in names])
+        b = np.array([self.rows[n][1] for n in names], np.float32)
+        return names, W, b
+
+
+def curve_at(pts, v):
+    xs, ys = zip(*pts)
+    return float(np.interp(v, xs, ys, left=None, right=None)) if xs[0] <= v <= xs[-1] else (
+        ys[0] + (v - xs[0]) * (ys[1] - ys[0]) / (xs[1] - xs[0]) if v < xs[0]
+        else ys[-1] + (v - xs[-1]) * (ys[-1] - ys[-2]) / (xs[-1] - xs[-2]))
+
+
+def knot_readout(pts, vmax):
+    """Express curve(v) - YEAR0 as a + sum_j c_j * relu(v - knot_j), interpolating
+    the curve on the shared knot grid. The curve is held flat outside
+    [first volume, vmax]: volumes past vmax are caught by the over: neurons, and
+    the flat ends keep every residual below GATE."""
+    ks = spec.KNOTS
+    lo = pts[0][0]
+    hi = min(k for k in ks if k >= vmax)       # hold flat from the first knot past vmax
+    ys = [curve_at(pts, min(max(k, lo), hi)) - YEAR0 for k in ks]
+    assert max(ys) < GATE - 10, (pts, max(ys))
+    slopes = [(ys[j + 1] - ys[j]) / (ks[j + 1] - ks[j]) for j in range(len(ks) - 1)]
+    coef = {}
+    prev = 0.0
+    for j, s in enumerate(slopes):
+        coef["vol>%d" % ks[j]] = s - prev
+        prev = s
+    return ys[0], coef
+
+
+# ------------------------------------------------------------------ build
+def build():
+    P = OrderedDict()   # weights
+    meta = {}
+
+    # ---- conv_rep (anchored) + conv_float
+    # A reporter template "#_abbr~" starts on the last digit of the volume, which sits at
+    # positions 1-4 right after BOS, so conv_rep only looks at the first ANCHOR_W columns
+    # (5 positions). Templates that can sit anywhere (series ordinals, LEXIS, law reviews)
+    # go in conv_float, which scans the whole sequence.
+    templates = [("rep:" + a, rep_template(a)) for a, *_ in spec.REPORTERS]
+    templates += [("series:" + n, t) for n, t in spec.PHANTOM_SERIES.items()]
+    templates += [("other:" + n, t) for n, t in spec.OTHER_SOURCES.items()]
+    anchored = [(n, t) for n, t in templates if t.startswith("#_")]
+    floating = [(n, t) for n, t in templates if not t.startswith("#_")]
+    for conv, group in (("conv_rep", anchored), ("conv_float", floating)):
+        ws, bs = zip(*(template_filter(t, K_REP) for _, t in group))
+        P[conv + ".weight"] = np.stack(ws)[:, :, None, :]
+        P[conv + ".bias"] = np.array(bs, np.float32)
+    rep_names = [n for n, _ in anchored] + [n for n, _ in floating]
+    meta["anchored"], meta["floating"] = [n for n, _ in anchored], [n for n, _ in floating]
+
+    # ---- conv_court
+    court_names, cw, cb = [], [], []
+    for name, t in spec.COURTS.items():
+        w, b = template_filter(t, K_COURT)
+        court_names.append("court:" + name); cw.append(w); cb.append(b)
+    P["conv_court.weight"] = np.stack(cw)[:, :, None, :]
+    P["conv_court.bias"] = np.array(cb, np.float32)
+
+    # ---- conv_num: gates (template) and values (digit place values)
+    # the year must follow a space, '(', '.' or ',' (so "(03-1202)" docket numbers are not years)
+    # and look like 17xx-20xx (so a page number closing a "(quoting ...)" parenthetical is not one)
+    gate_t = {"vol1": "<#!", "vol2": "<##!", "vol3": "<###!", "vol4": "<####!",
+              "year": "{ (.,}1{789}##)", "year20": "{ (.,}20##)"}
+    num_names = list(gate_t) + ["vol4y"]
+    gw, gb, vw, vb = [], [], [], []
+    for name in num_names:
+        t = gate_t["vol4" if name == "vol4y" else name]
+        w, b = template_filter(t, K_NUM)
+        gw.append(w); gb.append(b)
+        v = np.zeros((spec.NCHAR, K_NUM), np.float32)
+        digit_offsets = [o for o, st in enumerate(spec.parse_template(t)) if st and st <= spec.DIGITS]
+        n = len(digit_offsets)
+        for i, o in enumerate(digit_offsets):
+            for d in range(10):
+                v[spec.DIGIT0 + d, o] = d * 10 ** (n - 1 - i)
+        vw.append(v)
+        vb.append(-YEAR0 if name in ("year", "year20", "vol4y") else 0.0)
+    P["conv_gate.weight"] = np.stack(gw)[:, :, None, :]
+    P["conv_gate.bias"] = np.array(gb, np.float32)
+    P["conv_val.weight"] = np.stack(vw)[:, :, None, :]
+    P["conv_val.bias"] = np.array(vb, np.float32)
+
+    # numbers after pooling: vol1..vol4, year, vol4y  (value*gate)  +  gates
+    feat = rep_names + court_names + ["num:" + n for n in num_names] + \
+        ["gate:" + n for n in num_names]
+    meta["features"] = feat
+
+    # ---- fc1: concepts
+    L1 = Layer(feat)
+
+    def reps(abbrs):
+        """Sum over reporter templates, minus the templates each one excludes."""
+        terms = {}
+        for a in abbrs:
+            terms["rep:" + a] = terms.get("rep:" + a, 0) + 1
+            for x in spec.EXCLUDES.get(a, []):
+                terms["rep:" + x] = terms.get("rep:" + x, 0) - 1
+        return terms
+
+    classes = sorted({r[1] for r in spec.REPORTERS})
+    for c in classes:
+        L1.add("class:" + c, reps(a for a, cls, _, _ in spec.REPORTERS if cls == c), sat=True)
+    regions = sorted(spec.REGION_STATES)
+    for r in regions:
+        L1.add("region:" + r, reps(a for a, cls, h, _ in spec.REPORTERS if cls == "REGION" and h == r), sat=True)
+    homes = sorted({h for _, cls, h, _ in spec.REPORTERS if cls == "STATE"})
+    for h in homes:
+        L1.add("home:" + h, reps(a for a, cls, hh, _ in spec.REPORTERS if cls == "STATE" and hh == h), sat=True)
+    curves = list(spec.CURVES)
+    for k in curves:
+        L1.add("is:" + k, reps(a for a, _, _, cv in spec.REPORTERS if cv == k), sat=True)
+    L1.add("is:wl", {"rep:wl": 1}, sat=True)
+    L1.add("is:lexis", {"other:lexis": 1}, sat=True)
+    # phantom series: an ordinal glued to an abbreviation that never had that series
+    alr = {"other:a.l.r.": -1}       # A.L.R. 4th..7th are real annotation series
+    def ords(k):
+        return {"series:" + n: 1 for n in spec.PHANTOM_SERIES if n.rstrip("sc") == k}
+    L1.add("phantom:4th", dict(ords("ord4"), **alr, **{"rep:" + a: -1 for a in spec.VALID_4TH}))
+    L1.add("phantom:5th", dict(ords("ord5"), **alr, **{"rep:" + a: -1 for a in spec.VALID_5TH}))
+    L1.add("phantom:6th+", dict(ords("ord6+"), **alr))
+    known = reps(a for a, *_ in spec.REPORTERS)
+    known.update({"other:" + n: 1 for n in spec.OTHER_SOURCES})
+    for s in spec.PHANTOM_SERIES:
+        known["series:" + s] = 1
+    L1.add("known_source", known)
+    # an explanatory parenthetical ("(quoting X, 550 U.S. at 556 ...)") carries other reporters:
+    # volume checks are switched off for these strings (series checks still apply)
+    L1.add("expl", {"court:" + n: 1 for n in spec.COURTS if n.startswith("expl_")})
+    # courts
+    # Louisiana's state appeals courts are named "La. App. 3d Cir.": not a federal circuit
+    L1.add("court:circuit", {"court:circuit": 1, "court:circuit_dc": 1, "court:circuit_fed": 1, "court:state_la": -AND_N})
+    L1.add("court:district", {"court:district_x": 1, "court:district_d": 1, "court:state_d.c": -1,
+                              "court:dc_app": -1, "court:dc_mun": -1, "court:circuit_dc": -1})
+    L1.add("court:bankruptcy", {"court:bankruptcy": 1, "court:bap": 1})
+    for s in spec.STATES:
+        L1.add("state:" + s, {"court:state_" + s: 1, **({"court:dc_app": 1, "court:dc_mun": 1} if s == "d.c" else {})})
+    L1.add("court:year_only", {"court:year_only": 1})
+    # numbers: volume, year (minus 1700), presence flags
+    L1.add("volume", {"num:vol1": 1, "num:vol2": 1, "num:vol3": 1, "num:vol4": 1})
+    L1.add("has_volume", {"gate:vol1": 1, "gate:vol2": 1, "gate:vol3": 1, "gate:vol4": 1})
+    # year and vol4y are relu'd here and clamped to [0, 400] in fc2 as x - x_hi, so a strange
+    # 4-digit number ("3128 EDA 2007") can never push a gated rule past its big-M
+    yr = {"num:year": 1, "num:year20": 1}
+    expl = {"court:" + n: -AND_N for n in spec.COURTS if n.startswith("expl_")}
+    L1.add("year", yr)
+    L1.add("year_hi", yr, bias=-400.0)
+    L1.add("has_year", dict({"gate:year": 1, "gate:year20": 1}, **expl), sat=True)   # not inside "(quoting ...)"
+    L1.add("vol4y", {"num:vol4y": 1})
+    L1.add("vol4y_hi", {"num:vol4y": 1}, bias=-400.0)
+    L1.add("future", yr, bias=-(spec.LAST_YEAR - YEAR0 + 0.5))
+    # shared volume thermometer relu(v - knot), over 1-3 digit volumes only
+    # (4-digit volumes are years in WL/Lexis cites, or past every vmax)
+    L1.add("volume3", {"num:vol1": 1, "num:vol2": 1, "num:vol3": 1})
+    L1.add("has_vol4", {"gate:vol4": 1})
+    vol_terms = {"num:vol1": 1, "num:vol2": 1, "num:vol3": 1}
+    for k in spec.KNOTS[:-1]:
+        L1.add("vol>%d" % k, vol_terms, bias=-float(k))
+    names1, W1, b1 = L1.tensors()
+    P["fc1.weight"], P["fc1.bias"] = W1, b1
+    meta["concepts"] = names1
+
+    # ---- fc2: rules
+    L2 = Layer(names1)
+
+    def sat(name, w):
+        return {name: w, name + "^hi": -w}
+
+    def merge(*ds):
+        out = {}
+        for d in ds:
+            for n, w in d.items():
+                out[n] = out.get(n, 0) + w
+        return out
+    fed_courts = {"court:circuit": 1, "court:district": 1, "court:bankruptcy": 1}
+    any_state = {"state:" + s: 1 for s in spec.STATES}
+
+    def conj(name, cls, bad, group):
+        # AND(class, any bad court): the class is weighted by AND_N so that several
+        # court detectors firing at once can never fire the rule on their own
+        L2.add(name, merge(sat(cls, AND_N), bad), bias=-AND_N)
+        meta.setdefault("groups", {}).setdefault(group, []).append(name)
+
+    conj("mm:SCOTUS", "class:SCOTUS", dict(fed_courts, **any_state), "court_mismatch")
+    conj("mm:FEDAPP", "class:FEDAPP", dict({"court:district": 1, "court:bankruptcy": 1}, **any_state),
+         "court_mismatch")
+    # pre-1970s style wrote district courts as "(D.C. Minn. 1960)" / "(D.C. 1968)"
+    no_dc = {k: v for k, v in any_state.items() if k != "state:d.c"}
+    conj("mm:FEDAPP_OLD", "class:FEDAPP_OLD", no_dc, "court_mismatch")
+    conj("mm:FEDDIST", "class:FEDDIST", {"court:circuit": 1}, "court_mismatch")   # "(Mass. 1953)" = D. Mass. in older opinions
+    conj("mm:BANKR", "class:BANKR", no_dc, "court_mismatch")
+    conj("mm:REGION_fed", "class:REGION", fed_courts, "court_mismatch")
+    conj("mm:STATE_fed", "class:STATE", fed_courts, "court_mismatch")
+    for r in regions:
+        bad = {"state:" + s: 1 for s in spec.STATES if s not in spec.REGION_STATES[r]}
+        conj("mm:region_" + r, "region:" + r, bad, "state_mismatch")
+    for h in homes:
+        bad = {"state:" + s: 1 for s in spec.STATES if s != h}
+        conj("mm:home_" + h, "home:" + h, bad, "state_mismatch")
+
+    # volume/year curves: relu(+-(year - curve(vol)) - tol), gated by reporter and has_year
+    for k in curves:
+        c = spec.CURVES[k]
+        a, coef = knot_readout(c["pts"], c["vmax"])
+        gate = merge(sat("is:" + k, GATE), sat("has_year", GATE), {"has_volume": GATE})
+        late = {n: -w for n, w in coef.items()}
+        late["year"], late["year_hi"] = 1.0, -1.0
+        for n, w in gate.items():
+            late[n] = late.get(n, 0) + w
+        cut, extra = spec.EARLY_TOL.get(k, (None, 0.0))
+        if cut:   # tol(v) = tol + extra * (cut - min(v, cut)) / cut, with min(v, cut) = v - relu(v - cut)
+            widen = {"volume3": extra / cut, "vol>%d" % cut: -extra / cut}
+            for n, w in widen.items():
+                late[n] = late.get(n, 0) + w
+        L2.add("late:" + k, late, bias=-a - c["tol"] - extra - 3 * GATE)
+        early = dict(coef)
+        early["year"], early["year_hi"] = -1.0, 1.0
+        for n, w in gate.items():
+            early[n] = early.get(n, 0) + w
+        if cut:
+            for n, w in widen.items():
+                early[n] = early.get(n, 0) + w
+        L2.add("early:" + k, early, bias=a - c["tol"] - extra - 3 * GATE)
+        meta["groups"].setdefault("volume_year", []).extend(["late:" + k, "early:" + k])
+        L2.add("over:" + k, merge({"volume3": 1.0, "expl": -VGATE}, sat("is:" + k, VGATE)), bias=-c["vmax"] - VGATE)
+        L2.add("over4:" + k, merge({"has_vol4": 1.0, "expl": -2.0}, sat("is:" + k, 1.0)), bias=-1.0)
+        meta["groups"].setdefault("volume_missing", []).extend(["over:" + k, "over4:" + k])
+    # WL / Lexis: the 4-digit "volume" is the year the database added the opinion:
+    # the decision year, or the next year for late-December opinions
+    for src in ("wl", "lexis"):
+        g = merge(sat("is:" + src, GATE), sat("has_year", GATE))
+        L2.add("late:" + src, merge({"year": 1.0, "year_hi": -1.0, "vol4y": -1.0, "vol4y_hi": 1.0}, g), bias=-0.5 - 2 * GATE)
+        L2.add("early:" + src, merge({"year": -1.0, "year_hi": 1.0, "vol4y": 1.0, "vol4y_hi": -1.0}, g), bias=-1.5 - 2 * GATE)
+        meta["groups"]["volume_year"].extend(["late:" + src, "early:" + src])
+    for p in ("phantom:4th", "phantom:5th", "phantom:6th+"):
+        L2.add("r:" + p, {p: 1})
+        meta["groups"].setdefault("phantom_series", []).append("r:" + p)
+    L2.add("r:future", {"future": 1})
+    meta["groups"]["future_year"] = ["r:future"]
+    L2.add("r:unknown", {"has_volume": 1, "known_source": -1})
+    meta["groups"]["unknown_reporter"] = ["r:unknown"]
+    names2, W2, b2 = L2.tensors()
+    P["fc2.weight"], P["fc2.bias"] = W2, b2
+    meta["rules"] = names2
+
+    # ---- fc3: evidence sums and their overflow above cap; fc4: logit
+    L3 = Layer(names2)
+    for ev, w, cap, _ in spec.EVIDENCE:
+        terms = {n: 1.0 for n in meta["groups"][ev]}
+        L3.add("ev:" + ev, terms)
+        L3.add("ovf:" + ev, terms, bias=-cap)
+    names3, W3, b3 = L3.tensors()
+    P["fc3.weight"], P["fc3.bias"] = W3, b3
+
+    # saturated evidence = ev - ovf  (a fixed difference, written as a linear layer)
+    E = len(spec.EVIDENCE)
+    Ws = np.zeros((E, len(names3)), np.float32)
+    for i, (ev, *_rest) in enumerate(spec.EVIDENCE):
+        Ws[i, names3.index("ev:" + ev)] = 1
+        Ws[i, names3.index("ovf:" + ev)] = -1
+    P["fc_sat.weight"], P["fc_sat.bias"] = Ws, np.zeros(E, np.float32)
+    P["fc4.weight"] = np.array([[w for _, w, _, _ in spec.EVIDENCE]], np.float32)
+    P["fc4.bias"] = np.array([spec.BIAS], np.float32)
+    meta["evidence"] = [e[0] for e in spec.EVIDENCE]
+    return P, meta
+
+
+class CiteNet(nn.Module):
+    def __init__(self, P):
+        super().__init__()
+        def conv(name):
+            w = torch.from_numpy(P[name + ".weight"])
+            m = nn.Conv2d(w.shape[1], w.shape[0], (1, w.shape[3]))
+            return m
+        def fc(name):
+            w = torch.from_numpy(P[name + ".weight"])
+            return nn.Linear(w.shape[1], w.shape[0])
+        self.conv_rep, self.conv_float, self.conv_court = conv("conv_rep"), conv("conv_float"), conv("conv_court")
+        self.conv_gate, self.conv_val = conv("conv_gate"), conv("conv_val")
+        self.fc1, self.fc2, self.fc3 = fc("fc1"), fc("fc2"), fc("fc3")
+        self.fc_sat, self.fc4 = fc("fc_sat"), fc("fc4")
+        self.register_buffer("alphabet", torch.arange(spec.NCHAR, dtype=torch.float32).view(1, -1, 1, 1))
+        self.load_weights(P)
+
+    def load_weights(self, P):
+        sd = {k: torch.from_numpy(np.ascontiguousarray(v)) for k, v in P.items()}
+        sd["alphabet"] = self.alphabet
+        self.load_state_dict(sd)
+
+    def forward(self, codes):
+        x = F.relu(1.0 - torch.abs(codes - self.alphabet))           # one-hot [B,48,1,L]
+        xa = F.relu(1.0 - torch.abs(codes[:, :, :, :ANCHOR_W] - self.alphabet))   # slice the codes, not the one-hot
+        rep = F.relu(self.conv_rep(xa)).amax(dim=(2, 3))
+        flt = F.relu(self.conv_float(x)).amax(dim=(2, 3))
+        court = F.relu(self.conv_court(x)).amax(dim=(2, 3))
+        gate = F.relu(self.conv_gate(x))
+        num = (self.conv_val(x) * gate).amax(dim=(2, 3))
+        gate = gate.amax(dim=(2, 3))
+        f = torch.cat([rep, flt, court, num, gate], dim=1)
+        concepts = F.relu(self.fc1(f))
+        rules = F.relu(self.fc2(concepts))
+        evidence = self.fc_sat(F.relu(self.fc3(rules)))
+        p_fake = torch.sigmoid(self.fc4(evidence))
+        return p_fake, evidence, concepts
+
+
+def make():
+    P, meta = build()
+    net = CiteNet(P).eval()
+    return net, meta
+
+
+def param_counts(net):
+    total = sum(p.numel() for p in net.parameters())
+    nonzero = sum(int((p != 0).sum()) for p in net.parameters())
+    return total, nonzero

citenet/spec.py

@@ -0,0 +1,357 @@
+"""Hand-written knowledge that net.py compiles into weights.
+
+Nothing in this file is learned. Every table below is written from general
+knowledge of U.S. citation practice (Bluebook forms, West's National Reporter
+System, approximate reporter volume/year timelines). net.py turns each entry
+into specific conv filters and ReLU neurons, so this file is the model's
+source code.
+"""
+
+# ---------------------------------------------------------------- alphabet
+PAD, BOS, EOS = 0, 1, 2
+DIGIT0 = 3                      # '0'..'9' -> 3..12
+LETTER_A = 13                   # 'a'..'z' -> 13..38
+SPACE, DOT, COMMA, LPAREN, RPAREN, APOS, AMP, DASH, OTHER = range(39, 48)
+NCHAR = 48
+SEQ = 64                        # BOS + up to 46 chars + EOS, then PAD (room for K-1 pad)
+MAXCHARS = 46
+
+PUNCT = {" ": SPACE, ".": DOT, ",": COMMA, "(": LPAREN, ")": RPAREN,
+         "'": APOS, "&": AMP, "-": DASH}
+
+DIGITS = set(range(DIGIT0, DIGIT0 + 10))
+LETTERS = set(range(LETTER_A, LETTER_A + 26))
+ALL = set(range(NCHAR))
+NONDIGIT = ALL - DIGITS
+
+
+def code(ch):
+    if ch.isdigit():
+        return DIGIT0 + int(ch)
+    if "a" <= ch <= "z":
+        return LETTER_A + ord(ch) - ord("a")
+    return PUNCT.get(ch, OTHER)
+
+
+# ---------------------------------------------------------------- template DSL
+# A template is a string. Plain characters match themselves; these match a class:
+#   #  any digit           _  space            !  any non-digit (incl. BOS/EOS/PAD)
+#   <  BOS                 ~  end of token: space, EOS or ','
+#   @  letter or '.'       %  digit, 'a' or '*' (page, "at" short form, star page)
+#   {tdh}  any of the listed characters
+CLASSES = {
+    "#": DIGITS, "_": {SPACE}, "!": NONDIGIT, "<": {BOS},
+    "~": {SPACE, EOS, COMMA}, "@": LETTERS | {DOT},
+    "%": DIGITS | {code("a"), code("*")},
+}
+
+
+def parse_template(t):
+    """Template string -> list of allowed-code sets, one per offset."""
+    out, i = [], 0
+    while i < len(t):
+        ch = t[i]
+        if ch == "{":
+            j = t.index("}", i)
+            out.append({code(c) for c in t[i + 1:j]})
+            i = j + 1
+            continue
+        out.append(CLASSES[ch] if ch in CLASSES else {code(ch)})
+        i += 1
+    return out
+
+
+# ---------------------------------------------------------------- reporters
+# (normalized abbreviation, class, home state or region, curve key)
+# Classes:
+#   SCOTUS     U.S. Supreme Court reporters: court parenthetical holds only a year
+#   FEDAPP     modern federal appellate reporters: circuit courts only
+#   FEDAPP_OLD F. / F.2d: early volumes also printed district-court opinions
+#   FEDDIST    federal district-court reporters
+#   BANKR      Bankruptcy Reporter
+#   FEDSPEC    other federal (claims court, Federal Cases)
+#   REGION     West regional reporter; the 'home' field is the region key
+#   STATE      a state's own reporter; the 'home' field is the state
+#   WL         Westlaw / Lexis database cites: the "volume" is the year
+REPORTERS = [
+    ("u.s.", "SCOTUS", None, "us"), ("us_#", "SCOTUS", None, "us"), ("us_at_", "SCOTUS", None, "us"),
+    ("s.ct.", "SCOTUS", None, "sct"), ("s ct", "SCOTUS", None, "sct"),
+    ("dall.", "SCOTUS", None, None), ("cranch", "SCOTUS", None, None),
+    ("wheat.", "SCOTUS", None, None), ("pet.", "SCOTUS", None, None),
+    ("how.", "SCOTUS", None, None), ("black", "SCOTUS", None, None),
+    ("wall.", "SCOTUS", None, None),
+    ("l.ed.", "SCOTUS", None, "led"), ("l.ed.2d", "SCOTUS", None, "led2"),
+
+    ("f.", "FEDAPP_OLD", None, "f1"), ("f.2d", "FEDAPP_OLD", None, "f2"),
+    ("f.3d", "FEDAPP", None, "f3"), ("f.4th", "FEDAPP", None, "f4"),
+    ("f.app'x", "FEDAPP", None, "fappx"), ("f.appx", "FEDAPP", None, "fappx"),
+    ("fed.appx.", "FEDAPP", None, "fappx"), ("fed.appx", "FEDAPP", None, "fappx"),
+    ("fed.app'x", "FEDAPP", None, "fappx"), ("fed.app.", "FEDAPP", None, "fappx"),
+
+    ("f.supp.", "FEDDIST", None, "fs1"), ("f.supp_#", "FEDDIST", None, "fs1"), ("f.supp_at_", "FEDDIST", None, "fs1"),
+    ("f.supp.2d", "FEDDIST", None, "fs2"), ("f.supp.3d", "FEDDIST", None, "fs3"),
+    ("f.supp 2d", "FEDDIST", None, "fs2"), ("f.supp 3d", "FEDDIST", None, "fs3"),   # "F. Supp 2d"
+    ("f.r.d.", "FEDDIST", None, "frd"),
+    ("b.r.", "BANKR", None, "br"),
+    ("fed.cl.", "FEDSPEC", None, None), ("ct.cl.", "FEDSPEC", None, None),
+    ("cl.ct.", "FEDSPEC", None, None), ("f.cas.", "FEDSPEC", None, None),
+    ("ct.int'l", "FEDSPEC", None, None), ("m.j.", "FEDSPEC", None, None),
+
+    ("a.", "REGION", "A", None), ("a.2d", "REGION", "A", "a2"), ("a.3d", "REGION", "A", "a3"),
+    ("n.e.", "REGION", "NE", None), ("n.e.2d", "REGION", "NE", "ne2"), ("n.e.3d", "REGION", "NE", "ne3"),
+    ("n.w.", "REGION", "NW", None), ("n.w.2d", "REGION", "NW", "nw2"), ("n.w.3d", "REGION", "NW", None),
+    ("p.", "REGION", "P", None), ("p", "REGION", "P", None),
+    ("p.2d", "REGION", "P", "p2"), ("p.3d", "REGION", "P", "p3"),
+    ("s.e.", "REGION", "SE", None), ("s.e.2d", "REGION", "SE", "se2"), ("s.e.3d", "REGION", "SE", None),
+    ("s.w.", "REGION", "SW", None), ("s.w.2d", "REGION", "SW", "sw2"), ("s.w.3d", "REGION", "SW", "sw3"),
+    ("so.", "REGION", "SO", None), ("so.2d", "REGION", "SO", "so2"), ("so.3d", "REGION", "SO", "so3"),
+
+    ("cal.rptr.", "STATE", "cal", "cr1"), ("cal.rptr.2d", "STATE", "cal", "cr2"),
+    ("cal.rptr.3d", "STATE", "cal", "cr3"),
+    ("cal.", "STATE", "cal", None), ("cal.2d", "STATE", "cal", None), ("cal.3d", "STATE", "cal", None),
+    ("cal.4th", "STATE", "cal", None), ("cal.5th", "STATE", "cal", None),
+    ("cal.app.", "STATE", "cal", None), ("cal.app.2d", "STATE", "cal", None),
+    ("cal.app.3d", "STATE", "cal", None), ("cal.app.4th", "STATE", "cal", None),
+    ("cal.app.5th", "STATE", "cal", None),
+    ("n.y.s.", "STATE", "n.y", None), ("n.y.s.2d", "STATE", "n.y", "nys2"),
+    ("n.y.s.3d", "STATE", "n.y", "nys3"),
+    ("n.y.", "STATE", "n.y", None), ("n.y.2d", "STATE", "n.y", None), ("n.y.3d", "STATE", "n.y", None),
+    ("a.d.", "STATE", "n.y", None), ("a.d.2d", "STATE", "n.y", None), ("a.d.3d", "STATE", "n.y", None),
+    ("misc.2d", "STATE", "n.y", None), ("misc.3d", "STATE", "n.y", None),
+    ("mass.", "STATE", "mass", None), ("mass.app.ct.", "STATE", "mass", None),
+    ("mass.app.", "STATE", "mass", None),
+    ("ill.", "STATE", "ill", None), ("ill.2d", "STATE", "ill", None), ("ill.app.", "STATE", "ill", None),
+    ("ill.app.2d", "STATE", "ill", None), ("ill.app.3d", "STATE", "ill", None),
+    ("ill.dec.", "STATE", "ill", None), ("ind.", "STATE", "ind", None),
+    ("ind.app.", "STATE", "ind", None), ("okla.", "STATE", "okla", None),
+    ("va.", "STATE", "va", None), ("va.app.", "STATE", "va", None), ("va.cir.", "STATE", "va", None),
+    ("pa.", "STATE", "pa", None), ("pa.super.", "STATE", "pa", None), ("pa.commw.", "STATE", "pa", None),
+    ("n.j.", "STATE", "n.j", None), ("n.j.super.", "STATE", "n.j", None),
+    ("wash.", "STATE", "wash", None), ("wash.2d", "STATE", "wash", None),
+    ("wash.app.", "STATE", "wash", None), ("wash.app.2d", "STATE", "wash", None),
+    ("ohio st.3d", "STATE", "ohio", None), ("ohio app.3d", "STATE", "ohio", None),
+    ("md.", "STATE", "md", None), ("md.app.", "STATE", "md", None),
+    ("n.c.", "STATE", "n.c", None), ("n.c.app.", "STATE", "n.c", None),
+    ("ga.", "STATE", "ga", None), ("ga.app.", "STATE", "ga", None),
+    ("kan.", "STATE", "kan", None), ("kan.app.", "STATE", "kan", None),
+    ("kan.app.2d", "STATE", "kan", None),
+    ("mich.", "STATE", "mich", None), ("mich.app.", "STATE", "mich", None),
+    ("wis.2d", "STATE", "wis", None), ("conn.", "STATE", "conn", None),
+    ("conn.app.", "STATE", "conn", None), ("tex.", "STATE", "tex", None),
+    ("s.c.", "STATE", "s.c", None), ("r.i.", "STATE", "r.i", None),
+    ("colo.", "STATE", "colo", None), ("ariz.", "STATE", "ariz", None),
+    ("or.", "STATE", "or", None), ("or.app.", "STATE", "or", None),
+
+    # v1.5: state official reports, period-free official styles, compact West abbreviations
+    ("wn.", "STATE", "wash", None), ("wn.2d", "STATE", "wash", None), ("wn.app.", "STATE", "wash", None),
+    ("wn.app.2d", "STATE", "wash", None),
+    ("neb.", "STATE", "neb", None), ("neb.app.", "STATE", "neb", None), ("n.m.", "STATE", "n.m", None),
+    ("nev.", "STATE", "nev", None), ("minn.", "STATE", "minn", None), ("ark.", "STATE", "ark", None),
+    ("ark.app.", "STATE", "ark", None), ("idaho", "STATE", "idaho", None), ("mont.", "STATE", "mont", None),
+    ("ohio st.", "STATE", "ohio", None), ("ohio st.2d", "STATE", "ohio", None), ("ohio app.", "STATE", "ohio", None),
+    ("ohio app.2d", "STATE", "ohio", None), ("ala.", "STATE", "ala", None), ("ala.app.", "STATE", "ala", None),
+    ("la.", "STATE", "la", None), ("iowa", "STATE", "iowa", None), ("miss.", "STATE", "miss", None),
+    ("wis.", "STATE", "wis", None), ("w.va.", "STATE", "w.va", None), ("vt.", "STATE", "vt", None),
+    ("mo.", "STATE", "mo", None), ("mo.app.", "STATE", "mo", None), ("n.h.", "STATE", "n.h", None),
+    ("ky.", "STATE", "ky", None), ("tenn.", "STATE", "tenn", None), ("tenn.app.", "STATE", "tenn", None),
+    ("del.", "STATE", "del", None), ("me.", "STATE", "me", None), ("haw.", "STATE", "haw", None),
+    ("wyo.", "STATE", "wyo", None), ("utah", "STATE", "utah", None), ("utah 2d", "STATE", "utah", None),
+    ("n.d.", "STATE", "n.d", None), ("s.d.", "STATE", "s.d", None), ("alaska", "STATE", "alaska", None),
+    ("ny", "STATE", "n.y", None), ("ny2d", "STATE", "n.y", None), ("ny3d", "STATE", "n.y", None),
+    ("n y 2d", "STATE", "n.y", None), ("ad2d", "STATE", "n.y", None), ("ad3d", "STATE", "n.y", None),
+    ("a d 2d", "STATE", "n.y", None), ("app.div.", "STATE", "n.y", None), ("app div", "STATE", "n.y", None),
+    ("app.div.2d", "STATE", "n.y", None), ("misc.", "STATE", "n.y", None), ("misc 2d", "STATE", "n.y", None),
+    ("misc 3d", "STATE", "n.y", None), ("misc.rep.", "STATE", "n.y", None), ("nys2d", "STATE", "n.y", "nys2"),
+    ("nys3d", "STATE", "n.y", "nys3"),
+    ("f2d", "FEDAPP_OLD", None, "f2"), ("f3d", "FEDAPP", None, "f3"), ("f4th", "FEDAPP", None, "f4"),
+    ("a2d", "REGION", "A", "a2"), ("a3d", "REGION", "A", "a3"), ("ne2d", "REGION", "NE", "ne2"),
+    ("ne3d", "REGION", "NE", "ne3"), ("nw2d", "REGION", "NW", "nw2"), ("p2d", "REGION", "P", "p2"),
+    ("p3d", "REGION", "P", "p3"), ("se2d", "REGION", "SE", "se2"), ("sw2d", "REGION", "SW", "sw2"),
+    ("sw3d", "REGION", "SW", "sw3"), ("so2d", "REGION", "SO", "so2"), ("so3d", "REGION", "SO", "so3"),
+
+    ("wl", "WL", None, "wl"),
+]
+
+# A template that only counts when none of these also fired ("f.supp 2" is a prefix of "f.supp 2d").
+EXCLUDES = {"f.supp_#": ["f.supp 2d", "f.supp 3d"]}
+
+# Generic series detectors. A series ordinal glued to an abbreviation and then
+# followed by a page ("x.4th 12") or a short form ("x.4th at"). "4th" and "5th"
+# are only real for these reporters; 6th..9th are never real.
+VALID_4TH = ["f.4th", "f4th", "cal.4th", "cal.app.4th"]
+VALID_5TH = ["cal.5th", "cal.app.5th"]
+# "f.5th 12", "f.5th at", "f.5th, at 12", "f.5th *12"; and "utah 4th 279" (no period before the ordinal)
+PHANTOM_SERIES = {}
+for _k, _o in (("ord4", "4"), ("ord5", "5"), ("ord6+", "{6789}")):
+    PHANTOM_SERIES.update({_k: "@" + _o + "th_%", _k + "s": "@_" + _o + "th_%",          # "f.5th 12" / "utah 4th 279"
+                           _k + "c": "@" + _o + "th,_%", _k + "sc": "@_" + _o + "th,_%"})  # "f.5th, at 12"
+
+# Non-case sources and database cites that should not be marked unknown.
+OTHER_SOURCES = {
+    "lexis": "lexis~", "fed.reg.": "#_fed.reg.~", "fr": "#_fr~",
+    "u.s.c.": "#_u.s.c.", "c.f.r.": "#_c.f.r.", "stat.": "#_stat.~",
+    "ferc": "#_ferc~", "i&n": "n.dec.~", "t.c.": "#_t.c.",
+    "law review": "l.rev.~", "law journal": "l.j.~", "u.s.app.d.c.": "u.s.app.d.c.",
+    "c.m.r.": "#_c.m.r.~", "cmr": "#_cmr~", "vet.app.": "#_vet.app.~",
+    "b.t.a.": "#_b.t.a.~", "fed.cir.": "#_fed.cir.~", "c.c.p.a.": "#_c.c.p.a.~",
+    "o.s.": "#_o.s.~", "ok neutral": "#_ok_", "ok civ app": "#_ok civ app", "op.o.l.c.": "#_op.o.l.c.~",
+    "op.att'y": "#_op.att'y", "a.l.r.": "#_a.l.r.",       # A.L.R. runs 1st..7th and Fed.
+    # v1.5: non-case sources that turn up constantly in opinions
+    "ilcs": "#_ilcs~", "nlrb": "#_nlrb~", "uscma": "#_uscma~", "cong.rec.": "#_cong.rec.~", "l.r.a.": "#_l.r.a.",
+    "r.s.": "#_r.s.~", "burns": "#_burns~", "ops.cal.atty": "#_ops.cal.atty", "d.p.r.": "#_d.p.r.~", "dpr": "#_dpr~",
+    "j.t.s.": "#_j.t.s.~", "mal": "#_mal~", "ut neutral": "#_ut_", "ut app": "#_ut app", "nd neutral": "#_nd_",
+    "ny slip op": "#_ny slip op", "johns.": "#_johns.", "wend.": "#_wend.~", "cow.": "#_cow.~", "barb.": "#_barb.~",
+    "hun": "#_hun~", "paige": "#_paige~", "pick.": "#_pick.~", "cush.": "#_cush.~", "met.": "#_met.~",
+    "gray": "#_gray~", "allen": "#_allen~", "binn.": "#_binn.~", "watts": "#_watts~",
+}
+
+# ---------------------------------------------------------------- courts
+# West regions. N.D. and S.D. are left out on purpose: "(N.D. 2005)" and
+# "(N.D. Cal. 2005)" share a prefix, and the district detector owns that prefix.
+REGION_STATES = {
+    "A": ["conn", "del", "me", "md", "n.h", "n.j", "pa", "r.i", "vt", "d.c"],
+    "NE": ["ill", "ind", "mass", "n.y", "ohio"],
+    "NW": ["iowa", "mich", "minn", "neb", "wis"],
+    "P": ["alaska", "ariz", "cal", "colo", "haw", "idaho", "kan", "mont", "nev",
+          "n.m", "okla", "or", "utah", "wash", "wyo"],
+    "SE": ["ga", "n.c", "s.c", "va", "w.va"],
+    "SW": ["ark", "ky", "mo", "tenn", "tex"],
+    "SO": ["ala", "fla", "la", "miss"],
+}
+STATES = [s for v in REGION_STATES.values() for s in v]
+UNDOTTED = {"ohio", "iowa", "utah", "idaho", "alaska"}
+
+
+def state_template(s):
+    if s == "d.c":
+        return "(d.c.{ 0123456789}"   # D.C. Court of Appeals: "(D.C. 2005)", "(D.C.2005)"
+    if s in UNDOTTED:
+        return "(" + s + "{ .}"
+    return "(" + s + "."
+
+
+COURTS = {
+    # federal courts of appeals: an ordinal ending in t/d/h then " cir."
+    "circuit": "{tdh}_cir{.c }", "circuit_dc": "d.c.cir{. }", "circuit_fed": "fed.cir{. }",
+    # district courts: "(N.D. Cal.", "(S.D.N.Y.", "(D. Mass." -> "(d.mass."
+    "district_x": "({nsewmc}.d.@", "district_d": "(d.@",
+    "bankruptcy": "bankr.", "bap": "b.a.p.",
+    "year_only": "(####)",
+    # parentheticals that hold other citations: explanatory, parallel cites, subsequent history
+    "expl_quoting": "(quoting", "expl_citing": "(citing", "expl_internal": "(interna",
+    "expl_alteration": "(alterat", "expl_emphasis": "(emphasi", "expl_quotation": "(quotati",
+    "expl_par1": "(#_", "expl_par2": "(##_", "expl_par3": "(###_",
+    "expl_affirmed": "(affirme", "expl_affd": "(aff'd", "expl_revd": "(rev'd", "expl_cert": "(cert",
+    "expl_vacated": "(vacated", "expl_overruled": "(overrul", "expl_abrogated": "(abrogat",
+    "expl_superseded": "(superse", "expl_modified": "(modifie",
+}
+COURTS.update({"state_" + s: state_template(s) for s in STATES})
+COURTS.update({"dc_app": "(d.c.app", "dc_mun": "(d.c.mun"})   # "(D.C. App. 1968)", "(D.C. Mun. App. 1950)"
+
+# ---------------------------------------------------------------- volume -> year
+# Approximate (volume, decision year) anchors, written from memory of landmark
+# cases and series start/end dates (e.g. 347 U.S. = 1954, 467 U.S. = 1984,
+# F.3d runs 1993-2021). tol is the allowed gap in years before a cite looks
+# off; vmax is the highest volume that exists (2026).
+CURVES = {
+    # 1-4 U.S. (Dallas) span 1754-1806, so early volumes get extra tolerance (see EARLY_TOL)
+    "us": dict(tol=2.5, vmax=612, pts=[
+        (1, 1785), (2, 1792), (3, 1797), (4, 1801), (5, 1803), (9, 1809), (13, 1815), (17, 1819), (22, 1824), (60, 1857), (83, 1873),
+        (100, 1879), (118, 1886), (163, 1896), (198, 1905), (249, 1919), (268, 1925),
+        (304, 1938), (323, 1944), (347, 1954), (372, 1963), (384, 1966), (410, 1973),
+        (438, 1978), (467, 1984), (490, 1989), (505, 1992), (521, 1997), (531, 2000),
+        (543, 2005), (554, 2008), (558, 2010), (567, 2012), (576, 2015), (585, 2018),
+        (590, 2020), (597, 2022), (603, 2024), (612, 2027)]),
+    "sct": dict(tol=1.5, vmax=147, pts=[(1, 1880.5), (147, 2026.5)]),   # Oct-Term volume v spans v+1879..v+1880
+    "led": dict(tol=4, vmax=100, pts=[
+        (1, 1795), (2, 1805), (3, 1812), (4, 1818), (5, 1821), (6, 1825), (7, 1828), (8, 1832),
+        (9, 1835.5), (10, 1839), (15, 1857), (21, 1873), (41, 1896), (49, 1905), (63, 1919), (82, 1938),
+        (98, 1954), (100, 1956)]),
+    "led2": dict(tol=2.5, vmax=226, pts=[
+        (1, 1956), (16, 1966), (35, 1973), (81, 1984), (131, 1995), (167, 2007), (173, 2009),
+        (192, 2015), (213, 2022), (226, 2026)]),
+    "f1": dict(tol=3, vmax=300, pts=[(1, 1880), (100, 1900), (200, 1912), (300, 1924)]),
+    "f2": dict(tol=2.5, vmax=999, pts=[
+        (1, 1924), (50, 1931), (100, 1938), (150, 1945), (200, 1952), (250, 1957),
+        (300, 1962), (350, 1965), (400, 1968), (450, 1971), (500, 1974), (550, 1977),
+        (600, 1979), (650, 1981), (700, 1983), (750, 1985), (800, 1986), (850, 1988),
+        (900, 1990), (950, 1991), (999, 1993)]),
+    "f3": dict(tol=2, vmax=999, pts=[
+        (1, 1993), (50, 1995), (100, 1996.5), (150, 1998), (200, 1999.5), (250, 2001),
+        (300, 2002), (350, 2003.5), (400, 2005), (450, 2006), (500, 2007), (550, 2008.5),
+        (600, 2010), (650, 2011), (700, 2012.5), (750, 2014), (800, 2015), (850, 2017),
+        (900, 2018), (950, 2020), (999, 2021)]),
+    "f4": dict(tol=1.5, vmax=185, pts=[(1, 2021), (50, 2022.7), (100, 2024), (150, 2025.4), (200, 2026.8)]),
+    "fs1": dict(tol=3, vmax=999, pts=[
+        (1, 1932), (100, 1951), (200, 1962), (300, 1969), (400, 1975), (500, 1980),
+        (600, 1984), (700, 1988), (800, 1992), (900, 1995), (999, 1998)]),
+    "fs2": dict(tol=2, vmax=999, pts=[
+        (1, 1998), (100, 2000), (200, 2002), (300, 2004), (400, 2005.5), (500, 2007),
+        (600, 2009), (700, 2010), (800, 2011), (900, 2012.5), (999, 2014)]),
+    "fs3": dict(tol=2.5, vmax=850, pts=[
+        (1, 2014), (100, 2015), (200, 2016.5), (300, 2018), (400, 2019.5), (500, 2020.5),
+        (600, 2022), (700, 2023.5), (800, 2025)]),
+    "fappx": dict(tol=2, vmax=900, pts=[
+        (1, 2001), (100, 2004), (200, 2006.5), (300, 2008), (400, 2010.5), (500, 2012.5),
+        (600, 2015), (700, 2017), (800, 2019.5), (860, 2021), (900, 2022)]),
+    "br": dict(tol=3, vmax=700, pts=[
+        (1, 1979), (100, 1989), (200, 1996), (300, 2003), (400, 2009), (500, 2013),
+        (600, 2019), (660, 2024), (700, 2027)]),
+    "frd": dict(tol=4, vmax=360, pts=[(1, 1940), (50, 1970), (100, 1983.5), (150, 1993), (200, 2001), (250, 2008),
+                                      (300, 2014), (340, 2022), (360, 2026)]),
+    "a2": dict(tol=3, vmax=999, pts=[
+        (1, 1938), (100, 1953), (200, 1964), (300, 1973), (400, 1979), (500, 1985),
+        (600, 1991), (700, 1997), (800, 2002), (900, 2006), (999, 2010)]),
+    "a3": dict(tol=3, vmax=340, pts=[(1, 2010), (100, 2014), (200, 2019), (300, 2024), (340, 2026)]),
+    "ne2": dict(tol=3, vmax=999, pts=[
+        (1, 1936), (100, 1951), (200, 1964), (300, 1973), (400, 1980), (500, 1986.5),
+        (600, 1992), (700, 1998), (800, 2003.5), (900, 2009), (999, 2014)]),
+    "ne3": dict(tol=3, vmax=290, pts=[(1, 2014), (100, 2018), (200, 2022), (290, 2026)]),
+    "nw2": dict(tol=3, vmax=999, pts=[
+        (1, 1942), (100, 1960), (200, 1972), (300, 1980.5), (400, 1987), (500, 1993),
+        (600, 1999.5), (700, 2005), (800, 2011), (900, 2017), (999, 2023)]),
+    "p2": dict(tol=3, vmax=999, pts=[
+        (1, 1931), (100, 1940), (200, 1949), (300, 1956), (400, 1965), (500, 1972),
+        (600, 1979), (700, 1985), (800, 1990.5), (900, 1995), (999, 2000)]),
+    "p3": dict(tol=3, vmax=590, pts=[(1, 2000), (100, 2004.5), (200, 2009), (300, 2013), (400, 2017), (500, 2021.5), (590, 2026)]),
+    "se2": dict(tol=3, vmax=930, pts=[
+        (1, 1939), (100, 1957.5), (200, 1973.5), (300, 1983), (400, 1991), (500, 1998),
+        (600, 2004), (700, 2010.5), (800, 2017), (900, 2023), (930, 2026)]),
+    "sw2": dict(tol=3, vmax=999, pts=[
+        (1, 1928), (100, 1937), (200, 1947), (300, 1957), (400, 1966), (500, 1973.5),
+        (600, 1980), (700, 1985.5), (800, 1990.5), (900, 1995), (999, 1999)]),
+    "sw3": dict(tol=3, vmax=740, pts=[(1, 1999), (100, 2003), (200, 2006), (300, 2009.5), (400, 2013), (500, 2016), (600, 2020), (700, 2024), (740, 2026)]),
+    "so2": dict(tol=3, vmax=999, pts=[
+        (1, 1941), (100, 1958), (200, 1967), (300, 1974), (400, 1981), (500, 1987),
+        (600, 1992), (700, 1997), (800, 2001.5), (900, 2005), (999, 2008)]),
+    "so3": dict(tol=3, vmax=430, pts=[(1, 2008), (100, 2012.5), (200, 2016), (300, 2020.5), (400, 2025), (430, 2026)]),
+    "cr1": dict(tol=3, vmax=286, pts=[(1, 1959), (100, 1972), (200, 1984), (286, 1991)]),
+    "cr2": dict(tol=2, vmax=135, pts=[(1, 1991), (50, 1996), (100, 2000), (135, 2003)]),
+    "cr3": dict(tol=3, vmax=345, pts=[(1, 2003), (100, 2009), (200, 2016), (300, 2022), (345, 2026)]),
+    "nys2": dict(tol=3, vmax=999, pts=[
+        (1, 1938), (100, 1950), (200, 1960), (300, 1969), (400, 1977.5), (500, 1986),
+        (600, 1993.5), (700, 1999.5), (800, 2005), (900, 2010), (999, 2014)]),
+    "nys3": dict(tol=3, vmax=240, pts=[(1, 2014), (100, 2019), (200, 2024), (240, 2026)]),
+}
+LAST_YEAR = 2026      # anything later is in the future
+
+# Extra tolerance for the first volumes of the oldest reporters: tol + extra * (cut - v) / cut for v < cut
+EARLY_TOL = {"us": (10, 20.0), "led": (10, 6.0)}
+
+# Shared "volume thermometer": every curve is read out of these ReLU knots.
+KNOTS = [0, 2, 4, 6, 8, 10, 15, 20, 30, 40, 50, 60, 75, 90, 100, 125, 150, 175, 200, 250, 300, 350,
+         400, 450, 500, 550, 600, 650, 700, 750, 800, 850, 900, 950, 1000]
+
+# ---------------------------------------------------------------- evidence -> logit
+# Each evidence neuron saturates at `cap`; the logit is bias + sum(weight * value).
+EVIDENCE = [
+    # name,              weight, cap, meaning
+    ("phantom_series",    9.0, 1.0, "series that was never published (F.5th, S.W.4th, ...)"),
+    ("court_mismatch",    7.0, 1.0, "reporter never prints that court's opinions"),
+    ("state_mismatch",    7.0, 1.0, "regional or state reporter does not cover that state"),
+    ("volume_year",       2.5, 3.0, "years between the cited year and that volume's timeline"),
+    ("volume_missing",    7.0, 1.0, "volume number beyond the last one published"),
+    ("future_year",       7.0, 1.0, "decided after " + str(LAST_YEAR)),
+    ("unknown_reporter",  2.0, 1.0, "reporter abbreviation not recognized"),
+]
+BIAS = -4.0

citenet/text.py

@@ -0,0 +1,77 @@
+"""Tokenizer side: normalize a citation string and turn it into char codes.
+
+This is the only code that runs outside the network, the same role a BPE
+tokenizer plays for an LLM. Everything after the char codes happens inside
+the Core ML model.
+"""
+import re
+import unicodedata
+
+import numpy as np
+
+from . import spec
+
+_JOIN = re.compile(r"\.\s+(?=(?!at\b)[a-z]|\d+(?:d|th|st|nd|rd)\b)")
+# parentheticals that carry other citations, not this one's court and year: cut them off
+EXPL = ("quoting", "citing", "internal", "alteration", "emphasis", "quotation", "affirmed", "aff'd",
+        "rev'd", "cert", "vacated", "overruled", "abrogated", "superseded", "modified")
+_EXPL = re.compile(r"\s*\((?:" + "|".join(re.escape(w) for w in EXPL) + r"|\d+ )")
+_TRAIL = re.compile(r"(?<=[\d)])[\s.,;:]+$|[\s,;:]+$")
+
+
+def normalize(cite: str) -> str:
+    s = unicodedata.normalize("NFKC", cite)
+    s = s.replace("’", "'").replace("‘", "'").replace("`", "'")
+    s = s.replace("–", "-").replace("—", "-").replace("§", "s")
+    s = re.sub(r"\s+", " ", s).strip().lower()
+    m = _EXPL.search(s)
+    if m:
+        s = s[:m.start()]
+    s = _TRAIL.sub("", s)
+    s = _JOIN.sub(".", s)          # "F. Supp. 2d" -> "f.supp.2d", "S. Ct." -> "s.ct."
+    if len(s) > spec.MAXCHARS:     # keep the head (volume/reporter) and the tail (court, year)
+        s = s[:24] + s[-(spec.MAXCHARS - 24):]
+    return s
+
+
+def encode(cites, seq=spec.SEQ) -> np.ndarray:
+    """List of raw citation strings -> float32 codes [N, 1, 1, seq]."""
+    out = np.full((len(cites), 1, 1, seq), spec.PAD, dtype=np.float32)
+    for i, c in enumerate(cites):
+        s = normalize(c)
+        codes = [spec.BOS] + [spec.code(ch) for ch in s] + [spec.EOS]
+        out[i, 0, 0, :len(codes)] = codes
+    return out
+
+
+# ---------------------------------------------------------------- extraction
+_TOKEN = r"(?:[A-Z][A-Za-z'’&]*\.?|\d+(?:d|th|st|nd|rd)\b)"
+CITE_RE = re.compile(
+    r"\b(?P<vol>\d{1,4})\s+"
+    r"(?P<rep>" + _TOKEN + r"(?:\s?" + _TOKEN + r"){0,4})"
+    r"(?:\s*,\s*at\s+|\s+(?:at\s+)?)(?P<page>\*?\d{1,8})"        # "976 F. 2d, at 540" too
+    r"(?P<pin>(?:\s*,\s*(?:at\s+)?\*?\d+(?:\s*[-–]\s*\*?\d+)?)*)"
+    r"(?P<paren>\s*\((?:[^()]{0,60}?)\d{4}\))?"
+)
+
+
+# words that open a match but never a reporter: "No. 12 Section 3", "325 East 42nd", "5 July 2010"
+STOP = set("""No. Nos. No Id. Id Ibid. Section Sec. In On At Page Pages Rule Rules Cir. Supp. Tr. Year Years
+East West North South And Or The Of To CA Art. Article Para. Count Counts Exhibit Ex. Doc. Dkt. ECF
+January February March April May June July August September October November December
+Jan. Feb. Mar. Apr. Jun. Jul. Aug. Sep. Sept. Oct. Nov. Dec.
+C Civ Civ. Cr Cr. Crim. Crim CV CR""".split())         # docket numbers: "70 Civ 1113", "69 C 173"
+_FIRST = re.compile(_TOKEN)
+
+
+def extract(text: str):
+    """Find reporter-style citations in free text. Returns [(start, end, cite)]."""
+    out = []
+    for m in CITE_RE.finditer(text):
+        rep = m.group("rep")
+        if not any(ch.isupper() for ch in rep):
+            continue
+        if _FIRST.match(rep).group(0) in STOP:
+            continue
+        out.append((m.start(), m.end(), m.group(0)))
+    return out

demo/index.html

@@ -0,0 +1,186 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>CiteNet</title>
+<style>
+:root {
+  --bg: #f7f6f2; --panel: #ffffff; --ink: #1c1b19; --muted: #77746b; --line: #e6e3da;
+  --ok: #1f7a4d; --ok-bg: #e2f2e8; --bad: #c2321f; --bad-bg: #fbe3de; --warn: #a86a00; --warn-bg: #fbeed0;
+  --accent: #2f4fd6; --gpu: #1f7a4d;
+  --mono: ui-monospace, "SF Mono", Menlo, monospace;
+  --serif: "Iowan Old Style", Palatino, Georgia, serif;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #141412; --panel: #1c1b19; --ink: #ecebe6; --muted: #918e85; --line: #2d2c28;
+    --ok: #4fc487; --ok-bg: #1c3326; --bad: #ff7a66; --bad-bg: #42201a; --warn: #f0b545; --warn-bg: #3b2f17;
+    --accent: #8ea2ff; --gpu: #4fc487;
+  }
+}
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--bg); color: var(--ink); font: 15px/1.5 -apple-system, BlinkMacSystemFont, system-ui, sans-serif; }
+.wrap { max-width: 860px; margin: 0 auto; padding: 36px 20px 48px; }
+h1 { margin: 0; font-size: 30px; letter-spacing: -0.02em; }
+.lede { color: var(--muted); margin: 4px 0 22px; }
+.lede a { color: var(--ink); }
+.samples { display: flex; gap: 6px; align-items: center; margin-bottom: 8px; color: var(--muted); font-size: 13px; flex-wrap: wrap; }
+.samples button { font: inherit; font-size: 13px; border: 1px solid var(--line); background: var(--panel); color: var(--ink); padding: 4px 10px; border-radius: 999px; cursor: pointer; }
+.samples button.on { border-color: var(--ink); }
+.editor { position: relative; height: 340px; min-height: 200px; border: 1px solid var(--line); border-radius: 12px; background: var(--panel); }
+.editor .backdrop, .editor textarea {
+  position: absolute; inset: 0; margin: 0; padding: 16px 18px; font: 17px/1.65 var(--serif);
+  white-space: pre-wrap; overflow-wrap: break-word; overflow-y: auto; border: 0;
+}
+.editor .backdrop { color: transparent; pointer-events: none; }
+.editor textarea { background: transparent; color: var(--ink); resize: none; outline: none; caret-color: var(--accent); }
+mark { color: transparent; border-radius: 3px; }
+mark.ok { background: var(--ok-bg); }
+mark.phantom { background: var(--bad-bg); box-shadow: inset 0 -2px 0 var(--bad); }
+mark.unknown { background: var(--warn-bg); }
+mark.hot { outline: 2px solid var(--bad); }
+.status { margin: 12px 2px 6px; font-size: 14px; color: var(--muted); font-variant-numeric: tabular-nums; }
+.status b { color: var(--ink); font-weight: 600; }
+.hits { list-style: none; margin: 0; padding: 0; }
+.hits li { display: grid; grid-template-columns: 10px minmax(0, 1fr); gap: 2px 12px; padding: 9px 2px; border-top: 1px solid var(--line); }
+.hits li:first-child { border-top: 0; }
+.hits .d { width: 10px; height: 10px; border-radius: 50%; margin-top: 6px; background: var(--bad); }
+.hits .d.unknown { background: var(--warn); }
+.hits .c { font: 13.5px var(--mono); overflow-wrap: anywhere; }
+.hits .w { grid-column: 2; color: var(--muted); font-size: 14px; }
+.none { color: var(--muted); font-size: 14px; padding: 6px 2px; }
+.speed { margin-top: 34px; padding-top: 24px; border-top: 1px solid var(--line); display: flex; gap: 20px; align-items: center; flex-wrap: wrap; }
+.speed button { font: 600 15px -apple-system, system-ui, sans-serif; border: 0; background: var(--ink); color: var(--bg); padding: 11px 18px; border-radius: 10px; cursor: pointer; }
+.speed .out { flex: 1; min-width: 240px; }
+.big { font-size: 34px; font-weight: 700; letter-spacing: -0.03em; font-variant-numeric: tabular-nums; line-height: 1.1; }
+.small { color: var(--muted); font-size: 13.5px; }
+.bar { display: flex; height: 6px; border-radius: 3px; overflow: hidden; margin-top: 8px; background: var(--line); }
+.bar .ane { background: var(--accent); }
+.bar .gpu { background: var(--gpu); }
+.foot { margin-top: 34px; color: var(--muted); font-size: 13px; }
+.foot a { color: inherit; }
+@media (max-width: 600px) { .wrap { padding: 24px 16px 40px; } .big { font-size: 28px; } }
+</style>
+</head>
+<body>
+<div class="wrap">
+  <h1>CiteNet</h1>
+  <div class="lede">Flags legal citations that cannot exist. <span id="params">256k</span> weights written by hand, no training, running on Core ML.
+    <a href="/live">Live: scan 3.3 GB of real case law →</a> <a href="/wall">Watch it read →</a></div>
+
+  <div class="samples">Try:
+    <button data-sample="brief">Planted fakes</button>
+    <button data-sample="lepc">Real brief (LePhantomCite)</button>
+    <button data-sample="mata">Mata v. Avianca</button>
+  </div>
+  <div class="editor">
+    <div class="backdrop" id="backdrop"></div>
+    <textarea id="ta" spellcheck="false" placeholder="Paste a brief…"></textarea>
+  </div>
+
+  <div class="status" id="status">&nbsp;</div>
+  <ul class="hits" id="hits"></ul>
+
+  <div class="speed">
+    <button id="fire">Check 1,000,000 citations</button>
+    <div class="out">
+      <div class="big" id="fire-n">–</div>
+      <div class="small" id="fire-s">Neural Engine + GPU, native Core ML</div>
+      <div class="bar" id="bar"></div>
+    </div>
+  </div>
+
+  <div class="foot">LePhantomCite eval: 31/31 phantom citations caught, 1 of 983 real ones flagged.
+    Green means the citation is possible, not that the case exists; the Mata v. Avianca fakes copy real formats and pass.
+    <a href="/inspect">Inspect the neurons</a></div>
+</div>
+
+<script>
+const $ = (id) => document.getElementById(id);
+const ta = $("ta"), bd = $("backdrop");
+const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+let items = [], inflight = false, dirty = false, hot = -1;
+
+function paint() {
+  const t = ta.value; let out = "", pos = 0;
+  items.forEach((it, i) => {
+    out += esc(t.slice(pos, it.start)) +
+      `<mark class="${it.status}${i === hot ? " hot" : ""}">${esc(t.slice(it.start, it.end))}</mark>`;
+    pos = it.end;
+  });
+  bd.innerHTML = out + esc(t.slice(pos)) + " \n";
+  // grow the editor to fit the text (the backdrop holds the same text, so its height is the content height)
+  const ed = ta.parentElement;
+  ed.style.height = "auto";
+  bd.style.position = "static";
+  const h = Math.min(Math.max(bd.scrollHeight + 2, 200), 620);
+  bd.style.position = "";
+  ed.style.height = h + "px";
+  bd.scrollTop = ta.scrollTop;
+}
+
+function render(r) {
+  const bad = items.filter(i => i.status === "phantom").length;
+  const unit = r.model.includes("ANE") ? "the Neural Engine" : "the CPU";
+  const ms = r.model_ms < 1 ? r.model_ms.toFixed(2) : r.model_ms.toFixed(1);
+  $("status").innerHTML = r.n
+    ? `<b>${r.n}</b> citations · <b style="color:var(--bad)">${bad}</b> phantom · checked in <b>${ms} ms</b> on ${unit}`
+    : "No citations found.";
+  const flagged = items.map((it, i) => [it, i]).filter(([it]) => it.status !== "ok");
+  $("hits").innerHTML = flagged.length
+    ? flagged.map(([it, i]) => `<li data-i="${i}"><span class="d ${it.status}"></span><span class="c">${esc(it.cite)}</span>` +
+        `<span class="w">${esc(it.why.join("; "))}</span></li>`).join("")
+    : (r.n ? `<div class="none">Every citation is structurally possible.</div>` : "");
+  $("hits").querySelectorAll("li").forEach(li => {
+    li.onmouseenter = () => { hot = +li.dataset.i; paint(); };
+    li.onmouseleave = () => { hot = -1; paint(); };
+  });
+}
+
+async function check() {
+  if (inflight) { dirty = true; return; }
+  inflight = true; dirty = false;
+  const r = await fetch("/check", { method: "POST", body: JSON.stringify({ text: ta.value }) }).then(r => r.json());
+  items = r.items; paint(); render(r);
+  inflight = false;
+  if (dirty) check();
+}
+
+async function loadSample(kind) {
+  document.querySelectorAll("[data-sample]").forEach(b => b.classList.toggle("on", b.dataset.sample === kind));
+  const r = await fetch("/sample?kind=" + kind).then(r => r.json());
+  ta.value = r.text; ta.scrollTop = 0;
+  await check();
+}
+
+document.querySelectorAll("[data-sample]").forEach(b => b.onclick = () => loadSample(b.dataset.sample));
+ta.addEventListener("input", check);
+ta.addEventListener("scroll", () => { bd.scrollTop = ta.scrollTop; });
+
+$("fire").onclick = async () => {
+  $("fire-n").textContent = "…"; $("bar").innerHTML = "";
+  const r = await fetch("/firehose?n=1000000&lanes=ane%2Bgpu").then(r => r.json());
+  const t0 = performance.now();
+  const tick = (t) => {
+    const f = Math.min(1, (t - t0) / 600);
+    $("fire-n").textContent = Math.round(r.n * f).toLocaleString();
+    if (f < 1) return requestAnimationFrame(tick);
+    $("fire-n").textContent = `${r.n.toLocaleString()} in ${Math.round(r.seconds * 1000)} ms`;
+  };
+  requestAnimationFrame(tick);
+  const ane = r.lanes.ane?.cites || 0, gpu = r.lanes.gpu?.cites || 0;
+  $("fire-s").textContent = `${(r.per_sec / 1e6).toFixed(2)}M citations/s · Neural Engine ${Math.round(100 * ane / r.n)}% + GPU ${Math.round(100 * gpu / r.n)}%`;
+  $("bar").innerHTML = `<div class="ane" style="width:${100 * ane / r.n}%"></div><div class="gpu" style="width:${100 * gpu / r.n}%"></div>`;
+};
+
+fetch("/info").then(r => r.json()).then(i => { $("params").textContent = Math.round(i.params / 1000) + "k"; });
+const q = new URLSearchParams(location.search);
+// one silent request first: the Neural Engine takes ~10 ms to wake after idle, and the
+// first number on screen should be the steady-state one
+fetch("/check", { method: "POST", body: JSON.stringify({ text: "347 U.S. 483 (1954). ".repeat(12) }) })
+  .then(() => loadSample(q.get("sample") || "brief"))
+  .then(() => { if (q.get("fire")) $("fire").click(); });
+</script>
+</body>
+</html>

demo/inspect.html

@@ -0,0 +1,368 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>CiteNet</title>
+<style>
+:root {
+  --bg: #f6f5f1; --panel: #ffffff; --ink: #1c1b19; --muted: #6b6860; --line: #e4e1d8;
+  --ok: #1f7a4d; --ok-bg: #dff1e6; --bad: #c2321f; --bad-bg: #fbe1dc; --warn: #a86a00; --warn-bg: #fbedcc;
+  --accent: #2f4fd6; --accent-bg: #e6eafc; --cell: #2f4fd6; --grid: #eeece6;
+  --mono: ui-monospace, "SF Mono", Menlo, monospace;
+  --text: "Iowan Old Style", "Palatino", Georgia, serif;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #141412; --panel: #1d1c1a; --ink: #ecebe6; --muted: #9a978e; --line: #2f2e2a;
+    --ok: #4fc487; --ok-bg: #1d3528; --bad: #ff7a66; --bad-bg: #44211b; --warn: #f0b545; --warn-bg: #3d3018;
+    --accent: #8ea2ff; --accent-bg: #252c4d; --cell: #8ea2ff; --grid: #2a2926;
+  }
+}
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--bg); color: var(--ink); font: 15px/1.45 -apple-system, BlinkMacSystemFont, "Inter", system-ui, sans-serif; }
+header { padding: 22px 28px 8px; display: flex; align-items: baseline; gap: 18px; flex-wrap: wrap; }
+h1 { margin: 0; font-size: 26px; letter-spacing: -0.02em; }
+header .tag { color: var(--muted); }
+header .tag b { color: var(--ink); font-weight: 600; }
+.stats { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 12px; padding: 10px 28px 16px; }
+.stat { background: var(--panel); border: 1px solid var(--line); border-radius: 10px; padding: 12px 14px; }
+.stat .k { color: var(--muted); font-size: 12px; text-transform: uppercase; letter-spacing: .06em; }
+.stat .v { font-size: 28px; font-weight: 650; letter-spacing: -0.02em; font-variant-numeric: tabular-nums; }
+.stat .s { color: var(--muted); font-size: 13px; }
+main { display: grid; grid-template-columns: minmax(0, 1.25fr) minmax(0, 1fr); gap: 16px; padding: 0 28px 20px; }
+.panel { background: var(--panel); border: 1px solid var(--line); border-radius: 12px; padding: 14px 16px; min-width: 0; }
+.panel h2 { font-size: 13px; text-transform: uppercase; letter-spacing: .07em; color: var(--muted); margin: 0 0 10px; font-weight: 600; }
+.toolbar { display: flex; gap: 8px; flex-wrap: wrap; margin-bottom: 10px; align-items: center; }
+button { font: inherit; font-size: 13px; border: 1px solid var(--line); background: var(--bg); color: var(--ink); padding: 6px 11px; border-radius: 8px; cursor: pointer; }
+button:hover { border-color: var(--accent); }
+button.primary { background: var(--accent); color: #fff; border-color: var(--accent); }
+.editor { position: relative; height: 470px; border: 1px solid var(--line); border-radius: 10px; background: var(--bg); }
+.editor .backdrop, .editor textarea {
+  position: absolute; inset: 0; margin: 0; padding: 14px 16px; font: 17px/1.6 var(--text); white-space: pre-wrap; overflow-wrap: break-word;
+  overflow-y: auto; border: 0; letter-spacing: 0;
+}
+.editor .backdrop { color: transparent; pointer-events: none; }
+.editor textarea { background: transparent; color: var(--ink); resize: none; outline: none; caret-color: var(--accent); }
+mark { color: transparent; border-radius: 3px; padding: 1px 0; }
+mark.ok { background: var(--ok-bg); box-shadow: inset 0 -2px 0 var(--ok); }
+mark.phantom { background: var(--bad-bg); box-shadow: inset 0 -2px 0 var(--bad); }
+mark.unknown { background: var(--warn-bg); box-shadow: inset 0 -2px 0 var(--warn); }
+mark.sel { outline: 2px solid var(--accent); }
+.legend { display: flex; gap: 14px; color: var(--muted); font-size: 13px; margin-top: 8px; flex-wrap: wrap; }
+.dot { display: inline-block; width: 10px; height: 10px; border-radius: 3px; margin-right: 5px; vertical-align: -1px; }
+.list { display: flex; flex-direction: column; gap: 4px; max-height: 210px; overflow-y: auto; margin-bottom: 12px; }
+.row { display: grid; grid-template-columns: 74px minmax(0, 1fr) 54px; gap: 8px; align-items: center; padding: 5px 8px; border-radius: 7px; cursor: pointer; font-size: 14px; }
+.row:hover, .row.sel { background: var(--accent-bg); }
+.row .c { font-family: var(--mono); font-size: 12.5px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.row .p { text-align: right; font-variant-numeric: tabular-nums; color: var(--muted); font-size: 12.5px; }
+.badge { font-size: 11px; font-weight: 650; text-transform: uppercase; letter-spacing: .05em; padding: 2px 7px; border-radius: 6px; text-align: center; }
+.badge.ok { color: var(--ok); background: var(--ok-bg); }
+.badge.phantom { color: var(--bad); background: var(--bad-bg); }
+.badge.unknown { color: var(--warn); background: var(--warn-bg); }
+.insp h3 { font: 600 15px var(--mono); margin: 2px 0 8px; overflow-wrap: anywhere; }
+.ev { display: grid; grid-template-columns: minmax(0, 1fr) 58px; gap: 4px 10px; font-size: 13.5px; margin: 6px 0 10px; }
+.ev .n { color: var(--ink); }
+.ev .n small { color: var(--muted); display: block; font-size: 12px; }
+.ev .l { text-align: right; font: 600 13px var(--mono); color: var(--bad); }
+.chips { display: flex; flex-wrap: wrap; gap: 5px; margin: 4px 0 10px; }
+.chip { font: 12px var(--mono); padding: 2px 7px; border-radius: 6px; background: var(--accent-bg); color: var(--accent); }
+.sub { font-size: 12px; color: var(--muted); text-transform: uppercase; letter-spacing: .06em; margin: 12px 0 4px; font-weight: 600; }
+svg text { fill: var(--muted); font: 11px -apple-system, system-ui, sans-serif; }
+.heat { display: grid; gap: 1px; font: 11px var(--mono); margin-top: 4px; }
+.heat .lab { white-space: nowrap; overflow: hidden; }
+.heat div { height: 17px; display: flex; align-items: center; justify-content: center; }
+.heat .lab { color: var(--muted); justify-content: flex-end; padding-right: 4px; }
+.heat .cell { background: var(--grid); }
+.heat .on { background: var(--cell); color: #fff; }
+.heat .in { color: var(--ink); font-weight: 600; }
+.filters { display: flex; gap: 6px; flex-wrap: wrap; margin-top: 4px; }
+.filters button { font-family: var(--mono); font-size: 12px; padding: 3px 8px; }
+.filters button.on { background: var(--accent); color: #fff; border-color: var(--accent); }
+.speed { padding: 0 28px 28px; display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); gap: 16px; }
+.split { display: flex; height: 22px; border-radius: 6px; overflow: hidden; margin-top: 10px; font: 600 12px var(--mono); }
+.split div { display: flex; align-items: center; justify-content: center; color: #fff; white-space: nowrap; overflow: hidden; }
+.split .ane { background: var(--accent); }
+.split .gpu { background: var(--ok); }
+.big { font-size: 40px; font-weight: 700; letter-spacing: -0.03em; font-variant-numeric: tabular-nums; }
+pre { font: 12.5px/1.5 var(--mono); margin: 6px 0 0; white-space: pre-wrap; color: var(--ink); }
+.muted { color: var(--muted); }
+.note { color: var(--muted); font-size: 13px; margin-top: 8px; }
+.empty { color: var(--muted); padding: 20px 4px; }
+.arch { font: 12.5px/1.7 var(--mono); color: var(--muted); }
+.arch b { color: var(--ink); font-weight: 600; }
+@media (max-width: 980px) {
+  main, .speed { grid-template-columns: minmax(0, 1fr); padding-left: 16px; padding-right: 16px; }
+  .stats { grid-template-columns: repeat(2, minmax(0, 1fr)); padding: 10px 16px; }
+  header { padding: 18px 16px 6px; }
+  .editor { height: 380px; }
+}
+</style>
+</head>
+<body>
+<header>
+  <h1>CiteNet</h1>
+  <div class="tag">A phantom legal-citation detector that was never trained. <b id="params">–</b> parameters, every nonzero weight written by hand, running on Core ML.</div>
+</header>
+
+<section class="stats">
+  <div class="stat"><div class="k">This check</div><div class="v" id="s-ms">–</div><div class="s" id="s-ms2">–</div></div>
+  <div class="stat"><div class="k">One citation</div><div class="v" id="h-one">–</div><div class="s">p50, b1 on CPU, native Swift</div></div>
+  <div class="stat"><div class="k">Bulk</div><div class="v" id="h-bulk">–</div><div class="s" id="h-bulk2">–</div></div>
+  <div class="stat"><div class="k">LePhantomCite eval</div><div class="v">31 / 31</div><div class="s">phantoms caught · 1 / 983 real cites flagged</div></div>
+</section>
+
+<main>
+  <section class="panel">
+    <h2>Brief</h2>
+    <div class="toolbar">
+      <button data-sample="brief">Brief with planted phantoms</button>
+      <button data-sample="lepc">Random LePhantomCite excerpt</button>
+      <button data-sample="mata">Mata v. Avianca fakes</button>
+      <span class="muted" id="src" style="font-size:12px"></span>
+    </div>
+    <div class="editor">
+      <div class="backdrop" id="backdrop"></div>
+      <textarea id="ta" spellcheck="false"></textarea>
+    </div>
+    <div class="legend">
+      <span><span class="dot" style="background:var(--bad)"></span>phantom: the citation is impossible</span>
+      <span><span class="dot" style="background:var(--warn)"></span>unrecognized reporter</span>
+      <span><span class="dot" style="background:var(--ok)"></span>structurally possible (not proof the case exists)</span>
+    </div>
+  </section>
+
+  <section class="panel insp">
+    <h2>Citations <span id="count" class="muted"></span></h2>
+    <div class="list" id="list"></div>
+    <div id="detail"><div class="empty">Click a citation to see which hand-written neurons fired.</div></div>
+  </section>
+</main>
+
+<section class="speed">
+  <div class="panel">
+    <h2>Speed</h2>
+    <div class="toolbar">
+      <span class="muted" style="font-size:13px">Check 1,000,000 citations on</span>
+      <button data-lanes="ane">Neural Engine</button>
+      <button data-lanes="gpu">GPU</button>
+      <button class="primary" data-lanes="ane+gpu">Neural Engine + GPU</button>
+      <button id="bench">Score the LePhantomCite eval split</button>
+    </div>
+    <div class="big" id="fire-n">–</div>
+    <div class="muted" id="fire-s">Native Swift Core ML (bench/firehose): ANE b512 and GPU b8192, two threads per unit.</div>
+    <div class="split" id="split"></div>
+    <div id="bench-out" class="note"></div>
+    <div class="sub">Native Swift benchmark, M5 Pro (bench/bench.swift)</div>
+    <pre id="swift"></pre>
+  </div>
+  <div class="panel">
+    <h2>How the weights were written</h2>
+    <div class="arch" id="arch"></div>
+    <p class="note">Nothing was trained. <code>citenet/spec.py</code> lists reporters, series, courts, West regions and approximate volume-to-year timelines; <code>citenet/net.py</code> compiles each entry into specific filters and ReLU neurons. Design used only the LePhantomCite <code>aux_train</code> split. The <code>eval</code> split was scored once with the frozen v1.0 weights: 31/31 phantoms, 3/983 false flags. Two of those were tokenizer bugs, fixed in v1.1 (shown here). The remaining flag, <code>652 A.2d 634 (D.C. Cir. 1995)</code>, pairs a state reporter with a federal circuit.</p>
+    <p class="note">Limits: a string-only model checks that a citation <i>could</i> exist. LePhantomCite's non-existent citations are structurally impossible (F.5th, S.W.4th), so it catches all of them. Real LLM fakes such as the Mata v. Avianca cases copy valid formats, so they pass. Catching those needs a case-law lookup.</p>
+  </div>
+</section>
+
+<script>
+const $ = (id) => document.getElementById(id);
+const ta = $("ta"), bd = $("backdrop");
+let items = [], selected = -1, inflight = false, dirty = false, info = null;
+
+const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+const EVTEXT = {};
+
+async function getJSON(u) { const r = await fetch(u); return r.json(); }
+
+function paint() {
+  const t = ta.value; let out = "", pos = 0;
+  items.forEach((it, i) => {
+    out += esc(t.slice(pos, it.start));
+    out += `<mark class="${it.status}${i === selected ? " sel" : ""}">${esc(t.slice(it.start, it.end))}</mark>`;
+    pos = it.end;
+  });
+  out += esc(t.slice(pos)) + " \n";
+  bd.innerHTML = out;
+  bd.scrollTop = ta.scrollTop;
+}
+
+function renderList() {
+  $("count").textContent = items.length ? `· ${items.length} found · ${items.filter(i => i.status === "phantom").length} phantom` : "";
+  $("list").innerHTML = items.map((it, i) =>
+    `<div class="row${i === selected ? " sel" : ""}" data-i="${i}">
+       <span class="badge ${it.status}">${it.status === "ok" ? "possible" : it.status}</span>
+       <span class="c">${esc(it.cite)}</span><span class="p">${it.p.toFixed(3)}</span></div>`).join("");
+  $("list").querySelectorAll(".row").forEach(r => r.onclick = () => select(+r.dataset.i));
+}
+
+async function check() {
+  if (inflight) { dirty = true; return; }
+  inflight = true; dirty = false;
+  const t0 = performance.now();
+  const r = await fetch("/check", { method: "POST", body: JSON.stringify({ text: ta.value }) }).then(r => r.json());
+  const rtt = performance.now() - t0;
+  const prevCite = items[selected]?.cite;
+  items = r.items;
+  selected = prevCite ? items.findIndex(i => i.cite === prevCite) : selected;
+  if (selected >= items.length) selected = -1;
+  $("s-ms").textContent = r.n ? `${r.model_ms < 1 ? r.model_ms.toFixed(2) : r.model_ms.toFixed(1)} ms` : "–";
+  $("s-ms2").textContent = r.n ? `${r.n} citations on ${r.model} · ${rtt.toFixed(1)} ms round trip` : "no citations";
+  paint(); renderList();
+  if (selected >= 0) renderDetail(items[selected]); else if (!items.length) $("detail").innerHTML = `<div class="empty">No reporter citations found.</div>`;
+  inflight = false;
+  if (dirty) check();
+}
+
+function select(i) {
+  selected = i; paint(); renderList(); renderDetail(items[i]);
+}
+
+const NICE = (n) => n
+  .replace(/^class:/, "class ").replace(/^region:/, "region ").replace(/^home:/, "home state ")
+  .replace(/^state:/, "court state ").replace(/^court:/, "court ").replace(/^phantom:/, "phantom series ");
+
+async function renderDetail(it) {
+  if (!it) return;
+  const logit = it.logit_bias + it.reasons.reduce((a, r) => a + r.logit, 0);
+  let h = `<div style="display:flex;gap:10px;align-items:center"><span class="badge ${it.status}">${it.status === "ok" ? "possible" : it.status}</span>
+    <span class="muted" style="font-size:13px">p(phantom) = ${it.p.toFixed(3)} · logit ${logit.toFixed(2)}</span></div>
+    <h3>${esc(it.norm)}</h3>`;
+  h += `<div class="sub">Evidence → logit (bias ${it.logit_bias})</div>`;
+  h += it.reasons.length ? `<div class="ev">${it.reasons.map(r =>
+      `<div class="n">${r.name.replace(/_/g, " ")}${r.name === "volume_year" ? ` (${r.value.toFixed(1)} yr past tolerance)` : ""}<small>${esc(r.text)}</small></div><div class="l">+${r.logit.toFixed(2)}</div>`).join("")}</div>`
+    : `<div class="note" style="margin:4px 0 10px">No rule fired. Volume, reporter, court and year are mutually consistent.</div>`;
+  const parts = [];
+  if (it.volume) parts.push(`volume = ${it.volume}`);
+  if (it.year) parts.push(`year = ${it.year}`);
+  if (it.knots) parts.push(`${it.knots} volume knots active`);
+  h += `<div class="sub">Neurons that fired</div><div class="chips">${[...parts, ...it.fired.map(NICE)].map(c => `<span class="chip">${esc(c)}</span>`).join("")}</div>`;
+  h += `<div id="chart"></div><div class="sub">First-layer filters that matched</div><div class="filters" id="filters"></div><div id="heat"></div>`;
+  $("detail").innerHTML = h;
+  if (it.curve) drawCurve(it);
+  const fired = await getJSON("/fired?cite=" + encodeURIComponent(it.cite));
+  $("filters").innerHTML = fired.map((f, i) => `<button data-i="${i}">${esc(f.name)}</button>`).join("") || `<span class="muted">none</span>`;
+  const btns = $("filters").querySelectorAll("button");
+  btns.forEach(b => b.onclick = () => { btns.forEach(x => x.classList.remove("on")); b.classList.add("on"); drawFilter(fired[+b.dataset.i], it); });
+  const first = fired.findIndex(f => f.name.startsWith("rep:") || f.name.startsWith("series:"));
+  if (btns.length) btns[Math.max(0, first)].click();
+}
+
+async function drawCurve(it) {
+  const c = await getJSON("/curve?key=" + it.curve);
+  const W = 460, H = 170, L = 40, R = 10, T = 10, B = 24;
+  const xs = c.net.map(p => p[0]), ys = c.net.map(p => p[1]);
+  const y0 = Math.min(...ys, it.year || 1e9) - c.tol - 3, y1 = Math.max(...ys, it.year || 0) + c.tol + 3;
+  const x1 = Math.max(c.vmax, it.volume || 0) * 1.04;
+  const X = v => L + (W - L - R) * v / x1, Y = y => T + (H - T - B) * (1 - (y - y0) / (y1 - y0));
+  const up = c.net.map(p => `${X(p[0])},${Y(p[1] + c.tol)}`), dn = c.net.slice().reverse().map(p => `${X(p[0])},${Y(p[1] - c.tol)}`);
+  const line = c.net.map(p => `${X(p[0])},${Y(p[1])}`).join(" ");
+  const ticks = [];
+  const step = (y1 - y0) > 80 ? 40 : (y1 - y0) > 30 ? 10 : 5;
+  for (let y = Math.ceil(y0 / step) * step; y <= y1; y += step) ticks.push(`<line x1="${L}" x2="${W - R}" y1="${Y(y)}" y2="${Y(y)}" stroke="var(--grid)"/><text x="${L - 5}" y="${Y(y) + 4}" text-anchor="end">${y}</text>`);
+  let pt = "";
+  if (it.year && it.volume) {
+    const out = it.reasons.some(r => r.name === "volume_year" || r.name === "volume_missing");
+    pt = `<circle cx="${X(it.volume)}" cy="${Y(it.year)}" r="6" fill="${out ? "var(--bad)" : "var(--ok)"}" stroke="var(--panel)" stroke-width="2"/>`;
+  }
+  $("chart").innerHTML = `<div class="sub">Volume → year: what the knot neurons compute for ${esc(c.reporters.join(" / "))} (±${c.tol} yr)</div>
+    <svg viewBox="0 0 ${W} ${H}" width="100%" role="img" aria-label="volume to year curve">
+      ${ticks.join("")}
+      <polygon points="${up.concat(dn).join(" ")}" fill="var(--accent-bg)"/>
+      <polyline points="${line}" fill="none" stroke="var(--accent)" stroke-width="2"/>
+      <line x1="${X(c.vmax)}" x2="${X(c.vmax)}" y1="${T}" y2="${H - B}" stroke="var(--muted)" stroke-dasharray="3 3"/>
+      <text x="${X(c.vmax) - 4}" y="${T + 10}" text-anchor="end">last volume ${c.vmax}</text>
+      <text x="${L}" y="${H - 6}">vol 0</text><text x="${W - R}" y="${H - 6}" text-anchor="end">vol ${Math.round(x1)}</text>
+      ${pt}
+    </svg>`;
+}
+
+async function drawFilter(f, it) {
+  const w = await getJSON("/filter?name=" + encodeURIComponent(f.name));
+  const norm = "‹" + it.norm + "›";   // BOS / EOS markers, as the network sees them
+  const win = [];
+  for (let o = 0; o < w.k; o++) {
+    const ch = norm[f.pos + 1 + o];
+    win.push(ch === undefined ? "" : ch === " " ? "␣" : ch);
+  }
+  let g = `<div class="heat" style="grid-template-columns: 64px repeat(${w.k}, minmax(0, 1fr))">`;
+  g += `<div class="lab">input</div>` + win.map(c => `<div class="in">${esc(c)}</div>`).join("");
+  for (const r of w.rows) {
+    g += `<div class="lab">${esc(r.ch)}</div>` + r.w.map(v => `<div class="cell${v ? " on" : ""}"></div>`).join("");
+  }
+  g += `</div><div class="note">${esc(w.name)} · ${w.layer} · ${w.nonzero} nonzero of ${w.params} weights · bias ${w.bias}. ` +
+       `It outputs relu(matches + bias), which is 1 only when every column hits.</div>`;
+  $("heat").innerHTML = g;
+}
+
+async function loadSample(kind, pick) {
+  const r = await getJSON("/sample?kind=" + kind);
+  ta.value = r.text; selected = -1;
+  $("src").textContent = kind === "lepc" ? `LePhantomCite eval · ${r.file} · planted: ${Object.values(r.planted).join(", ") || "none"}` : "";
+  await check();
+  const want = pick ? items.findIndex(i => i.cite.includes(pick)) : -1;
+  const firstBad = items.findIndex(i => i.status === "phantom");
+  if (want >= 0) select(want); else if (firstBad >= 0) select(firstBad); else if (items.length) select(0);
+}
+
+document.querySelectorAll("[data-sample]").forEach(b => b.onclick = () => loadSample(b.dataset.sample));
+ta.addEventListener("input", () => check());
+ta.addEventListener("scroll", () => { bd.scrollTop = ta.scrollTop; });
+ta.addEventListener("click", () => {
+  const p = ta.selectionStart, i = items.findIndex(it => p >= it.start && p <= it.end);
+  if (i >= 0) select(i);
+});
+
+document.querySelectorAll("[data-lanes]").forEach(b => b.onclick = async () => {
+  const lanes = b.dataset.lanes;
+  $("fire-n").textContent = "…"; $("split").innerHTML = "";
+  const r = await getJSON("/firehose?n=1000000&lanes=" + encodeURIComponent(lanes));
+  const dur = 700, t0 = performance.now();
+  const tick = (t) => {
+    const f = Math.min(1, (t - t0) / dur);
+    $("fire-n").textContent = Math.round(r.n * f).toLocaleString() + " citations";
+    if (f < 1) requestAnimationFrame(tick);
+    else $("fire-n").textContent = `${r.n.toLocaleString()} in ${(r.seconds * 1000).toFixed(0)} ms`;
+  };
+  requestAnimationFrame(tick);
+  const name = { ane: "Neural Engine", gpu: "GPU", "ane+gpu": "Neural Engine + GPU" }[lanes];
+  $("fire-s").textContent = `${r.per_sec.toLocaleString()} citations/s on the ${name} · ${r.flagged.toLocaleString()} flagged · native Swift Core ML`;
+  $("split").innerHTML = Object.entries(r.lanes).map(([k, v]) =>
+    `<div class="${k}" style="width:${100 * v.cites / r.n}%">${k.toUpperCase()} b${v.batch} · ${(v.cites / r.seconds / 1e3).toFixed(0)}k/s</div>`).join("");
+});
+$("bench").onclick = async () => {
+  const r = await getJSON("/bench");
+  $("bench-out").innerHTML = `${r.n.toLocaleString()} eval citations in <b>${r.ms} ms</b> on ${r.model}: ` +
+    `${r.recall[0]}/${r.recall[1]} phantoms caught, ${r.false_flags[0]}/${r.false_flags[1]} real citations flagged` +
+    (r.false_flag_cites.length ? ` (${r.false_flag_cites.map(esc).join("; ")})` : "") + ".";
+};
+
+(async () => {
+  info = await getJSON("/info");
+  $("params").textContent = `${info.params.toLocaleString()}`;
+  $("swift").textContent = info.swift.trim();
+  const hl = info.headline, k = (n) => n >= 1e6 ? (n / 1e6).toFixed(2) + "M" : Math.round(n / 1e3) + "k";
+  if (hl.b1_cpu) $("h-one").textContent = `${Math.round(hl.b1_cpu.p50_us)} µs`;
+  const both = hl["concurrent:ane b512 + gpu b8192"];
+  if (both) {
+    $("h-bulk").textContent = `${k(both)}/s`;
+    $("h-bulk2").textContent = `citations/s, Neural Engine + GPU together (ANE alone ${k(hl.b512_ane.per_sec)}/s, GPU ${k(hl.b8192_gpu.per_sec)}/s)`;
+  } else if (hl.b512_ane) {
+    $("h-bulk").textContent = `${k(hl.b512_ane.per_sec)}/s`; $("h-bulk2").textContent = "citations/s, b512 on the Neural Engine";
+  }
+  const L = info.layers;
+  $("arch").innerHTML = [
+    `<b>char codes</b> [B, 1, 1, 64]`,
+    `→ <b>one-hot</b> relu(1 − |code − k|), k = 0…47 (no weights)`,
+    `→ <b>${L.rep} reporter filters</b> (conv 1×15) + <b>${L.court} court filters</b> (conv 1×8) + <b>6 digit decoders</b>, max over positions`,
+    `→ <b>${L.concepts} concept neurons</b>: reporter classes, West regions, courts, a 29-knot volume thermometer`,
+    `→ <b>${L.rules} rule neurons</b>: AND(class, bad court), |year − curve(volume)| − tol, volume > last`,
+    `→ <b>${L.evidence} evidence</b> sums, saturated → <b>logit</b> → sigmoid`,
+    `${info.params.toLocaleString()} parameters · ${info.nonzero.toLocaleString()} nonzero · 0 training steps`,
+  ].join("<br>");
+  const q = new URLSearchParams(location.search);   // ?sample=mata&pick=925  (deep links for screenshots)
+  await loadSample(q.get("sample") || "brief", q.get("pick"));
+  if (q.get("fire")) document.querySelector(`[data-lanes="${q.get("fire")}"]`)?.click();
+})();
+</script>
+</body>
+</html>

demo/live.html

@@ -0,0 +1,165 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>CiteNet Live</title>
+<style>
+:root {
+  --bg: #f7f6f2; --panel: #ffffff; --ink: #1c1b19; --muted: #77746b; --line: #e6e3da;
+  --ok: #1f7a4d; --ok-bg: #e2f2e8; --bad: #c2321f; --bad-bg: #fbe3de;
+  --accent: #2f4fd6; --gpu: #1f7a4d;
+  --mono: ui-monospace, "SF Mono", Menlo, monospace;
+  --serif: "Iowan Old Style", Palatino, Georgia, serif;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #141412; --panel: #1c1b19; --ink: #ecebe6; --muted: #918e85; --line: #2d2c28;
+    --ok: #4fc487; --ok-bg: #1c3326; --bad: #ff7a66; --bad-bg: #42201a;
+    --accent: #8ea2ff; --gpu: #4fc487;
+  }
+}
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--bg); color: var(--ink); font: 15px/1.5 -apple-system, BlinkMacSystemFont, system-ui, sans-serif; }
+.wrap { max-width: 980px; margin: 0 auto; padding: 36px 20px 48px; }
+h1 { margin: 0; font-size: 30px; letter-spacing: -0.02em; }
+.lede { color: var(--muted); margin: 4px 0 20px; }
+.lede a { color: inherit; }
+.controls { display: flex; gap: 14px; align-items: center; flex-wrap: wrap; }
+.controls button { font: 600 15px -apple-system, system-ui, sans-serif; border: 0; background: var(--ink); color: var(--bg); padding: 11px 18px; border-radius: 10px; cursor: pointer; }
+.controls label { color: var(--muted); font-size: 14px; display: flex; gap: 6px; align-items: center; cursor: pointer; }
+.nums { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 16px; margin: 26px 0 10px; }
+.num .k { color: var(--muted); font-size: 12px; text-transform: uppercase; letter-spacing: .07em; }
+.num .v { font-size: 38px; font-weight: 700; letter-spacing: -0.03em; font-variant-numeric: tabular-nums; line-height: 1.15; }
+.num .r { color: var(--muted); font-size: 14px; font-variant-numeric: tabular-nums; }
+.num .r b { color: var(--ink); font-weight: 600; }
+.bar { display: flex; height: 6px; border-radius: 3px; overflow: hidden; background: var(--line); }
+.bar div { background: var(--ink); width: 0; transition: width .1s linear; }
+.meta { color: var(--muted); font-size: 13px; margin-top: 8px; font-variant-numeric: tabular-nums; min-height: 1.5em; }
+.cols { display: grid; grid-template-columns: minmax(0, 1.4fr) minmax(0, 1fr); gap: 24px; margin-top: 26px; }
+h2 { font-size: 12px; text-transform: uppercase; letter-spacing: .07em; color: var(--muted); margin: 0 0 8px; font-weight: 600; }
+.tape { height: 420px; overflow: hidden; border: 1px solid var(--line); border-radius: 12px; background: var(--panel); padding: 8px 14px;
+        -webkit-mask-image: linear-gradient(to bottom, #000 70%, transparent); mask-image: linear-gradient(to bottom, #000 70%, transparent); }
+.tape div { font: 14px/1.55 var(--serif); padding: 4px 0; border-bottom: 1px solid var(--line); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; color: var(--muted); }
+.tape mark { background: var(--ok-bg); color: var(--ink); border-radius: 3px; padding: 0 2px; }
+.tape mark.bad { background: var(--bad-bg); box-shadow: inset 0 -2px 0 var(--bad); }
+.caught { list-style: none; margin: 0; padding: 0; max-height: 420px; overflow: hidden; }
+.caught li { padding: 8px 0; border-top: 1px solid var(--line); }
+.caught li:first-child { border-top: 0; }
+.caught .c { font: 13px var(--mono); color: var(--bad); overflow-wrap: anywhere; }
+.caught .w { color: var(--muted); font-size: 13.5px; }
+.note { color: var(--muted); font-size: 13px; margin-top: 10px; }
+.empty { color: var(--muted); font-size: 14px; }
+@media (max-width: 760px) {
+  .wrap { padding: 24px 16px 40px; }
+  .nums { grid-template-columns: minmax(0, 1fr); gap: 10px; }
+  .num .v { font-size: 30px; }
+  .cols { grid-template-columns: minmax(0, 1fr); }
+  .tape { height: 300px; }
+}
+</style>
+</head>
+<body>
+<div class="wrap">
+  <h1>CiteNet Live</h1>
+  <div class="lede" id="lede">Real US court opinions, scanned for impossible citations as fast as the Mac can read them. <a href="/">Back</a></div>
+
+  <div class="controls">
+    <button id="go">Scan</button>
+    <label><input type="checkbox" id="loop"> keep going (loop the corpus)</label>
+  </div>
+
+  <div class="nums">
+    <div class="num"><div class="k">Text read</div><div class="v" id="n-bytes">0 GB</div><div class="r" id="r-bytes">&nbsp;</div></div>
+    <div class="num"><div class="k">Citations checked</div><div class="v" id="n-cites">0</div><div class="r" id="r-cites">&nbsp;</div></div>
+    <div class="num"><div class="k">Flagged</div><div class="v" id="n-flag">0</div><div class="r" id="r-flag">&nbsp;</div></div>
+  </div>
+  <div class="bar"><div id="prog"></div></div>
+  <div class="meta" id="meta"></div>
+
+  <div class="cols">
+    <div>
+      <h2>Citations going by</h2>
+      <div class="tape" id="tape"><div class="empty" style="border:0">Press Scan.</div></div>
+    </div>
+    <div>
+      <h2>Flagged</h2>
+      <ul class="caught" id="caught"></ul>
+      <div class="note">Unverified. Real opinions contain typos and OCR errors, and CiteNet's volume timelines are approximate, so some flags are its own mistakes.</div>
+    </div>
+  </div>
+</div>
+
+<script>
+const $ = (id) => document.getElementById(id);
+const esc = (s) => s.replace(/&#(\d+);/g, (_, n) => String.fromCharCode(+n)).replace(/&amp;/g, "&")
+  .replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+const fmtB = (b) => b >= 1e9 ? (b / 1e9).toFixed(2) + " GB" : (b / 1e6).toFixed(0) + " MB";
+const fmtR = (n) => n >= 1e6 ? (n / 1e6).toFixed(2) + "M" : n >= 1e3 ? Math.round(n / 1e3) + "k" : String(n);
+let info = null, es = null, seen = new Set();
+
+function reset() {
+  ["n-bytes", "n-cites", "n-flag"].forEach(id => $(id).textContent = "0");
+  $("n-bytes").textContent = "0 GB";
+  ["r-bytes", "r-cites", "r-flag"].forEach(id => $(id).innerHTML = "&nbsp;");
+  $("tape").innerHTML = ""; $("caught").innerHTML = ""; $("meta").textContent = ""; $("prog").style.width = "0";
+  seen = new Set();
+}
+
+function stop() { if (es) { es.close(); es = null; } $("go").textContent = info ? `Scan ${fmtB(info.bytes)}` : "Scan"; }
+
+function onTick(ev) {
+  if (ev.start) return;
+  const loopRun = $("loop").checked;
+  $("n-bytes").textContent = fmtB(ev.bytes);
+  $("r-bytes").innerHTML = ev.done ? `in <b>${ev.t.toFixed(2)} s</b>` : `<b>${(ev.mbps / 1000).toFixed(2)} GB/s</b>`;
+  $("n-cites").textContent = ev.checked.toLocaleString();
+  $("r-cites").innerHTML = ev.done ? `<b>${fmtR(Math.round(ev.checked / ev.t))}/s</b> average` : `<b>${fmtR(ev.cps)}/s</b>`;
+  $("n-flag").textContent = ev.flagged.toLocaleString();
+  $("r-flag").innerHTML = ev.checked ? `${(100 * ev.flagged / ev.checked).toFixed(3)}% of citations` : "&nbsp;";
+  const total = info ? info.bytes : ev.bytes;
+  $("prog").style.width = loopRun ? "100%" : Math.min(100, 100 * ev.bytes / total) + "%";
+  const lanes = ev.ane + ev.gpu;
+  $("meta").textContent = (lanes ? `Neural Engine ${Math.round(100 * ev.ane / lanes)}% · GPU ${Math.round(100 * ev.gpu / lanes)}% · ` : "") +
+    `4 CPU scan threads · ${ev.t.toFixed(1)} s` + (loopRun ? ` · pass ${ev.pass + 1}` : "") +
+    (ev.done ? ` · done: ${info ? info.decisions.toLocaleString() + " decisions, " : ""}${ev.checked.toLocaleString()} citations` : "");
+  const tape = $("tape");
+  for (const s of ev.ticker) {
+    const d = document.createElement("div");
+    const before = s.before.slice(-34), after = s.after.slice(0, 40);
+    d.innerHTML = `…${esc(before)}<mark class="${s.flag ? "bad" : ""}">${esc(s.cite)}</mark>${esc(after)}…`;
+    tape.prepend(d);
+  }
+  while (tape.children.length > 40) tape.lastChild.remove();
+  const ul = $("caught");
+  for (const c of ev.caught) {
+    if (seen.has(c.cite)) continue;
+    seen.add(c.cite);
+    const li = document.createElement("li");
+    li.innerHTML = `<div class="c">${esc(c.cite)}</div><div class="w">${esc(c.why || c.kind)}</div>`;
+    ul.prepend(li);
+  }
+  while (ul.children.length > 14) ul.lastChild.remove();
+  if (ev.done) stop();
+}
+
+$("go").onclick = () => {
+  if (es) return stop();
+  reset();
+  $("go").textContent = "Stop";
+  es = new EventSource("/live/stream?loop=" + ($("loop").checked ? 1 : 0));
+  es.onmessage = (m) => onTick(JSON.parse(m.data));
+  es.onerror = () => stop();
+};
+
+fetch("/live/info").then(r => r.json()).then(j => {
+  if (j.error) { $("lede").innerHTML = "No corpus found (data/cold/corpus.txt). <a href='/'>Back</a>"; return; }
+  info = j;
+  $("lede").innerHTML = `${j.decisions.toLocaleString()} real US court decisions (${fmtB(j.bytes)}, COLD Cases, CC0), ` +
+    `scanned by a native scanner on the CPU and checked by CiteNet on the Neural Engine + GPU. <a href="/wall">Watch it read</a> · <a href="/">Back</a>`;
+  $("go").textContent = `Scan ${fmtB(j.bytes)}`;
+  if (new URLSearchParams(location.search).get("auto")) $("go").click();
+});
+</script>
+</body>
+</html>

demo/sample_brief.txt

@@ -0,0 +1,5 @@
+A complaint survives a motion to dismiss only if it states a claim that is plausible on its face. Bell Atl. Corp. v. Twombly, 550 U.S. 544, 570 (2007); Ashcroft v. Iqbal, 556 U.S. 662, 678 (2009). Courts in this circuit apply that rule strictly to carriage claims. Henley v. Northwind Cargo, Inc., 412 F.5th 1187, 1193 (2d Cir. 2023); see also Viacom Int'l, Inc. v. YouTube, Inc., 676 F.3d 19 (2d Cir. 2012).
+
+Summary judgment is appropriate where there is no genuine dispute of material fact. Celotex Corp. v. Catrett, 477 U.S. 317, 322 (1986). District courts apply the same standard. Ruiz v. Pacific Lantern Co., 88 F. Supp. 3d 412, 418 (5th Cir. 2015); Thaler v. Perlmutter, 687 F. Supp. 3d 140 (D.D.C. 2023).
+
+Expert testimony must rest on a reliable foundation. Daubert v. Merrell Dow Pharms., Inc., 509 U.S. 579, 589 (1993); Okafor v. Bellmont Labs., 912 F.3d 455, 460 (9th Cir. 1998). State courts agree. Hargrove v. Benton Freight, 702 So. 2d 115, 117 (Tex. App. 1997); Tarasoff v. Regents of Univ. of Cal., 551 P.2d 334 (Cal. 1976); Moreau v. Calder, 233 S.W.4th 905, 929 (Tex. 2002).

demo/sample_mata.txt

@@ -0,0 +1,10 @@
+The six citations ChatGPT invented for the plaintiff's brief in Mata v. Avianca, Inc., 678 F. Supp. 3d 443 (S.D.N.Y. 2023). None of these cases exist, but every citation copies a real format:
+
+Varghese v. China Southern Airlines Co., 925 F.3d 1339 (11th Cir. 2019).
+Shaboon v. Egyptair, 2013 IL App (1st) 111279-U (Ill. App. Ct. 2013).
+Petersen v. Iran Air, 905 F. Supp. 2d 121 (D.D.C. 2012).
+Martinez v. Delta Air Lines, Inc., 2019 WL 4639462 (Tex. App. Sept. 25, 2019).
+Estate of Durden v. KLM Royal Dutch Airlines, 2017 WL 2418825 (Ga. Ct. App. June 5, 2017).
+Miller v. United Airlines, Inc., 174 F.3d 366 (2d Cir. 1999).
+
+A string-only model can only test whether a citation is structurally possible. Catching these needs a lookup against case law (for example the CourtListener citation API).

demo/server.py

@@ -0,0 +1,568 @@
+"""CiteNet demo server: live phantom-citation checking on Core ML.
+
+  python demo/server.py            -> http://localhost:8025
+
+Every request runs the hand-written model through Core ML: b1 on the CPU for a
+single citation, b32 / b512 on the Neural Engine for more. Timings in the
+responses are measured around MLModel.predict in this process. The firehose
+runs the native Swift binary bench/firehose (ANE b512, GPU b8192, or both, two
+threads per unit).
+"""
+import json
+import os
+import random
+import sys
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+import numpy as np
+import coremltools as ct
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, ROOT)
+sys.path.insert(0, os.path.join(ROOT, "scripts"))
+from citenet import spec, text            # noqa: E402
+from citenet.net import knot_readout, K_REP, K_COURT, ANCHOR_W  # noqa: E402
+from lepc import load                     # noqa: E402
+
+BUILD = os.path.join(ROOT, "build")
+PORT = int(os.environ.get("PORT", 8025))
+
+META = json.load(open(os.path.join(BUILD, "meta.json")))
+W = np.load(os.path.join(BUILD, "weights.npz"))
+CONCEPTS = META["concepts"]
+EVIDENCE = META["evidence"]
+EV_INFO = {e[0]: dict(weight=e[1], cap=e[2], text=e[3]) for e in spec.EVIDENCE}
+
+MODELS = {
+    1: ("CPU", ct.models.MLModel(os.path.join(BUILD, "CiteNet_b1.mlpackage"), compute_units=ct.ComputeUnit.CPU_ONLY)),
+    32: ("ANE", ct.models.MLModel(os.path.join(BUILD, "CiteNet_b32.mlpackage"), compute_units=ct.ComputeUnit.CPU_AND_NE)),
+    512: ("ANE", ct.models.MLModel(os.path.join(BUILD, "CiteNet_b512.mlpackage"), compute_units=ct.ComputeUnit.CPU_AND_NE)),
+}
+LOCK = threading.Lock()
+LAST_ACTIVE = [0.0]       # time of the last wall request; the keep-alive runs while it is recent
+
+
+def keep_warm():
+    """While a wall is open, run a tiny batch every 100 ms so the Neural Engine stays awake.
+    Idle for a few seconds, the ANE powers down and the next call pays ~15-20 ms to wake up;
+    warm, a 64 KB chunk takes ~1.5 ms. About 1% of the ANE's time; stops 8 s after the last request."""
+    pings = {b: np.zeros((b, 1, 1, spec.SEQ), np.float16) for b in (32, 512)}
+    while True:
+        time.sleep(0.1)
+        if time.time() - LAST_ACTIVE[0] < 8:
+            with LOCK:
+                for b, x in pings.items():
+                    MODELS[b][1].predict({"codes": x})
+TOTAL = sum(int(np.prod(v.shape)) for v in W.values())
+NONZERO = sum(int((v != 0).sum()) for v in W.values())
+
+
+
+def run(codes):
+    """codes [N,1,1,SEQ] float -> (p, evidence, concepts, model label, ms)."""
+    n = len(codes)
+    b = 1 if n == 1 else (32 if n <= 32 else 512)
+    unit, m = MODELS[b]
+    ps, evs, cs = [], [], []
+    t0 = time.perf_counter()
+    with LOCK:
+        for i in range(0, n, b):
+            chunk = codes[i:i + b]
+            x = np.zeros((b, 1, 1, spec.SEQ), np.float16)
+            x[:len(chunk)] = chunk
+            out = m.predict({"codes": x})
+            k = len(chunk)
+            ps.append(out["p_fake"][:k, 0]); evs.append(out["evidence"][:k]); cs.append(out["concepts"][:k])
+    ms = (time.perf_counter() - t0) * 1e3
+    if n == 0:
+        return np.zeros(0), np.zeros((0, len(EVIDENCE))), np.zeros((0, len(CONCEPTS))), f"b{b} {unit}", 0.0
+    return (np.concatenate(ps).astype(float), np.concatenate(evs).astype(float),
+            np.concatenate(cs).astype(float), f"b{b} · {unit}", ms)
+
+
+def describe(p, ev, c):
+    act = {CONCEPTS[j]: float(c[j]) for j in np.nonzero(c > 0.5e-2)[0]}
+    status = "phantom" if p >= 0.5 else ("unknown" if p > 0.1 else "ok")
+    reasons = [dict(name=e, value=round(float(v), 2), text=EV_INFO[e]["text"],
+                    logit=round(float(min(v, EV_INFO[e]["cap"]) * EV_INFO[e]["weight"]), 2))
+               for e, v in zip(EVIDENCE, ev) if v > 0.01]
+    vol = act.get("volume", 0.0)
+    year = act.get("year", 0.0) + 1700 if act.get("has_year", 0) > 0.5 else None
+    curve = next((n[3:] for n in act if n.startswith("is:") and n[3:] in spec.CURVES), None)
+    fired = [n for n in act if not n.startswith(("vol>", "is:", "has_", "known", "volume", "year", "vol4y", "future"))
+             and not n.endswith("^hi")]
+    fired += [n for n in act if n.startswith("region:")]
+    return dict(p=round(float(p), 4), status=status, reasons=reasons, volume=int(round(vol)) or None,
+                year=int(round(year)) if year else None, curve=curve, fired=fired,
+                knots=sum(1 for n in act if n.startswith("vol>")), logit_bias=spec.BIAS)
+
+
+def filters_fired(cite):
+    """Which first-layer filters fired (recomputed on the host from the same weights, for display)."""
+    codes = text.encode([cite])[0, 0, 0].astype(int)
+    onehot = np.zeros((spec.NCHAR, spec.SEQ), np.float32)
+    onehot[codes, np.arange(spec.SEQ)] = 1
+    out = []
+    for conv, names, k, width in (("conv_rep", META["anchored"], K_REP, ANCHOR_W),
+                                  ("conv_float", META["floating"], K_REP, spec.SEQ),
+                                  ("conv_court", [n for n in META["features"] if n.startswith("court:")], K_COURT, spec.SEQ)):
+        w, b = W[conv + ".weight"][:, :, 0, :], W[conv + ".bias"]
+        for i, name in enumerate(names):
+            for pos in range(width - k + 1):
+                if (w[i] * onehot[:, pos:pos + k]).sum() + b[i] > 0.5:
+                    out.append(dict(name=name, pos=pos - 1, len=int(-b[i] + 1)))
+                    break
+    return out
+
+
+CLASS_DESC = {
+    "SCOTUS": "a Supreme Court reporter", "FEDAPP": "a federal appeals reporter",
+    "FEDAPP_OLD": "a federal appeals reporter", "FEDDIST": "a district-court reporter",
+    "BANKR": "a bankruptcy reporter", "REGION": "a state-court reporter", "STATE": "a state-court reporter",
+}
+STATE_NAME = {"cal": "California", "n.y": "New York", "mass": "Massachusetts", "ill": "Illinois", "ind": "Indiana",
+              "va": "Virginia", "pa": "Pennsylvania", "n.j": "New Jersey", "wash": "Washington", "ohio": "Ohio",
+              "md": "Maryland", "n.c": "North Carolina", "ga": "Georgia", "kan": "Kansas", "mich": "Michigan",
+              "wis": "Wisconsin", "conn": "Connecticut", "tex": "Texas", "s.c": "South Carolina",
+              "r.i": "Rhode Island", "colo": "Colorado", "ariz": "Arizona", "or": "Oregon", "okla": "Oklahoma"}
+REGION_NAME = {"A": "Atlantic", "NE": "North Eastern", "NW": "North Western", "P": "Pacific",
+               "SE": "South Eastern", "SW": "South Western", "SO": "Southern"}
+
+
+def explain(d, cite):
+    """One plain sentence per evidence neuron that fired, filled in from the citation."""
+    import re
+    from citenet.net import curve_at
+    m = text.CITE_RE.match(cite.strip())
+    rep = m.group("rep") if m else "this reporter"
+    paren = (m.group("paren") or "").strip(" ()") if m else ""
+    court = re.sub(r"\s*(?:[A-Z][a-z]{2,4}\.? \d{1,2}, )?\d{4}$", "", paren).strip(" ,") or None
+    act = set(d["fired"])
+    cls = next((n[6:] for n in act if n.startswith("class:")), None)
+    out = []
+    for r in d["reasons"]:
+        n = r["name"]
+        if n == "phantom_series":
+            out.append(f"{rep} was never published")
+        elif n == "court_mismatch":
+            out.append(f"{rep} is {CLASS_DESC.get(cls, 'a reporter')}; it never prints {court or 'that court'} opinions")
+        elif n == "state_mismatch":
+            reg = next((n2[7:] for n2 in act if n2.startswith("region:")), None)
+            home = next((n2[5:] for n2 in act if n2.startswith("home:")), None)
+            if reg:
+                sts = [s.title() + ("" if s in spec.UNDOTTED else ".") for s in spec.REGION_STATES[reg]]
+                lst = ", ".join(sts[:-1]) + " and " + sts[-1] if len(sts) <= 5 else ", ".join(sts[:4]) + " and others"
+                out.append(f"{rep} ({REGION_NAME[reg]} Reporter) covers {lst}, not {court}")
+            else:
+                out.append(f"{rep} only prints {STATE_NAME.get(home, 'its own state')} cases, not {court}")
+        elif n == "volume_year" and any(r2["name"] == "volume_missing" for r2 in d["reasons"]):
+            continue
+        elif n == "volume_year" and d["curve"]:
+            c = spec.CURVES[d["curve"]]
+            exp = round(curve_at(c["pts"], min(d["volume"], c["vmax"])))
+            out.append(f"volume {d['volume']} of {rep} is from about {exp}, not {d['year']}")
+        elif n == "volume_year":
+            out.append(f"the Westlaw/Lexis number is from {d['volume']}, but the case is dated {d['year']}")
+        elif n == "volume_missing":
+            vmax = spec.CURVES[d["curve"]]["vmax"] if d["curve"] else None
+            out.append(f"{rep} has no volume {d['volume']}; it ends around volume {vmax}" if vmax else f"{rep} has no volume {d['volume']}")
+        elif n == "future_year":
+            out.append(f"dated {d['year']}, which is in the future")
+        elif n == "unknown_reporter":
+            out.append(f"“{rep}” is not a reporter I recognize")
+    return out
+
+
+def check_text(t):
+    t0 = time.perf_counter()
+    found = text.extract(t)
+    codes = text.encode([c for _, _, c in found])
+    t1 = time.perf_counter()
+    p, ev, c, label, ms = run(codes)
+    items = []
+    for (s, e, cite), pi, evi, ci in zip(found, p, ev, c):
+        d = describe(pi, evi, ci)
+        d.update(start=s, end=e, cite=cite, norm=text.normalize(cite))
+        d["why"] = explain(d, cite)
+        items.append(d)
+    return dict(items=items, n=len(items), model=label, model_ms=round(ms, 3),
+                tokenize_ms=round((t1 - t0) * 1e3, 3))
+
+
+def curve_payload(key):
+    c = spec.CURVES[key]
+    a, coef = knot_readout(c["pts"], c["vmax"])
+    vs = np.linspace(0, max(10, c["vmax"]), 120)
+    net = [a + sum(w * max(0.0, v - float(n[4:])) for n, w in coef.items()) + 1700 for v in vs]
+    return dict(key=key, tol=c["tol"], vmax=c["vmax"], anchors=c["pts"],
+                net=[[float(v), float(y)] for v, y in zip(vs, net)],
+                reporters=[a for a, _, _, k in spec.REPORTERS if k == key])
+
+
+def _label(rs, labels):
+    if len(rs) == 1:
+        return labels[rs[0]]
+    digits = [r for r in rs if spec.DIGIT0 <= r < spec.DIGIT0 + 10]
+    letters = [r for r in rs if spec.LETTER_A <= r < spec.LETTER_A + 26]
+    rest = [labels[r] for r in rs if r not in digits and r not in letters]
+    out = []
+    if len(digits) == 10:
+        out.append("0-9")
+    elif len(digits) >= 6:
+        out.append("0-9*")
+    else:
+        out += [labels[r] for r in digits]
+    if len(letters) >= 20:
+        out.append("a-z" if len(letters) == 26 else "a-z*")
+    else:
+        out += [labels[r] for r in letters]
+    if len(rest) > 6:
+        return "other"
+    return " ".join(out + rest)
+
+
+def filter_payload(name):
+    conv, names, k = None, None, None
+    for cv, ns, kk in (("conv_rep", META["anchored"], K_REP), ("conv_float", META["floating"], K_REP),
+                       ("conv_court", [n for n in META["features"] if n.startswith("court:")], K_COURT)):
+        if name in ns:
+            conv, names, k = cv, ns, kk
+    if conv is None:
+        return None
+    i = names.index(name)
+    w = W[conv + ".weight"][i, :, 0, :]
+    labels = ["pad", "bos", "eos"] + [str(d) for d in range(10)] + [chr(97 + j) for j in range(26)] + \
+        ["␣", ".", ",", "(", ")", "'", "&", "-", "?"]
+    # merge characters with identical weight rows ("0-9", "a-z") and order rows by
+    # their first column, so a template reads as a diagonal
+    groups = {}
+    for r in range(spec.NCHAR):
+        if w[r].any():
+            groups.setdefault(tuple(int(x) for x in w[r]), []).append(r)
+    rows = []
+    for vec, rs in sorted(groups.items(), key=lambda kv: (kv[0].index(1), kv[1][0])):
+        rows.append(dict(ch=_label(rs, labels), w=list(vec)))
+    return dict(name=name, k=k, bias=float(W[conv + ".bias"][i]), rows=rows, layer=conv,
+                params=int(w.size) + 1, nonzero=int((w != 0).sum()))
+
+
+# ---------------------------------------------------------------- samples and benchmarks
+SAMPLES = {
+    "brief": open(os.path.join(ROOT, "demo", "sample_brief.txt")).read(),
+    "mata": open(os.path.join(ROOT, "demo", "sample_mata.txt")).read(),
+}
+EVAL_ROWS = [json.loads(l) for l in open(os.path.join(ROOT, "data", "eval.jsonl"))]
+EVAL_CITES = load("eval")
+ALL_CITES = load("aux_train") + EVAL_CITES
+ALL_CODES = text.encode([r["cite"] for r in ALL_CITES]).astype(np.float16)
+
+
+def lepc_sample():
+    r = random.choice([r for r in EVAL_ROWS if any("non_existent_citation" in v
+                                                   for v in (r.get("list_hallucination_types") or {}).values())])
+    return dict(text=r["text"], file=r["filename"],
+                planted={k: v for k, v in (r.get("list_hallucinations") or {}).items()})
+
+
+def bench_eval():
+    codes = text.encode([r["cite"] for r in EVAL_CITES])
+    p, _, _, label, ms = run(codes)
+    lab = np.array([r["label"] for r in EVAL_CITES]); flag = p >= 0.5
+    tp = int((flag & (lab == "phantom")).sum()); P = int((lab == "phantom").sum())
+    fp = int((flag & (lab == "genuine")).sum()); G = int((lab == "genuine").sum())
+    flagged = [r["cite"] for r, f in zip(EVAL_CITES, flag) if f and r["label"] == "genuine"]
+    return dict(n=len(EVAL_CITES), model=label, ms=round(ms, 2), recall=[tp, P], false_flags=[fp, G],
+                false_flag_cites=flagged)
+
+
+FIREHOSE = os.path.join(ROOT, "bench", "firehose")
+
+
+def firehose(n, lanes):
+    """Native Swift Core ML firehose (bench/firehose.swift): Python threads cannot keep the
+    ANE and the GPU busy at the same time, a native process can."""
+    import subprocess
+    if lanes not in ("ane", "gpu", "ane+gpu"):
+        lanes = "ane+gpu"
+    with LOCK:
+        out = subprocess.run([FIREHOSE, BUILD, lanes, str(n)], capture_output=True, text=True, timeout=120)
+    return json.loads(out.stdout)
+
+
+STREAM = os.path.join(ROOT, "bench", "stream_bin")
+CORPUS = os.path.join(ROOT, "data", "cold", "corpus.txt")
+EV_SHORT = ["never-published series", "court mismatch", "state mismatch", "year doesn't fit volume",
+            "volume doesn't exist", "future date", "unknown reporter"]
+
+
+def corpus_info():
+    try:
+        return json.load(open(CORPUS.rsplit(".", 1)[0] + ".json"))
+    except OSError:
+        return None
+
+
+def live_stream(handler, loop):
+    """Run bench/stream_bin over the case-law corpus; relay its JSON lines as server-sent events."""
+    import subprocess
+    cmd = [STREAM, BUILD, CORPUS] + (["--loop"] if loop else [])
+    proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, bufsize=1)
+    handler.send_response(200)
+    handler.send_header("Content-Type", "text/event-stream")
+    handler.send_header("Cache-Control", "no-store")
+    handler.end_headers()
+    try:
+        for line in proc.stdout:
+            ev = json.loads(line)
+            for c in ev.get("caught", []):
+                items = check_text(c["cite"])["items"]
+                c["why"] = "; ".join(items[0]["why"]) if items else EV_SHORT[c["ev"]]
+                c["kind"] = EV_SHORT[c["ev"]]
+            handler.wfile.write(b"data: " + json.dumps(ev).encode() + b"\n\n")
+            handler.wfile.flush()
+            if ev.get("done"):
+                break
+    except (BrokenPipeError, ConnectionResetError):
+        pass
+    finally:
+        proc.kill()
+        proc.wait()
+
+
+# ---------------------------------------------------------------- text wall
+import mmap
+WALL_SRC = {"cold": CORPUS, "lepc": os.path.join(BUILD, "lepc_text.txt")}
+_maps = {}
+
+
+def _wall_map(src):
+    if src not in _maps:
+        f = open(WALL_SRC[src], "rb")
+        _maps[src] = mmap.mmap(f.fileno(), 0, access=mmap.ACCESS_READ)
+    return _maps[src]
+
+
+def wall_random(src):
+    """Byte offset of the start of a random decision / brief excerpt."""
+    src = "cold" if src == "planted" else src
+    m = _wall_map(src)
+    off = random.randrange(0, max(1, len(m) - 100_000))
+    i = m.find(b"\n\n\n" if src == "cold" else b"\n\n", off)
+    return dict(off=0 if i < 0 else i + (3 if src == "cold" else 2))
+
+
+# ---- planted fakes: mutate real citations into impossible ones, then let the model find them
+import re as _re
+CURVE_REPS = {a for a, _, _, k in spec.REPORTERS if k and k in spec.CURVES}
+FIRST_SERIES = {"F.", "A.", "P.", "So.", "N.E.", "N.W.", "S.E.", "S.W."}
+FED_APP = {"f.3d", "f.2d", "f.4th", "f.app'x", "fed.appx."}
+STATE_COURTS = ["Tex. App.", "Cal. Ct. App.", "N.Y. App. Div.", "Fla. Dist. Ct. App.", "Ill. App. Ct."]
+_SERIES = _re.compile(r"^(?P<base>.*?)(?P<sp>\s?)(?P<ord>2d|3d|4th|5th|2nd|3rd)$")
+
+
+PLANT_RATE = 0.125    # target share of planted citations (a quota: unmutable ones pass it to the next)
+
+
+def plant(cite, rng):
+    """One impossible variant of a real citation, or None if none of the mutations applies."""
+    m = text.CITE_RE.match(cite)
+    if not m:
+        return None
+    rep = m.group("rep")
+    norm = text.normalize(rep + " 1").rsplit(" ", 1)[0]
+    paren = m.group("paren") or ""
+    yr = _re.search(r"(?<=[\s(.,])(\d{4})\)\s*$", paren)          # a real year, not "*7771985"
+    opts = []
+    sm = None if "A.L.R" in rep or "ALR" in rep else _SERIES.match(rep)      # A.L.R. really runs to 7th
+    if sm:
+        bump = {"2d": "4th", "2nd": "4th", "3d": rng.choice(["4th", "5th"]), "3rd": "5th", "4th": "6th", "5th": "7th"}[sm["ord"]]
+        if not (norm in ("f.3d", "f.supp.3d") and bump == "4th"):        # F.4th is real
+            opts += [("series", rep[:sm.start("ord")] + bump)] * 3
+    elif rep in FIRST_SERIES:      # F.4th is real, so the first Federal Reporter jumps to 5th/6th
+        opts += [("series", rep + (rng.choice(["5th", "6th"]) if rep == "F." else rng.choice(["4th", "5th"])))] * 3
+    if yr and norm in CURVE_REPS:
+        y = int(yr.group(1))
+        ny = y + rng.choice([-1, 1]) * rng.randint(18, 40)
+        if not 1800 <= ny <= 2024:
+            ny = y - rng.randint(18, 40) if ny > 2024 else y + rng.randint(18, 40)
+        if 1800 <= ny <= 2024:
+            opts += [("year", None, ny)] * 2
+    if paren and "Cir." in paren and norm in FED_APP:
+        opts.append(("court", rng.choice(STATE_COURTS)))
+    if not opts:
+        return None
+    kind, *val = rng.choice(opts)
+    if kind == "series":
+        a, b = m.span("rep")
+        fake_rep = val[0]
+        # never produce a series that really exists (F.4th, Cal. 4th/5th, Cal. App. 4th/5th)
+        real = set(spec.VALID_4TH) | set(spec.VALID_5TH)
+        if text.normalize(fake_rep + " 1").rsplit(" ", 1)[0] in real:
+            fake_rep = _re.sub(r"(4th|5th)$", "6th", fake_rep)
+        return cite[:a] + fake_rep + cite[b:]
+    if kind == "year":
+        a = m.start("paren") + yr.start(1)
+        return cite[:a] + str(val[1]) + cite[a + 4:]
+    if not yr:
+        return None
+    new_paren = paren[:paren.index("(") + 1] + val[0] + " " + yr.group(1) + ")"
+    return cite[:m.start("paren")] + new_paren + cite[m.end("paren"):]
+
+
+def plant_text(t, rate, seed):
+    """Replace ~rate of the citations in t with planted fakes. Returns (new text, planted ranges)."""
+    rng = random.Random(seed)
+    out, ranges, pos = [], [], 0
+    owed = rng.random()                     # quota carried across citations, so density stays near `rate`
+    for s_, e_, cite in text.extract(t):
+        owed = min(owed + rate, 3.0)
+        if owed < 1 or rng.random() < 0.3:  # a little jitter so fakes are not evenly spaced
+            continue
+        fake = plant(cite, rng)
+        if not fake or fake == cite:
+            continue
+        owed -= 1
+        out.append(t[pos:s_])
+        start = sum(len(x) for x in out)
+        out.append(fake)
+        ranges.append((start, start + len(fake)))
+        pos = e_
+    out.append(t[pos:])
+    return "".join(out), ranges
+
+
+def wall_chunk(src, off, size):
+    """The next ~size bytes of text from `off` (ending on a line break), with every citation
+    checked by the Core ML model. Returns text plus spans [start, end, status, why]."""
+    planting = src == "planted"
+    if planting:
+        src = "cold"
+    m = _wall_map(src)
+    n = len(m)
+    off %= n
+    end = m.find(b"\n", min(n, off + size))
+    end = n if end < 0 else end + 1
+    raw = m[off:end]
+    nxt = end if end < n else 0                     # loop at the end of the corpus
+    t = raw.decode("utf-8", errors="replace").replace("\r\n", "\n").replace("\r", "\n").replace("\x0c", "\n")
+    ranges = []
+    if planting:                                   # the model below only ever sees the mutated text
+        t, ranges = plant_text(t, PLANT_RATE, seed=off)
+    t0 = time.perf_counter()
+    found = text.extract(t)
+    codes = text.encode([c for _, _, c in found])
+    t1 = time.perf_counter()
+    p, ev, c, label, ms = run(codes)
+    spans, flagged, caught, missed = [], 0, 0, 0
+    for (s_, e_, cite), pi, evi, ci in zip(found, p, ev, c):
+        status = "phantom" if pi >= 0.5 else ("unknown" if pi > 0.1 else "ok")
+        why = ""
+        if status != "ok":
+            d = describe(pi, evi, ci)
+            why = "; ".join(explain(d, cite))
+            flagged += status == "phantom"
+        planted = any(a < e_ and s_ < b for a, b in ranges)
+        caught += planted and status == "phantom"
+        missed += planted and status != "phantom"
+        spans.append([s_, e_, status, why, planted])
+    return dict(text=t, spans=spans, next=nxt, bytes=len(raw), n=len(found), flagged=flagged,
+                planted=len(ranges), caught=caught, missed=missed,
+                model=label, model_ms=round(ms, 3), tokenize_ms=round((t1 - t0) * 1e3, 3))
+
+
+SWIFT = open(os.path.join(ROOT, "results", "bench_swift.txt")).read()
+
+
+def swift_headline():
+    """Pull the header-card numbers out of the native benchmark log."""
+    import re
+    out = {}
+    for line in SWIFT.splitlines():
+        m = re.match(r"b(\d+)\s+(\w+)\s+p50\s+([\d.]+) us.*?(\d+) cites/s", line)
+        if m:
+            out[f"b{m[1]}_{m[2]}"] = dict(p50_us=float(m[3]), per_sec=int(m[4]))
+        m = re.match(r"concurrent (.*) -> (\d+) cites/s", line)
+        if m:
+            out["concurrent:" + re.sub(r" [\d.]+k/s", "", m[1])] = int(m[2])
+    return out
+
+
+def info():
+    return dict(params=TOTAL, nonzero=NONZERO, evidence=[dict(name=e[0], weight=e[1], cap=e[2], text=e[3]) for e in spec.EVIDENCE],
+                bias=spec.BIAS, swift=SWIFT, headline=swift_headline(),
+                layers=dict(rep=len([n for n in META["features"] if n.startswith(("rep:", "series:", "other:"))]),
+                            court=len([n for n in META["features"] if n.startswith("court:")]),
+                            concepts=len(CONCEPTS), rules=len(META["rules"]), evidence=len(EVIDENCE)),
+                curves=sorted(spec.CURVES))
+
+
+class H(BaseHTTPRequestHandler):
+    def log_message(self, *a):
+        pass
+
+    def send(self, obj, code=200, ctype="application/json"):
+        body = obj if isinstance(obj, bytes) else json.dumps(obj).encode()
+        self.send_response(code)
+        self.send_header("Content-Type", ctype)
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self):
+        path, _, q = self.path.partition("?")
+        args = dict(kv.split("=", 1) for kv in q.split("&") if "=" in kv)
+        from urllib.parse import unquote
+        if path in ("/", "/index.html"):
+            return self.send(open(os.path.join(ROOT, "demo", "index.html"), "rb").read(), ctype="text/html; charset=utf-8")
+        if path == "/wall":
+            return self.send(open(os.path.join(ROOT, "demo", "wall.html"), "rb").read(), ctype="text/html; charset=utf-8")
+        if path == "/wall/random":
+            return self.send(wall_random(args.get("src", "cold")))
+        if path == "/wall/chunk":
+            LAST_ACTIVE[0] = time.time()
+            return self.send(wall_chunk(args.get("src", "cold"), int(args.get("off", 0)),
+                                        min(int(args.get("size", 16384)), 1 << 20)))
+        if path == "/live":
+            return self.send(open(os.path.join(ROOT, "demo", "live.html"), "rb").read(), ctype="text/html; charset=utf-8")
+        if path == "/live/info":
+            return self.send(corpus_info() or {"error": "no corpus"})
+        if path == "/live/stream":
+            return live_stream(self, args.get("loop") == "1")
+        if path == "/inspect":          # detailed view: neurons, filters, volume/year curves
+            return self.send(open(os.path.join(ROOT, "demo", "inspect.html"), "rb").read(), ctype="text/html; charset=utf-8")
+        if path == "/info":
+            return self.send(info())
+        if path == "/sample":
+            kind = args.get("kind", "brief")
+            return self.send(lepc_sample() if kind == "lepc" else dict(text=SAMPLES[kind]))
+        if path == "/curve":
+            return self.send(curve_payload(unquote(args["key"])))
+        if path == "/filter":
+            f = filter_payload(unquote(args["name"]))
+            return self.send(f) if f else self.send({"error": "no such filter"}, 404)
+        if path == "/fired":
+            return self.send(filters_fired(unquote(args["cite"])))
+        if path == "/bench":
+            return self.send(bench_eval())
+        if path == "/firehose":
+            return self.send(firehose(min(int(args.get("n", 1000000)), 20_000_000), unquote(args.get("lanes", "ane+gpu"))))
+        self.send({"error": "not found"}, 404)
+
+    def do_POST(self):
+        n = int(self.headers.get("Content-Length", 0))
+        body = json.loads(self.rfile.read(n) or b"{}")
+        if self.path == "/check":
+            return self.send(check_text(body.get("text", "")))
+        self.send({"error": "not found"}, 404)
+
+
+if __name__ == "__main__":
+    run(text.encode(["347 U.S. 483 (1954)"]))                     # warm up all three models
+    run(text.encode(["347 U.S. 483 (1954)"] * 20))
+    run(text.encode(["347 U.S. 483 (1954)"] * 100))
+    threading.Thread(target=keep_warm, daemon=True).start()
+    print(f"CiteNet demo on http://localhost:{PORT}  ({TOTAL:,} params, {NONZERO:,} nonzero, all hand-written)")
+    ThreadingHTTPServer(("127.0.0.1", PORT), H).serve_forever()

demo/wall.html

@@ -0,0 +1,311 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>CiteNet Wall</title>
+<style>
+:root {
+  --bg: #f7f6f2; --panel: #ffffff; --ink: #1c1b19; --muted: #77746b; --faint: #8f8b80; --line: #e6e3da;
+  --ok: #1f7a4d; --ok-bg: #dcefe3; --bad: #c2321f; --bad-bg: #f9dcd6; --warn: #a86a00; --warn-bg: #f8ebcc;
+  --mono: ui-monospace, "SF Mono", Menlo, monospace;
+  --serif: "Iowan Old Style", Palatino, Georgia, serif;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #121210; --panel: #1a1917; --ink: #ecebe6; --muted: #918e85; --faint: #8a877e; --line: #2b2a26;
+    --ok: #4fc487; --ok-bg: #1b3325; --bad: #ff7a66; --bad-bg: #4a221b; --warn: #f0b545; --warn-bg: #3b2f17;
+  }
+}
+* { box-sizing: border-box; }
+html, body { height: 100%; }
+body { margin: 0; background: var(--bg); color: var(--ink); font: 14px/1.5 -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
+       display: flex; flex-direction: column; overflow: hidden; }
+header { padding: 14px 22px 10px; display: flex; gap: 10px 18px; align-items: center; flex-wrap: wrap; border-bottom: 1px solid var(--line); }
+h1 { margin: 0; font-size: 20px; letter-spacing: -0.02em; }
+.group { display: flex; gap: 4px; align-items: center; }
+.group span { color: var(--muted); font-size: 12px; margin-right: 4px; }
+button { font: inherit; font-size: 13px; border: 1px solid var(--line); background: var(--panel); color: var(--ink); padding: 4px 10px; border-radius: 999px; cursor: pointer; }
+button.on { border-color: var(--ink); background: var(--ink); color: var(--bg); }
+header a { color: var(--muted); font-size: 13px; }
+.stats { padding: 8px 22px; display: flex; gap: 6px 22px; flex-wrap: wrap; color: var(--muted); font-size: 13px; font-variant-numeric: tabular-nums; border-bottom: 1px solid var(--line); }
+.stats b { color: var(--ink); font-weight: 600; }
+.stats .bad { color: var(--bad); }
+main { flex: 1; display: flex; min-height: 0; }
+.viewport { flex: 1; overflow: hidden; position: relative; cursor: pointer; min-width: 0;
+            -webkit-mask-image: linear-gradient(to bottom, transparent 0, #000 6%, #000 88%, transparent 100%);
+            mask-image: linear-gradient(to bottom, transparent 0, #000 6%, #000 88%, transparent 100%); }
+.wall { position: absolute; left: 0; right: 0; top: 0; will-change: transform; }
+.chunk { max-width: 1180px; margin: 0 auto; padding: 0 22px; font: 14.5px/1.62 var(--serif); color: var(--faint); white-space: pre-wrap; overflow-wrap: break-word; }
+.case { display: inline-block; color: var(--ink); font: 600 13px/1.4 -apple-system, system-ui, sans-serif; margin-top: 10px; }
+mark { border-radius: 3px; padding: 0 1px; color: var(--ink); }
+mark.ok { background: var(--ok-bg); }
+mark.unknown { background: var(--warn-bg); }
+mark.phantom { background: var(--bad-bg); box-shadow: inset 0 -2px 0 var(--bad); font-weight: 600; }
+mark.missed { outline: 2px dashed var(--bad); }
+.tag.miss { background: var(--muted); }
+.q .b { font: 600 10px/1 -apple-system, system-ui, sans-serif; text-transform: uppercase; letter-spacing: .05em; color: var(--muted); margin-left: 6px; }
+.tag { font: 600 11px/1 -apple-system, system-ui, sans-serif; color: #fff; background: var(--bad); border-radius: 4px; padding: 2px 6px; margin-left: 4px; white-space: nowrap; vertical-align: 1px; }
+.readline { position: absolute; left: 0; right: 0; top: 55%; border-top: 1px dashed var(--line); pointer-events: none; }
+.readline span { position: absolute; right: 10px; top: -9px; font-size: 11px; color: var(--muted); background: var(--bg); padding: 0 4px; }
+mark.hit { animation: hit .6s ease-out; }
+@keyframes hit { from { outline: 3px solid var(--ink); } to { outline: 3px solid transparent; } }
+aside { width: 380px; border-left: 1px solid var(--line); display: flex; flex-direction: column; min-height: 0; background: var(--panel); }
+aside h2 { margin: 0; padding: 10px 14px 6px; font-size: 11px; text-transform: uppercase; letter-spacing: .07em; color: var(--muted); font-weight: 600;
+           display: flex; justify-content: space-between; }
+aside h2 b { color: var(--ink); font-variant-numeric: tabular-nums; }
+.reds { max-height: 38%; overflow-y: auto; border-bottom: 1px solid var(--line); padding-bottom: 6px; }
+.reds .empty { color: var(--muted); font-size: 13px; padding: 2px 14px 6px; }
+.lights { flex: 1; overflow: hidden; -webkit-mask-image: linear-gradient(to bottom, #000 75%, transparent); mask-image: linear-gradient(to bottom, #000 75%, transparent); }
+.q { display: grid; grid-template-columns: 9px minmax(0, 1fr); gap: 1px 9px; padding: 4px 14px; align-items: baseline; }
+.q i { width: 9px; height: 9px; border-radius: 50%; background: var(--ok); display: inline-block; }
+.q.unknown i { background: var(--warn); }
+.q.phantom i { background: var(--bad); }
+.q.missedrow i { background: transparent; border: 2px solid var(--bad); }
+.q .c { font: 12.5px/1.35 var(--mono); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.q.phantom .c { color: var(--bad); white-space: normal; overflow-wrap: anywhere; }
+.q .w { grid-column: 2; color: var(--muted); font-size: 12.5px; line-height: 1.35; }
+.q.new { animation: slide .35s ease-out; }
+@keyframes slide { from { background: var(--line); } to { background: transparent; } }
+button.play { font-weight: 600; border-color: var(--bad); color: var(--bad); }
+button.play.on { background: var(--bad); color: #fff; border-color: var(--bad); }
+.runbar { position: absolute; left: 0; top: 0; height: 3px; background: var(--bad); width: 0; z-index: 2; }
+.summary { position: absolute; left: 50%; top: 38%; transform: translate(-50%, -50%); z-index: 3; display: none;
+           background: var(--panel); border: 1px solid var(--line); border-radius: 14px; padding: 18px 26px; text-align: center;
+           box-shadow: 0 10px 40px rgba(0,0,0,.35); min-width: 360px; cursor: pointer; }
+.summary .t { font-size: 12px; text-transform: uppercase; letter-spacing: .08em; color: var(--muted); }
+.summary .big { font-size: 34px; font-weight: 700; letter-spacing: -0.02em; margin: 4px 0 8px; font-variant-numeric: tabular-nums; }
+.summary .row { color: var(--muted); font-size: 14px; font-variant-numeric: tabular-nums; line-height: 1.7; }
+.summary .row b { color: var(--ink); }
+.summary .row .bad { color: var(--bad); }
+.summary .hint { color: var(--faint); font-size: 12px; margin-top: 8px; }
+.paused { position: absolute; right: 22px; top: 14px; font-size: 12px; color: var(--muted); background: var(--panel); border: 1px solid var(--line); border-radius: 6px; padding: 3px 8px; display: none; }
+@media (max-width: 900px) {
+  main { flex-direction: column; }
+  aside { width: auto; height: 34vh; border-left: 0; border-top: 1px solid var(--line); }
+  header, .stats { padding-left: 16px; padding-right: 16px; } .chunk { padding: 0 16px; font-size: 14px; }
+}
+</style>
+</head>
+<body>
+<header>
+  <h1>CiteNet Wall</h1>
+  <div class="group"><span>Text</span>
+    <button data-src="planted" class="on" title="real opinions with ~1 in 11 citations mutated into impossible ones">Opinions + planted fakes</button>
+    <button data-src="cold">Court opinions</button>
+    <button data-src="lepc">LePhantomCite briefs</button>
+  </div>
+  <div class="group"><span>Speed</span>
+    <button data-speed="45">Read</button>
+    <button data-speed="400" class="on">Fast</button>
+    <button data-speed="2500">Faster</button>
+    <button data-speed="9000">Max</button>
+  </div>
+  <button id="play" class="play" title="fresh run for exactly 30 seconds at the selected speed, then stop">▶ 30 s</button>
+  <button id="pause" title="pause / resume (space, or click the text)">❚❚ Pause</button>
+  <a href="/live">Full-speed scan</a> <a href="/">Back</a>
+</header>
+<div class="stats" id="stats">&nbsp;</div>
+<main>
+  <div class="viewport" id="vp">
+    <div class="wall" id="wall"></div>
+    <div class="readline"><span>citations join the queue here</span></div>
+    <div class="paused" id="paused">paused</div>
+    <div class="runbar" id="runbar"></div>
+    <div class="summary" id="summary"></div>
+  </div>
+  <aside>
+    <h2><span>Phantoms</span><b id="n-red">0</b></h2>
+    <div class="reds" id="reds"><div class="empty">None yet.</div></div>
+    <h2><span>Queue</span><b id="n-lit">0</b></h2>
+    <div class="lights" id="lights"></div>
+  </aside>
+</main>
+
+<script>
+const $ = (id) => document.getElementById(id);
+const vp = $("vp"), wall = $("wall");
+const ENT = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: "\u00a0", sect: "\u00a7", para: "\u00b6" };
+const unent = (s) => s.replace(/&(#\d+|[a-z]+);/g, (m, e) => e[0] === "#" ? String.fromCharCode(+e.slice(1)) : (ENT[e] ?? m));
+const esc = (s) => unent(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+let pending = [], lit = 0, reds = 0;
+const RUN_S = 30;
+let runLeft = 0;            // seconds left in a 30 s run (0 = not in a run)
+let src = "planted", speed = 400, y = 0, next = 0, inflight = false, paused = false, gen = 0;
+let tot = { bytes: 0, cites: 0, flagged: 0, chunks: 0, planted: 0, caught: 0, missed: 0 }, recentMs = [], lastModel = "", px = 0, lastPx = 0, lastT = performance.now();
+
+function render(c, first) {
+  const t = c.text; let h = "", pos = 0;
+  for (const [s, e, st, why, planted] of c.spans) {
+    const cls = st + (planted ? " planted" : "") + (planted && st !== "phantom" ? " missed" : "");
+    h += esc(t.slice(pos, s)) + `<mark class="${cls}" data-why="${esc(why)}"${why ? ` title="${esc(why)}"` : ""}>${esc(t.slice(s, e))}</mark>`;
+    if (st === "phantom") h += `<span class="tag">${planted ? "planted · " : ""}${esc(why)}</span>`;
+    else if (planted) h += `<span class="tag miss">missed planted fake</span>`;
+    pos = e;
+  }
+  h += esc(t.slice(pos));
+  // a decision starts after a triple line break with a "case name, court, date" line
+  h = h.replace(/\n\n\n([^\n<]{3,220})\n/g, "\n\n\n<span class=\"case\">$1</span>\n");
+  if (first && src === "cold") h = h.replace(/^([^\n<]{3,220})\n/, "<span class=\"case\">$1</span>\n");
+  const d = document.createElement("div");
+  d.className = "chunk"; d.innerHTML = h;
+  return d;
+}
+
+async function fetchMore(g) {
+  inflight = true;
+  const size = speed >= 2500 ? 65536 : 12288;          // bigger chunks when scrolling fast
+  const c = await fetch(`/wall/chunk?src=${src}&off=${next}&size=${size}`).then(r => r.json());
+  inflight = false;
+  if (g !== gen) return;
+  next = c.next;
+  const d = render(c, tot.chunks === 0); d.dataset.bytes = c.bytes;
+  wall.appendChild(d);
+  pending.push(...d.querySelectorAll("mark"));
+  tot.bytes += c.bytes; tot.cites += c.n; tot.flagged += c.flagged; tot.chunks += 1;
+  tot.planted += c.planted || 0; tot.caught += c.caught || 0; tot.missed += c.missed || 0;
+  recentMs.push([c.model_ms, c.bytes]); if (recentMs.length > 25) recentMs.shift();
+  lastModel = c.model;
+}
+
+function stats() {
+  // scroll rate in bytes: pixels scrolled per second times bytes per pixel of the text on screen
+  const now = performance.now(), dt = (now - lastT) / 1000;
+  const pps = (px - lastPx) / Math.max(dt, 1e-3); lastPx = px; lastT = now;
+  let b = 0; for (const ch of wall.children) b += +ch.dataset.bytes || 0;
+  const kbs = pps * (b / Math.max(1, wall.scrollHeight)) / 1000;
+  const unit = lastModel.includes("ANE") ? "Neural Engine" : "CPU";
+  const sorted = [...recentMs].sort((a, b) => a[0] - b[0]), mid = sorted[sorted.length >> 1] || [0, 0];
+  const per = mid[0], chunkKB = Math.round(mid[1] / 1024);
+  $("stats").innerHTML =
+    `<span><b>${(tot.bytes / 1e6).toFixed(2)} MB</b> read</span>` +
+    `<span><b>${tot.cites.toLocaleString()}</b> citations highlighted</span>` +
+    (src === "planted"
+      ? `<span><b>${tot.planted.toLocaleString()}</b> fakes planted</span><span class="bad"><b class="bad">${tot.caught.toLocaleString()}</b> caught</span>` +
+        `<span><b>${tot.missed.toLocaleString()}</b> missed</span><span><b>${(tot.flagged - tot.caught).toLocaleString()}</b> found in the source</span>`
+      : `<span class="bad"><b class="bad">${tot.flagged.toLocaleString()}</b> phantom</span>`) +
+    `<span>each ${chunkKB} KB chunk checked in <b>${per.toFixed(2)} ms</b> on the ${unit}</span>` +
+    `<span>scrolling <b>${kbs < 1 ? Math.round(kbs * 1000) + " B/s" : kbs < 1000 ? kbs.toFixed(0) + " KB/s" : (kbs / 1000).toFixed(1) + " MB/s"}</b></span>`;
+}
+
+let last = performance.now();
+function frame(t) {
+  const dt = Math.min(0.1, (t - last) / 1000); last = t;
+  const vh = vp.clientHeight;
+  if (runLeft > 0 && !paused) {
+    runLeft -= dt;
+    $("runbar").style.width = (100 * (1 - Math.max(0, runLeft) / RUN_S)) + "%";
+    $("play").textContent = "0:" + String(Math.ceil(Math.max(0, runLeft))).padStart(2, "0");
+    if (runLeft <= 0) finishRun();
+  }
+  if (!paused) {
+    const room = wall.scrollHeight - y - vh;
+    const step = Math.min(speed * dt, Math.max(0, room));      // never scroll past what has been checked
+    y += step; px += step;
+  }
+  // drop chunks that have scrolled off the top
+  while (wall.firstChild && wall.firstChild.offsetHeight < y - vh * 0.2) {
+    y -= wall.firstChild.offsetHeight;
+    wall.removeChild(wall.firstChild);
+  }
+  wall.style.transform = `translate3d(0, ${-y}px, 0)`;
+  // citations that crossed the reading line join the queue, in reading order
+  const line = vp.getBoundingClientRect().top + vh * 0.55;
+  let moved = 0;
+  while (pending.length && moved < 40) {
+    const m = pending[0];
+    if (!m.isConnected) { pending.shift(); continue; }
+    if (m.getBoundingClientRect().top > line) break;
+    pending.shift(); enqueue(m); moved++;
+  }
+  if (!inflight && wall.scrollHeight - y < vh * 3 + speed * 1.5) fetchMore(gen);   // keep ~1.5 s of text ahead
+  requestAnimationFrame(frame);
+}
+
+function enqueue(m) {
+  const st = m.className.split(" ")[0], why = m.dataset.why;
+  const planted = m.classList.contains("planted"), missed = m.classList.contains("missed");
+  m.classList.add("hit");
+  const row = document.createElement("div");
+  row.className = `q ${missed ? "phantom missedrow" : st} new`;
+  const badge = src === "planted" && st === "phantom" ? `<span class="b">${planted ? "planted" : "in source"}</span>` : missed ? `<span class="b">missed</span>` : "";
+  row.innerHTML = `<i></i><span class="c">${esc(m.textContent)}${badge}</span>` + (why && st !== "ok" ? `<span class="w">${esc(why)}</span>` : "");
+  const L = $("lights");
+  L.prepend(row);
+  while (L.children.length > 80) L.lastChild.remove();
+  $("n-lit").textContent = (++lit).toLocaleString();
+  if (st === "phantom" || missed) {
+    const R = $("reds");
+    if (!reds) R.innerHTML = "";
+    R.prepend(row.cloneNode(true));
+    while (R.children.length > 40) R.lastChild.remove();
+    $("n-red").textContent = (++reds).toLocaleString();
+  }
+}
+
+async function start(newSrc) {
+  src = newSrc; gen += 1; y = 0; wall.innerHTML = "";
+  pending = []; lit = 0; reds = 0;
+  $("lights").innerHTML = ""; $("reds").innerHTML = `<div class="empty">None yet.</div>`;
+  $("n-lit").textContent = "0"; $("n-red").textContent = "0";
+  tot = { bytes: 0, cites: 0, flagged: 0, chunks: 0, planted: 0, caught: 0, missed: 0 }; recentMs = [];
+  document.querySelectorAll("[data-src]").forEach(b => b.classList.toggle("on", b.dataset.src === src));
+  next = (await fetch(`/wall/random?src=${src}`).then(r => r.json())).off;
+  inflight = false;
+}
+
+document.querySelectorAll("[data-src]").forEach(b => b.onclick = () => start(b.dataset.src));
+document.querySelectorAll("[data-speed]").forEach(b => b.onclick = () => {
+  speed = +b.dataset.speed;
+  document.querySelectorAll("[data-speed]").forEach(x => x.classList.toggle("on", x === b));
+});
+function syncPause() {
+  $("pause").textContent = paused ? "▶ Resume" : "❚❚ Pause";
+  $("pause").classList.toggle("on", paused);
+  $("paused").style.display = paused && $("summary").style.display !== "block" ? "block" : "none";
+}
+const toggle = () => {
+  if ($("summary").style.display === "block") { $("summary").style.display = "none"; }
+  paused = !paused;
+  syncPause();
+};
+
+function finishRun() {
+  runLeft = 0; paused = true;
+  $("play").classList.remove("on"); $("play").textContent = "↻ 30 s";
+  const planted = src === "planted";
+  const kb = tot.bytes / 1000;
+  $("summary").innerHTML =
+    `<div class="t">${RUN_S} seconds · ${{ planted: "opinions + planted fakes", cold: "court opinions", lepc: "LePhantomCite briefs" }[src]} · ${document.querySelector("[data-speed].on").textContent}</div>` +
+    `<div class="big">${tot.cites.toLocaleString()} citations checked</div>` +
+    `<div class="row"><b>${kb < 1000 ? kb.toFixed(0) + " KB" : (kb / 1000).toFixed(2) + " MB"}</b> of text read · ` +
+    `each chunk checked in <b>${$("stats").querySelector("span:nth-last-child(2) b")?.textContent || "–"}</b> on the Neural Engine</div>` +
+    `<div class="row">` + (planted
+      ? `<b>${tot.planted}</b> fakes planted · <b class="bad">${tot.caught}</b> caught · <b>${tot.missed}</b> missed · <b>${tot.flagged - tot.caught}</b> found in the source`
+      : `<b class="bad">${tot.flagged}</b> phantom citations flagged`) + `</div>` +
+    `<div class="hint">click to keep reading</div>`;
+  $("summary").style.display = "block";
+  syncPause();
+}
+
+$("play").onclick = async (e) => {
+  e.stopPropagation();
+  $("summary").style.display = "none"; $("paused").style.display = "none";
+  await start(src);
+  paused = false; runLeft = RUN_S; syncPause();
+  $("play").classList.add("on"); $("runbar").style.width = "0";
+};
+vp.onclick = toggle;
+$("pause").onclick = (e) => { e.stopPropagation(); toggle(); };
+document.addEventListener("keydown", (e) => { if (e.code === "Space") { e.preventDefault(); toggle(); } });
+
+const q = new URLSearchParams(location.search);
+if (q.get("speed")) { const b = document.querySelector(`[data-speed="${q.get("speed")}"]`); if (b) b.click(); }
+start(q.get("src") || "planted").then(() => {
+  requestAnimationFrame(frame);
+  if (q.get("play")) $("play").click();
+});
+setInterval(stats, 250);
+</script>
+</body>
+</html>

models/CiteNet_b1.mlpackage/Data/com.apple.CoreML/model.mlmodel

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ec3a0cfb04508460da297d90e6d5ac3f4fda5f924039e6209905c8836d12ef6b
+size 15201

models/CiteNet_b1.mlpackage/Data/com.apple.CoreML/weights/weight.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9f6b5d99f5e879552c83f6163c09b705de858c8ef3c4910d0dced667d2042eef
+size 795972

models/CiteNet_b1.mlpackage/Manifest.json

@@ -0,0 +1,18 @@
+{
+    "fileFormatVersion": "1.0.0",
+    "itemInfoEntries": {
+        "B756F141-B556-40C4-B761-26475A7395DF": {
+            "author": "com.apple.CoreML",
+            "description": "CoreML Model Weights",
+            "name": "weights",
+            "path": "com.apple.CoreML/weights"
+        },
+        "BB7691E4-DCAA-452B-B171-DCCC5C95FAB9": {
+            "author": "com.apple.CoreML",
+            "description": "CoreML Model Specification",
+            "name": "model.mlmodel",
+            "path": "com.apple.CoreML/model.mlmodel"
+        }
+    },
+    "rootModelIdentifier": "BB7691E4-DCAA-452B-B171-DCCC5C95FAB9"
+}

models/CiteNet_b32.mlpackage/Data/com.apple.CoreML/model.mlmodel

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0005b22c1df3adfe2c105594c815affa760d9cc38894b1aa6574c857341eb9f4
+size 15202

models/CiteNet_b32.mlpackage/Data/com.apple.CoreML/weights/weight.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9f6b5d99f5e879552c83f6163c09b705de858c8ef3c4910d0dced667d2042eef
+size 795972

models/CiteNet_b32.mlpackage/Manifest.json

@@ -0,0 +1,18 @@
+{
+    "fileFormatVersion": "1.0.0",
+    "itemInfoEntries": {
+        "4B03BD52-4F51-47DE-95C8-E345C5F7F1BD": {
+            "author": "com.apple.CoreML",
+            "description": "CoreML Model Weights",
+            "name": "weights",
+            "path": "com.apple.CoreML/weights"
+        },
+        "4EF2FA4D-6F4A-4DCF-A2A1-B32C86D83C3D": {
+            "author": "com.apple.CoreML",
+            "description": "CoreML Model Specification",
+            "name": "model.mlmodel",
+            "path": "com.apple.CoreML/model.mlmodel"
+        }
+    },
+    "rootModelIdentifier": "4EF2FA4D-6F4A-4DCF-A2A1-B32C86D83C3D"
+}

models/CiteNet_b512.mlpackage/Data/com.apple.CoreML/model.mlmodel

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:67b85f25cbf21b2433a14f0631b77bf8c18df9f647003a2d209b93dcfe7e825d
+size 15244

models/CiteNet_b512.mlpackage/Data/com.apple.CoreML/weights/weight.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9f6b5d99f5e879552c83f6163c09b705de858c8ef3c4910d0dced667d2042eef
+size 795972

models/CiteNet_b512.mlpackage/Manifest.json

@@ -0,0 +1,18 @@
+{
+    "fileFormatVersion": "1.0.0",
+    "itemInfoEntries": {
+        "7CD9686B-F9F7-4E15-92F2-4388F2E4A50A": {
+            "author": "com.apple.CoreML",
+            "description": "CoreML Model Specification",
+            "name": "model.mlmodel",
+            "path": "com.apple.CoreML/model.mlmodel"
+        },
+        "960033A0-1526-47ED-8F07-3A7AA6BAF996": {
+            "author": "com.apple.CoreML",
+            "description": "CoreML Model Weights",
+            "name": "weights",
+            "path": "com.apple.CoreML/weights"
+        }
+    },
+    "rootModelIdentifier": "7CD9686B-F9F7-4E15-92F2-4388F2E4A50A"
+}

models/CiteNet_lean_b512.mlpackage/Data/com.apple.CoreML/model.mlmodel

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ebba1df193dae2767ce365708488b28cb5609a30227cc9d4b6d70979b1b8d6ab
+size 14674

models/CiteNet_lean_b512.mlpackage/Data/com.apple.CoreML/weights/weight.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9f6b5d99f5e879552c83f6163c09b705de858c8ef3c4910d0dced667d2042eef
+size 795972

models/CiteNet_lean_b512.mlpackage/Manifest.json

@@ -0,0 +1,18 @@
+{
+    "fileFormatVersion": "1.0.0",
+    "itemInfoEntries": {
+        "F3AF92E8-6810-444E-8DCD-DCE24722DD8D": {
+            "author": "com.apple.CoreML",
+            "description": "CoreML Model Weights",
+            "name": "weights",
+            "path": "com.apple.CoreML/weights"
+        },
+        "FE87E531-E500-4514-AC4C-357B5176D8EF": {
+            "author": "com.apple.CoreML",
+            "description": "CoreML Model Specification",
+            "name": "model.mlmodel",
+            "path": "com.apple.CoreML/model.mlmodel"
+        }
+    },
+    "rootModelIdentifier": "FE87E531-E500-4514-AC4C-357B5176D8EF"
+}

models/CiteNet_lean_b8192.mlpackage/Data/com.apple.CoreML/model.mlmodel

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d4a65ada73a068b4c8e1fa5f5a13b2bd11f33425f73514f4fab5aa010bd4c946
+size 14674

models/CiteNet_lean_b8192.mlpackage/Data/com.apple.CoreML/weights/weight.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9f6b5d99f5e879552c83f6163c09b705de858c8ef3c4910d0dced667d2042eef
+size 795972

models/CiteNet_lean_b8192.mlpackage/Manifest.json

@@ -0,0 +1,18 @@
+{
+    "fileFormatVersion": "1.0.0",
+    "itemInfoEntries": {
+        "54300A80-AA23-4C07-9E54-8525A1FA637F": {
+            "author": "com.apple.CoreML",
+            "description": "CoreML Model Specification",
+            "name": "model.mlmodel",
+            "path": "com.apple.CoreML/model.mlmodel"
+        },
+        "F475A9B2-83E4-48F8-9953-2EB8FAFACC89": {
+            "author": "com.apple.CoreML",
+            "description": "CoreML Model Weights",
+            "name": "weights",
+            "path": "com.apple.CoreML/weights"
+        }
+    },
+    "rootModelIdentifier": "54300A80-AA23-4C07-9E54-8525A1FA637F"
+}

models/meta.json

@@ -0,0 +1 @@
+{"features": ["rep:u.s.", "rep:us_#", "rep:us_at_", "rep:s.ct.", "rep:s ct", "rep:dall.", "rep:cranch", "rep:wheat.", "rep:pet.", "rep:how.", "rep:black", "rep:wall.", "rep:l.ed.", "rep:l.ed.2d", "rep:f.", "rep:f.2d", "rep:f.3d", "rep:f.4th", "rep:f.app'x", "rep:f.appx", "rep:fed.appx.", "rep:fed.appx", "rep:fed.app'x", "rep:fed.app.", "rep:f.supp.", "rep:f.supp_#", "rep:f.supp_at_", "rep:f.supp.2d", "rep:f.supp.3d", "rep:f.supp 2d", "rep:f.supp 3d", "rep:f.r.d.", "rep:b.r.", "rep:fed.cl.", "rep:ct.cl.", "rep:cl.ct.", "rep:f.cas.", "rep:ct.int'l", "rep:m.j.", "rep:a.", "rep:a.2d", "rep:a.3d", "rep:n.e.", "rep:n.e.2d", "rep:n.e.3d", "rep:n.w.", "rep:n.w.2d", "rep:n.w.3d", "rep:p.", "rep:p", "rep:p.2d", "rep:p.3d", "rep:s.e.", "rep:s.e.2d", "rep:s.e.3d", "rep:s.w.", "rep:s.w.2d", "rep:s.w.3d", "rep:so.", "rep:so.2d", "rep:so.3d", "rep:cal.rptr.", "rep:cal.rptr.2d", "rep:cal.rptr.3d", "rep:cal.", "rep:cal.2d", "rep:cal.3d", "rep:cal.4th", "rep:cal.5th", "rep:cal.app.", "rep:cal.app.2d", "rep:cal.app.3d", "rep:cal.app.4th", "rep:cal.app.5th", "rep:n.y.s.", "rep:n.y.s.2d", "rep:n.y.s.3d", "rep:n.y.", "rep:n.y.2d", "rep:n.y.3d", "rep:a.d.", "rep:a.d.2d", "rep:a.d.3d", "rep:misc.2d", "rep:misc.3d", "rep:mass.", "rep:mass.app.ct.", "rep:mass.app.", "rep:ill.", "rep:ill.2d", "rep:ill.app.", "rep:ill.app.2d", "rep:ill.app.3d", "rep:ill.dec.", "rep:ind.", "rep:ind.app.", "rep:okla.", "rep:va.", "rep:va.app.", "rep:va.cir.", "rep:pa.", "rep:pa.super.", "rep:pa.commw.", "rep:n.j.", "rep:n.j.super.", "rep:wash.", "rep:wash.2d", "rep:wash.app.", "rep:wash.app.2d", "rep:ohio st.3d", "rep:ohio app.3d", "rep:md.", "rep:md.app.", "rep:n.c.", "rep:n.c.app.", "rep:ga.", "rep:ga.app.", "rep:kan.", "rep:kan.app.", "rep:kan.app.2d", "rep:mich.", "rep:mich.app.", "rep:wis.2d", "rep:conn.", "rep:conn.app.", "rep:tex.", "rep:s.c.", "rep:r.i.", "rep:colo.", "rep:ariz.", "rep:or.", "rep:or.app.", "rep:wn.", "rep:wn.2d", "rep:wn.app.", "rep:wn.app.2d", "rep:neb.", "rep:neb.app.", "rep:n.m.", "rep:nev.", "rep:minn.", "rep:ark.", "rep:ark.app.", "rep:idaho", "rep:mont.", "rep:ohio st.", "rep:ohio st.2d", "rep:ohio app.", "rep:ohio app.2d", "rep:ala.", "rep:ala.app.", "rep:la.", "rep:iowa", "rep:miss.", "rep:wis.", "rep:w.va.", "rep:vt.", "rep:mo.", "rep:mo.app.", "rep:n.h.", "rep:ky.", "rep:tenn.", "rep:tenn.app.", "rep:del.", "rep:me.", "rep:haw.", "rep:wyo.", "rep:utah", "rep:utah 2d", "rep:n.d.", "rep:s.d.", "rep:alaska", "rep:ny", "rep:ny2d", "rep:ny3d", "rep:n y 2d", "rep:ad2d", "rep:ad3d", "rep:a d 2d", "rep:app.div.", "rep:app div", "rep:app.div.2d", "rep:misc.", "rep:misc 2d", "rep:misc 3d", "rep:misc.rep.", "rep:nys2d", "rep:nys3d", "rep:f2d", "rep:f3d", "rep:f4th", "rep:a2d", "rep:a3d", "rep:ne2d", "rep:ne3d", "rep:nw2d", "rep:p2d", "rep:p3d", "rep:se2d", "rep:sw2d", "rep:sw3d", "rep:so2d", "rep:so3d", "rep:wl", "other:fed.reg.", "other:fr", "other:u.s.c.", "other:c.f.r.", "other:stat.", "other:ferc", "other:t.c.", "other:c.m.r.", "other:cmr", "other:vet.app.", "other:b.t.a.", "other:fed.cir.", "other:c.c.p.a.", "other:o.s.", "other:ok neutral", "other:ok civ app", "other:op.o.l.c.", "other:op.att'y", "other:a.l.r.", "other:ilcs", "other:nlrb", "other:uscma", "other:cong.rec.", "other:l.r.a.", "other:r.s.", "other:burns", "other:ops.cal.atty", "other:d.p.r.", "other:dpr", "other:j.t.s.", "other:mal", "other:ut neutral", "other:ut app", "other:nd neutral", "other:ny slip op", "other:johns.", "other:wend.", "other:cow.", "other:barb.", "other:hun", "other:paige", "other:pick.", "other:cush.", "other:met.", "other:gray", "other:allen", "other:binn.", "other:watts", "series:ord4", "series:ord4s", "series:ord4c", "series:ord4sc", "series:ord5", "series:ord5s", "series:ord5c", "series:ord5sc", "series:ord6+", "series:ord6+s", "series:ord6+c", "series:ord6+sc", "other:lexis", "other:i&n", "other:law review", "other:law journal", "other:u.s.app.d.c.", "court:circuit", "court:circuit_dc", "court:circuit_fed", "court:district_x", "court:district_d", "court:bankruptcy", "court:bap", "court:year_only", "court:expl_quoting", "court:expl_citing", "court:expl_internal", "court:expl_alteration", "court:expl_emphasis", "court:expl_quotation", "court:expl_par1", "court:expl_par2", "court:expl_par3", "court:expl_affirmed", "court:expl_affd", "court:expl_revd", "court:expl_cert", "court:expl_vacated", "court:expl_overruled", "court:expl_abrogated", "court:expl_superseded", "court:expl_modified", "court:state_conn", "court:state_del", "court:state_me", "court:state_md", "court:state_n.h", "court:state_n.j", "court:state_pa", "court:state_r.i", "court:state_vt", "court:state_d.c", "court:state_ill", "court:state_ind", "court:state_mass", "court:state_n.y", "court:state_ohio", "court:state_iowa", "court:state_mich", "court:state_minn", "court:state_neb", "court:state_wis", "court:state_alaska", "court:state_ariz", "court:state_cal", "court:state_colo", "court:state_haw", "court:state_idaho", "court:state_kan", "court:state_mont", "court:state_nev", "court:state_n.m", "court:state_okla", "court:state_or", "court:state_utah", "court:state_wash", "court:state_wyo", "court:state_ga", "court:state_n.c", "court:state_s.c", "court:state_va", "court:state_w.va", "court:state_ark", "court:state_ky", "court:state_mo", "court:state_tenn", "court:state_tex", "court:state_ala", "court:state_fla", "court:state_la", "court:state_miss", "court:dc_app", "court:dc_mun", "num:vol1", "num:vol2", "num:vol3", "num:vol4", "num:year", "num:year20", "num:vol4y", "gate:vol1", "gate:vol2", "gate:vol3", "gate:vol4", "gate:year", "gate:year20", "gate:vol4y"], "concepts": ["class:BANKR", "class:BANKR^hi", "class:FEDAPP", "class:FEDAPP^hi", "class:FEDAPP_OLD", "class:FEDAPP_OLD^hi", "class:FEDDIST", "class:FEDDIST^hi", "class:FEDSPEC", "class:FEDSPEC^hi", "class:REGION", "class:REGION^hi", "class:SCOTUS", "class:SCOTUS^hi", "class:STATE", "class:STATE^hi", "class:WL", "class:WL^hi", "region:A", "region:A^hi", "region:NE", "region:NE^hi", "region:NW", "region:NW^hi", "region:P", "region:P^hi", "region:SE", "region:SE^hi", "region:SO", "region:SO^hi", "region:SW", "region:SW^hi", "home:ala", "home:ala^hi", "home:alaska", "home:alaska^hi", "home:ariz", "home:ariz^hi", "home:ark", "home:ark^hi", "home:cal", "home:cal^hi", "home:colo", "home:colo^hi", "home:conn", "home:conn^hi", "home:del", "home:del^hi", "home:ga", "home:ga^hi", "home:haw", "home:haw^hi", "home:idaho", "home:idaho^hi", "home:ill", "home:ill^hi", "home:ind", "home:ind^hi", "home:iowa", "home:iowa^hi", "home:kan", "home:kan^hi", "home:ky", "home:ky^hi", "home:la", "home:la^hi", "home:mass", "home:mass^hi", "home:md", "home:md^hi", "home:me", "home:me^hi", "home:mich", "home:mich^hi", "home:minn", "home:minn^hi", "home:miss", "home:miss^hi", "home:mo", "home:mo^hi", "home:mont", "home:mont^hi", "home:n.c", "home:n.c^hi", "home:n.d", "home:n.d^hi", "home:n.h", "home:n.h^hi", "home:n.j", "home:n.j^hi", "home:n.m", "home:n.m^hi", "home:n.y", "home:n.y^hi", "home:neb", "home:neb^hi", "home:nev", "home:nev^hi", "home:ohio", "home:ohio^hi", "home:okla", "home:okla^hi", "home:or", "home:or^hi", "home:pa", "home:pa^hi", "home:r.i", "home:r.i^hi", "home:s.c", "home:s.c^hi", "home:s.d", "home:s.d^hi", "home:tenn", "home:tenn^hi", "home:tex", "home:tex^hi", "home:utah", "home:utah^hi", "home:va", "home:va^hi", "home:vt", "home:vt^hi", "home:w.va", "home:w.va^hi", "home:wash", "home:wash^hi", "home:wis", "home:wis^hi", "home:wyo", "home:wyo^hi", "is:us", "is:us^hi", "is:sct", "is:sct^hi", "is:led", "is:led^hi", "is:led2", "is:led2^hi", "is:f1", "is:f1^hi", "is:f2", "is:f2^hi", "is:f3", "is:f3^hi", "is:f4", "is:f4^hi", "is:fs1", "is:fs1^hi", "is:fs2", "is:fs2^hi", "is:fs3", "is:fs3^hi", "is:fappx", "is:fappx^hi", "is:br", "is:br^hi", "is:frd", "is:frd^hi", "is:a2", "is:a2^hi", "is:a3", "is:a3^hi", "is:ne2", "is:ne2^hi", "is:ne3", "is:ne3^hi", "is:nw2", "is:nw2^hi", "is:p2", "is:p2^hi", "is:p3", "is:p3^hi", "is:se2", "is:se2^hi", "is:sw2", "is:sw2^hi", "is:sw3", "is:sw3^hi", "is:so2", "is:so2^hi", "is:so3", "is:so3^hi", "is:cr1", "is:cr1^hi", "is:cr2", "is:cr2^hi", "is:cr3", "is:cr3^hi", "is:nys2", "is:nys2^hi", "is:nys3", "is:nys3^hi", "is:wl", "is:wl^hi", "is:lexis", "is:lexis^hi", "phantom:4th", "phantom:5th", "phantom:6th+", "known_source", "expl", "court:circuit", "court:district", "court:bankruptcy", "state:conn", "state:del", "state:me", "state:md", "state:n.h", "state:n.j", "state:pa", "state:r.i", "state:vt", "state:d.c", "state:ill", "state:ind", "state:mass", "state:n.y", "state:ohio", "state:iowa", "state:mich", "state:minn", "state:neb", "state:wis", "state:alaska", "state:ariz", "state:cal", "state:colo", "state:haw", "state:idaho", "state:kan", "state:mont", "state:nev", "state:n.m", "state:okla", "state:or", "state:utah", "state:wash", "state:wyo", "state:ga", "state:n.c", "state:s.c", "state:va", "state:w.va", "state:ark", "state:ky", "state:mo", "state:tenn", "state:tex", "state:ala", "state:fla", "state:la", "state:miss", "court:year_only", "volume", "has_volume", "year", "year_hi", "has_year", "has_year^hi", "vol4y", "vol4y_hi", "future", "volume3", "has_vol4", "vol>0", "vol>2", "vol>4", "vol>6", "vol>8", "vol>10", "vol>15", "vol>20", "vol>30", "vol>40", "vol>50", "vol>60", "vol>75", "vol>90", "vol>100", "vol>125", "vol>150", "vol>175", "vol>200", "vol>250", "vol>300", "vol>350", "vol>400", "vol>450", "vol>500", "vol>550", "vol>600", "vol>650", "vol>700", "vol>750", "vol>800", "vol>850", "vol>900", "vol>950"], "rules": ["mm:SCOTUS", "mm:FEDAPP", "mm:FEDAPP_OLD", "mm:FEDDIST", "mm:BANKR", "mm:REGION_fed", "mm:STATE_fed", "mm:region_A", "mm:region_NE", "mm:region_NW", "mm:region_P", "mm:region_SE", "mm:region_SO", "mm:region_SW", "mm:home_ala", "mm:home_alaska", "mm:home_ariz", "mm:home_ark", "mm:home_cal", "mm:home_colo", "mm:home_conn", "mm:home_del", "mm:home_ga", "mm:home_haw", "mm:home_idaho", "mm:home_ill", "mm:home_ind", "mm:home_iowa", "mm:home_kan", "mm:home_ky", "mm:home_la", "mm:home_mass", "mm:home_md", "mm:home_me", "mm:home_mich", "mm:home_minn", "mm:home_miss", "mm:home_mo", "mm:home_mont", "mm:home_n.c", "mm:home_n.d", "mm:home_n.h", "mm:home_n.j", "mm:home_n.m", "mm:home_n.y", "mm:home_neb", "mm:home_nev", "mm:home_ohio", "mm:home_okla", "mm:home_or", "mm:home_pa", "mm:home_r.i", "mm:home_s.c", "mm:home_s.d", "mm:home_tenn", "mm:home_tex", "mm:home_utah", "mm:home_va", "mm:home_vt", "mm:home_w.va", "mm:home_wash", "mm:home_wis", "mm:home_wyo", "late:us", "early:us", "over:us", "over4:us", "late:sct", "early:sct", "over:sct", "over4:sct", "late:led", "early:led", "over:led", "over4:led", "late:led2", "early:led2", "over:led2", "over4:led2", "late:f1", "early:f1", "over:f1", "over4:f1", "late:f2", "early:f2", "over:f2", "over4:f2", "late:f3", "early:f3", "over:f3", "over4:f3", "late:f4", "early:f4", "over:f4", "over4:f4", "late:fs1", "early:fs1", "over:fs1", "over4:fs1", "late:fs2", "early:fs2", "over:fs2", "over4:fs2", "late:fs3", "early:fs3", "over:fs3", "over4:fs3", "late:fappx", "early:fappx", "over:fappx", "over4:fappx", "late:br", "early:br", "over:br", "over4:br", "late:frd", "early:frd", "over:frd", "over4:frd", "late:a2", "early:a2", "over:a2", "over4:a2", "late:a3", "early:a3", "over:a3", "over4:a3", "late:ne2", "early:ne2", "over:ne2", "over4:ne2", "late:ne3", "early:ne3", "over:ne3", "over4:ne3", "late:nw2", "early:nw2", "over:nw2", "over4:nw2", "late:p2", "early:p2", "over:p2", "over4:p2", "late:p3", "early:p3", "over:p3", "over4:p3", "late:se2", "early:se2", "over:se2", "over4:se2", "late:sw2", "early:sw2", "over:sw2", "over4:sw2", "late:sw3", "early:sw3", "over:sw3", "over4:sw3", "late:so2", "early:so2", "over:so2", "over4:so2", "late:so3", "early:so3", "over:so3", "over4:so3", "late:cr1", "early:cr1", "over:cr1", "over4:cr1", "late:cr2", "early:cr2", "over:cr2", "over4:cr2", "late:cr3", "early:cr3", "over:cr3", "over4:cr3", "late:nys2", "early:nys2", "over:nys2", "over4:nys2", "late:nys3", "early:nys3", "over:nys3", "over4:nys3", "late:wl", "early:wl", "late:lexis", "early:lexis", "r:phantom:4th", "r:phantom:5th", "r:phantom:6th+", "r:future", "r:unknown"], "evidence": ["phantom_series", "court_mismatch", "state_mismatch", "volume_year", "volume_missing", "future_year", "unknown_reporter"], "groups": {"court_mismatch": ["mm:SCOTUS", "mm:FEDAPP", "mm:FEDAPP_OLD", "mm:FEDDIST", "mm:BANKR", "mm:REGION_fed", "mm:STATE_fed"], "state_mismatch": ["mm:region_A", "mm:region_NE", "mm:region_NW", "mm:region_P", "mm:region_SE", "mm:region_SO", "mm:region_SW", "mm:home_ala", "mm:home_alaska", "mm:home_ariz", "mm:home_ark", "mm:home_cal", "mm:home_colo", "mm:home_conn", "mm:home_del", "mm:home_ga", "mm:home_haw", "mm:home_idaho", "mm:home_ill", "mm:home_ind", "mm:home_iowa", "mm:home_kan", "mm:home_ky", "mm:home_la", "mm:home_mass", "mm:home_md", "mm:home_me", "mm:home_mich", "mm:home_minn", "mm:home_miss", "mm:home_mo", "mm:home_mont", "mm:home_n.c", "mm:home_n.d", "mm:home_n.h", "mm:home_n.j", "mm:home_n.m", "mm:home_n.y", "mm:home_neb", "mm:home_nev", "mm:home_ohio", "mm:home_okla", "mm:home_or", "mm:home_pa", "mm:home_r.i", "mm:home_s.c", "mm:home_s.d", "mm:home_tenn", "mm:home_tex", "mm:home_utah", "mm:home_va", "mm:home_vt", "mm:home_w.va", "mm:home_wash", "mm:home_wis", "mm:home_wyo"], "volume_year": ["late:us", "early:us", "late:sct", "early:sct", "late:led", "early:led", "late:led2", "early:led2", "late:f1", "early:f1", "late:f2", "early:f2", "late:f3", "early:f3", "late:f4", "early:f4", "late:fs1", "early:fs1", "late:fs2", "early:fs2", "late:fs3", "early:fs3", "late:fappx", "early:fappx", "late:br", "early:br", "late:frd", "early:frd", "late:a2", "early:a2", "late:a3", "early:a3", "late:ne2", "early:ne2", "late:ne3", "early:ne3", "late:nw2", "early:nw2", "late:p2", "early:p2", "late:p3", "early:p3", "late:se2", "early:se2", "late:sw2", "early:sw2", "late:sw3", "early:sw3", "late:so2", "early:so2", "late:so3", "early:so3", "late:cr1", "early:cr1", "late:cr2", "early:cr2", "late:cr3", "early:cr3", "late:nys2", "early:nys2", "late:nys3", "early:nys3", "late:wl", "early:wl", "late:lexis", "early:lexis"], "volume_missing": ["over:us", "over4:us", "over:sct", "over4:sct", "over:led", "over4:led", "over:led2", "over4:led2", "over:f1", "over4:f1", "over:f2", "over4:f2", "over:f3", "over4:f3", "over:f4", "over4:f4", "over:fs1", "over4:fs1", "over:fs2", "over4:fs2", "over:fs3", "over4:fs3", "over:fappx", "over4:fappx", "over:br", "over4:br", "over:frd", "over4:frd", "over:a2", "over4:a2", "over:a3", "over4:a3", "over:ne2", "over4:ne2", "over:ne3", "over4:ne3", "over:nw2", "over4:nw2", "over:p2", "over4:p2", "over:p3", "over4:p3", "over:se2", "over4:se2", "over:sw2", "over4:sw2", "over:sw3", "over4:sw3", "over:so2", "over4:so2", "over:so3", "over4:so3", "over:cr1", "over4:cr1", "over:cr2", "over4:cr2", "over:cr3", "over4:cr3", "over:nys2", "over4:nys2", "over:nys3", "over4:nys3"], "phantom_series": ["r:phantom:4th", "r:phantom:5th", "r:phantom:6th+"], "future_year": ["r:future"], "unknown_reporter": ["r:unknown"]}, "anchored": ["rep:u.s.", "rep:us_#", "rep:us_at_", "rep:s.ct.", "rep:s ct", "rep:dall.", "rep:cranch", "rep:wheat.", "rep:pet.", "rep:how.", "rep:black", "rep:wall.", "rep:l.ed.", "rep:l.ed.2d", "rep:f.", "rep:f.2d", "rep:f.3d", "rep:f.4th", "rep:f.app'x", "rep:f.appx", "rep:fed.appx.", "rep:fed.appx", "rep:fed.app'x", "rep:fed.app.", "rep:f.supp.", "rep:f.supp_#", "rep:f.supp_at_", "rep:f.supp.2d", "rep:f.supp.3d", "rep:f.supp 2d", "rep:f.supp 3d", "rep:f.r.d.", "rep:b.r.", "rep:fed.cl.", "rep:ct.cl.", "rep:cl.ct.", "rep:f.cas.", "rep:ct.int'l", "rep:m.j.", "rep:a.", "rep:a.2d", "rep:a.3d", "rep:n.e.", "rep:n.e.2d", "rep:n.e.3d", "rep:n.w.", "rep:n.w.2d", "rep:n.w.3d", "rep:p.", "rep:p", "rep:p.2d", "rep:p.3d", "rep:s.e.", "rep:s.e.2d", "rep:s.e.3d", "rep:s.w.", "rep:s.w.2d", "rep:s.w.3d", "rep:so.", "rep:so.2d", "rep:so.3d", "rep:cal.rptr.", "rep:cal.rptr.2d", "rep:cal.rptr.3d", "rep:cal.", "rep:cal.2d", "rep:cal.3d", "rep:cal.4th", "rep:cal.5th", "rep:cal.app.", "rep:cal.app.2d", "rep:cal.app.3d", "rep:cal.app.4th", "rep:cal.app.5th", "rep:n.y.s.", "rep:n.y.s.2d", "rep:n.y.s.3d", "rep:n.y.", "rep:n.y.2d", "rep:n.y.3d", "rep:a.d.", "rep:a.d.2d", "rep:a.d.3d", "rep:misc.2d", "rep:misc.3d", "rep:mass.", "rep:mass.app.ct.", "rep:mass.app.", "rep:ill.", "rep:ill.2d", "rep:ill.app.", "rep:ill.app.2d", "rep:ill.app.3d", "rep:ill.dec.", "rep:ind.", "rep:ind.app.", "rep:okla.", "rep:va.", "rep:va.app.", "rep:va.cir.", "rep:pa.", "rep:pa.super.", "rep:pa.commw.", "rep:n.j.", "rep:n.j.super.", "rep:wash.", "rep:wash.2d", "rep:wash.app.", "rep:wash.app.2d", "rep:ohio st.3d", "rep:ohio app.3d", "rep:md.", "rep:md.app.", "rep:n.c.", "rep:n.c.app.", "rep:ga.", "rep:ga.app.", "rep:kan.", "rep:kan.app.", "rep:kan.app.2d", "rep:mich.", "rep:mich.app.", "rep:wis.2d", "rep:conn.", "rep:conn.app.", "rep:tex.", "rep:s.c.", "rep:r.i.", "rep:colo.", "rep:ariz.", "rep:or.", "rep:or.app.", "rep:wn.", "rep:wn.2d", "rep:wn.app.", "rep:wn.app.2d", "rep:neb.", "rep:neb.app.", "rep:n.m.", "rep:nev.", "rep:minn.", "rep:ark.", "rep:ark.app.", "rep:idaho", "rep:mont.", "rep:ohio st.", "rep:ohio st.2d", "rep:ohio app.", "rep:ohio app.2d", "rep:ala.", "rep:ala.app.", "rep:la.", "rep:iowa", "rep:miss.", "rep:wis.", "rep:w.va.", "rep:vt.", "rep:mo.", "rep:mo.app.", "rep:n.h.", "rep:ky.", "rep:tenn.", "rep:tenn.app.", "rep:del.", "rep:me.", "rep:haw.", "rep:wyo.", "rep:utah", "rep:utah 2d", "rep:n.d.", "rep:s.d.", "rep:alaska", "rep:ny", "rep:ny2d", "rep:ny3d", "rep:n y 2d", "rep:ad2d", "rep:ad3d", "rep:a d 2d", "rep:app.div.", "rep:app div", "rep:app.div.2d", "rep:misc.", "rep:misc 2d", "rep:misc 3d", "rep:misc.rep.", "rep:nys2d", "rep:nys3d", "rep:f2d", "rep:f3d", "rep:f4th", "rep:a2d", "rep:a3d", "rep:ne2d", "rep:ne3d", "rep:nw2d", "rep:p2d", "rep:p3d", "rep:se2d", "rep:sw2d", "rep:sw3d", "rep:so2d", "rep:so3d", "rep:wl", "other:fed.reg.", "other:fr", "other:u.s.c.", "other:c.f.r.", "other:stat.", "other:ferc", "other:t.c.", "other:c.m.r.", "other:cmr", "other:vet.app.", "other:b.t.a.", "other:fed.cir.", "other:c.c.p.a.", "other:o.s.", "other:ok neutral", "other:ok civ app", "other:op.o.l.c.", "other:op.att'y", "other:a.l.r.", "other:ilcs", "other:nlrb", "other:uscma", "other:cong.rec.", "other:l.r.a.", "other:r.s.", "other:burns", "other:ops.cal.atty", "other:d.p.r.", "other:dpr", "other:j.t.s.", "other:mal", "other:ut neutral", "other:ut app", "other:nd neutral", "other:ny slip op", "other:johns.", "other:wend.", "other:cow.", "other:barb.", "other:hun", "other:paige", "other:pick.", "other:cush.", "other:met.", "other:gray", "other:allen", "other:binn.", "other:watts"], "floating": ["series:ord4", "series:ord4s", "series:ord4c", "series:ord4sc", "series:ord5", "series:ord5s", "series:ord5c", "series:ord5sc", "series:ord6+", "series:ord6+s", "series:ord6+c", "series:ord6+sc", "other:lexis", "other:i&n", "other:law review", "other:law journal", "other:u.s.app.d.c."]}

models/weights.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8bad6f5b755fa19e6188f5ffe8581775157d0e01c7a96db42b7cf012058ef2d6
+size 19448

results/aux_train_v1.5.txt

@@ -0,0 +1,18 @@
+params 397,250 (nonzero 13,871)
+Counter({np.str_('genuine'): 2340, np.str_('other'): 634, np.str_('phantom'): 119})
+phantom recall 119/119 = 1.000
+genuine false-flag 2/2340 = 0.0009
+precision 0.983
+other-hallucination cites flagged 3/634
+cites where >1 reporter class fired: 0 []
+
+-- missed phantoms
+
+-- false flags
+  0.971 '588 F.3d 1318, 1328 (11th Cir. 2002);' -> '588 f.3d 1318, 1328 (11th cir. 2002)' [volume_year=3.00]
+  0.971 '395 U.S. 411, 421 (1959);' -> '395 u.s. 411, 421 (1959)' [volume_year=3.00]
+
+-- genuine but amber (0.1-0.5): 3
+  0.119 '23 p.r.offic.trans. 393' [unknown_reporter=1.00]
+  0.119 '773 f.3d. 138' [unknown_reporter=1.00]
+  0.119 '3 va.law rep. 1177 (va.ct.app. 1986)' [unknown_reporter=1.00]

results/bench_swift.txt

@@ -0,0 +1,17 @@
+b1    cpu  p50    50.1 us  p99    63.6 us     19538 cites/s
+b1    ane  p50    49.5 us  p99    62.5 us     19782 cites/s
+b32   cpu  p50   329.2 us  p99   353.6 us     96915 cites/s
+b32   ane  p50   169.5 us  p99   207.0 us    187674 cites/s
+b32   gpu  p50   330.1 us  p99   381.1 us     96141 cites/s
+b512  cpu  p50  4004.8 us  p99  4340.2 us    127204 cites/s
+b512  ane  p50  1213.6 us  p99  1279.0 us    421373 cites/s
+b512  gpu  p50   643.5 us  p99   781.5 us    786837 cites/s
+b2048 ane  p50  5598.4 us  p99  5770.8 us    365059 cites/s
+b2048 gpu  p50  1806.5 us  p99  2988.0 us   1083873 cites/s
+b8192 ane  p50 26298.8 us  p99 27173.3 us    310711 cites/s
+b8192 gpu  p50  6161.5 us  p99  6463.7 us   1327992 cites/s
+concurrent ane b512 421k/s -> 421079 cites/s
+concurrent gpu b8192 1320k/s -> 1320080 cites/s
+concurrent ane b512 409k/s + gpu b8192 1297k/s -> 1706405 cites/s
+concurrent ane b2048 357k/s + gpu b8192 1294k/s -> 1650628 cites/s
+concurrent ane b512 217k/s + ane b512 217k/s + gpu b8192 606k/s + gpu b8192 601k/s -> 1640213 cites/s

results/eval_v1.0_blind.txt

@@ -0,0 +1,29 @@
+params 190,664 (nonzero 7,901)
+Counter({np.str_('genuine'): 983, np.str_('other'): 276, np.str_('phantom'): 31})
+phantom recall 31/31 = 1.000
+genuine false-flag 3/983 = 0.0031
+precision 0.912
+other-hallucination cites flagged 2/276
+
+-- missed phantoms
+
+-- false flags
+  0.971 '479 F.3d 875 (03-1202),' -> '479 f.3d 875 (03-1202)' [volume_year=3.00]
+  0.953 '652 A.2d 634, 636 (D.C. Cir. 1995)' -> '652 a.2d 634, 636 (d.c.cir. 1995)' [court_mismatch=1.00]
+  0.953 '2013 US Dist LEXIS 14304' -> '2013 us dist lexis 14304' [volume_missing=1.00]
+
+-- genuine but amber (0.1-0.5): 14
+  0.119 '55 ind.app. 455, 464 (1914)' [unknown_reporter=1.00]
+  0.119 '120 s ct 1878' [unknown_reporter=1.00]
+  0.119 '957 f.2d. 655' [unknown_reporter=1.00]
+  0.119 '14 how. 156, 175, 14' [unknown_reporter=1.00]
+  0.119 '70 o.s. 6' [unknown_reporter=1.00]
+  0.119 '2011 ok civ app 68' [unknown_reporter=1.00]
+  0.119 '70 o.s. 5' [unknown_reporter=1.00]
+  0.119 '1995 ok 138' [unknown_reporter=1.00]
+  0.119 '189 ok 49' [unknown_reporter=1.00]
+  0.119 '151 f.2d. 240' [unknown_reporter=1.00]
+  0.119 '433 f.3d. 867' [unknown_reporter=1.00]
+  0.119 '31 op.o.l.c. 73' [unknown_reporter=1.00]
+  0.119 '70 o.s. 5' [unknown_reporter=1.00]
+  0.119 '1995 ok 138' [unknown_reporter=1.00]

results/eval_v1.5.txt

@@ -0,0 +1,17 @@
+params 397,250 (nonzero 13,871)
+Counter({np.str_('genuine'): 983, np.str_('other'): 276, np.str_('phantom'): 31})
+phantom recall 31/31 = 1.000
+genuine false-flag 1/983 = 0.0010
+precision 0.969
+other-hallucination cites flagged 2/276
+cites where >1 reporter class fired: 0 []
+
+-- missed phantoms
+
+-- false flags
+  0.953 '652 A.2d 634, 636 (D.C. Cir. 1995)' -> '652 a.2d 634, 636 (d.c.cir. 1995)' [court_mismatch=1.00]
+
+-- genuine but amber (0.1-0.5): 3
+  0.119 '957 f.2d. 655' [unknown_reporter=1.00]
+  0.119 '151 f.2d. 240' [unknown_reporter=1.00]
+  0.119 '433 f.3d. 867' [unknown_reporter=1.00]

results/firehose.txt

@@ -0,0 +1,4 @@
+{"n": 3000320, "seconds": 6.9778, "per_sec": 429979, "flagged": 99632, "lanes": {"ane": {"batch": 512, "threads": 2, "cites": 3000320}}}
+{"n": 3006464, "seconds": 2.1772, "per_sec": 1380882, "flagged": 107253, "lanes": {"gpu": {"batch": 8192, "threads": 2, "cites": 3006464}}}
+{"n": 3000320, "seconds": 1.6592, "per_sec": 1808283, "flagged": 105279, "lanes": {"ane": {"batch": 512, "threads": 2, "cites": 714752}, "gpu": {"batch": 8192, "threads": 2, "cites": 2285568}}}
+{"n": 3000320, "seconds": 1.6442, "per_sec": 1824796, "flagged": 105328, "lanes": {"ane": {"batch": 512, "threads": 2, "cites": 698368}, "gpu": {"batch": 8192, "threads": 2, "cites": 2301952}}}

results/train_baseline_v1.1.txt

@@ -0,0 +1,7 @@
+/Users/hanweng/citenet/scripts/train_baseline.py:47: UserWarning: To copy construct from a tensor, it is recommended to use sourceTensor.detach().clone() or sourceTensor.detach().clone().requires_grad_(True), rather than torch.tensor(sourceTensor).
+  pw = torch.tensor((1 - ytr.mean()) / ytr.mean())
+hand-written (0 steps) eval phantoms 31/31  eval false flags 1/983  | brief: series fakes 2/2, other fakes 3/3, real flagged 0/7
+random init, seed 0    eval phantoms 31/31  eval false flags 0/983  | brief: series fakes 1/2, other fakes 0/3, real flagged 0/7
+random init, seed 1    eval phantoms 31/31  eval false flags 0/983  | brief: series fakes 1/2, other fakes 0/3, real flagged 0/7
+random init, seed 2    eval phantoms 31/31  eval false flags 0/983  | brief: series fakes 1/2, other fakes 0/3, real flagged 0/7
+hand init + fine-tune  eval phantoms 30/31  eval false flags 118/983  | brief: series fakes 2/2, other fakes 1/3, real flagged 0/7

scripts/cold_extract.py

@@ -0,0 +1,48 @@
+"""COLD Cases parquet shard -> one plain-text corpus for the live demo.
+
+Writes data/cold/corpus.txt: one decision per record ("case name, court, date"
+header + opinion texts), records separated by blank lines, plus corpus.json.
+"""
+import json, sys, re, html
+import pyarrow.parquet as pq
+
+src, dst = sys.argv[1], sys.argv[2]
+limit = int(sys.argv[3]) if len(sys.argv) > 3 else 10**12
+pf = pq.ParquetFile(src)
+print(pf.schema_arrow)
+n_dec = n_bytes = 0
+courts = {}
+years = []
+tag = re.compile(r"<[^>]+>")
+with open(dst, "w", encoding="utf-8") as out:
+    for rg in range(pf.num_row_groups):
+        t = pf.read_row_group(rg, columns=["case_name", "court_short_name", "date_filed", "opinions"]).to_pylist()
+        for r in t:
+            texts = []
+            for o in r["opinions"] or []:
+                tx = o.get("opinion_text") or ""
+                if "<" in tx and ">" in tx:
+                    tx = html.unescape(tag.sub(" ", tx))
+                tx = re.sub(r"\n{3,}", "\n\n", tx.strip())
+                if tx:
+                    texts.append(tx)
+            if not texts:
+                continue
+            head = f"{r['case_name'] or ''}, {r['court_short_name'] or ''}, {r['date_filed'] or ''}"
+            rec = head + "\n\n" + "\n\n".join(texts) + "\n\n\n"
+            out.write(rec)
+            n_dec += 1; n_bytes += len(rec.encode())
+            courts[r["court_short_name"]] = courts.get(r["court_short_name"], 0) + 1
+            if r["date_filed"]:
+                years.append(int(str(r["date_filed"])[:4]))
+            if n_bytes >= limit:
+                break
+        if n_bytes >= limit:
+            break
+        print(f"row group {rg}: {n_dec:,} decisions, {n_bytes/1e9:.2f} GB", flush=True)
+years.sort()
+meta = dict(source="harvard-lil/cold-cases (CC0), " + src.split("/")[-1], decisions=n_dec, bytes=n_bytes,
+            courts=len(courts), top_courts=sorted(courts.items(), key=lambda kv: -kv[1])[:12],
+            years=[years[0], years[len(years)//2], years[-1]] if years else None)
+json.dump(meta, open(dst.rsplit(".", 1)[0] + ".json", "w"), indent=1)
+print(json.dumps(meta, indent=1))

scripts/convert.py

@@ -0,0 +1,85 @@
+"""Hand-written CiteNet -> Core ML (.mlpackage, fp16), plus parity and placement checks."""
+import json, os, shutil, sys, time
+import numpy as np, torch, coremltools as ct
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from citenet import net as cn, text, spec
+from lepc import load
+
+OUT = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "build")
+# Fixed shapes: with EnumeratedShapes Core ML ran every shape on the CPU. With a
+# fixed batch the planner puts all ops on the ANE from B=16 up; B=1 stays on CPU.
+# b2048 / b8192 are for the GPU, which wants bigger batches.
+BATCHES = [1, 32, 512, 2048, 8192]
+
+model, meta = cn.make()
+tot, nz = cn.param_counts(model)
+paths = {}
+for B in BATCHES:
+    traced = torch.jit.trace(model, torch.zeros(B, 1, 1, spec.SEQ))
+    ml = ct.convert(
+        traced,
+        inputs=[ct.TensorType(name="codes", shape=(B, 1, 1, spec.SEQ), dtype=np.float16)],
+        outputs=[ct.TensorType(name=n, dtype=np.float16) for n in ("p_fake", "evidence", "concepts")],
+        compute_precision=ct.precision.FLOAT16,
+        minimum_deployment_target=ct.target.macOS15,
+    )
+    ml.short_description = "CiteNet: phantom legal-citation detector with hand-written weights (no training)"
+    ml.user_defined_metadata.update({"params": str(tot), "nonzero_params": str(nz), "trained": "false",
+                                     "batch": str(B), "evidence": json.dumps(meta["evidence"])})
+    paths[B] = os.path.join(OUT, f"CiteNet_b{B}.mlpackage")
+    ml.save(paths[B])
+    print("saved", paths[B])
+# lean builds for bulk scanning: no concepts output (only p_fake + evidence leave the accelerator)
+class Lean(torch.nn.Module):
+    def __init__(self, m):
+        super().__init__(); self.m = m
+    def forward(self, x):
+        p, e, _ = self.m(x)
+        return p, e
+for B in (512, 2048, 8192):
+    traced = torch.jit.trace(Lean(model).eval(), torch.zeros(B, 1, 1, spec.SEQ))
+    ml = ct.convert(traced, inputs=[ct.TensorType(name="codes", shape=(B, 1, 1, spec.SEQ), dtype=np.float16)],
+                    outputs=[ct.TensorType(name=n, dtype=np.float16) for n in ("p_fake", "evidence")],
+                    compute_precision=ct.precision.FLOAT16, minimum_deployment_target=ct.target.macOS15)
+    ml.short_description = "CiteNet lean (p_fake + evidence only), hand-written weights"
+    lp = os.path.join(OUT, f"CiteNet_lean_b{B}.mlpackage"); ml.save(lp)
+    dst = os.path.join(OUT, f"CiteNet_lean_b{B}.mlmodelc"); shutil.rmtree(dst, ignore_errors=True)
+    ct.utils.compile_model(lp, dst)
+    print("saved", lp)
+json.dump({k: meta[k] for k in ("features", "concepts", "rules", "evidence", "groups", "anchored", "floating")},
+          open(os.path.join(OUT, "meta.json"), "w"))
+np.savez_compressed(os.path.join(OUT, "weights.npz"), **{k: v for k, v in cn.build()[0].items()})
+
+# ---- parity: torch fp32 vs Core ML fp16 on every train+eval citation
+rows = load("aux_train") + load("eval")
+X = text.encode([r["cite"] for r in rows])
+with torch.no_grad():
+    pt = model(torch.from_numpy(X))[0][:, 0].numpy()
+for B, cu in ((512, "CPU_AND_NE"), (2048, "CPU_AND_GPU")):
+    m = ct.models.MLModel(paths[B], compute_units=getattr(ct.ComputeUnit, cu))
+    outs = []
+    for i in range(0, len(X), B):
+        xb = X[i:i + B]; n = len(xb)
+        pad = np.zeros((B, 1, 1, spec.SEQ), np.float16); pad[:n] = xb
+        outs.append(m.predict({"codes": pad})["p_fake"][:n, 0])
+    pc = np.concatenate(outs).astype(np.float32)
+    flip = np.where((pc >= 0.5) != (pt >= 0.5))[0]
+    print(f"{cu} b{B} vs torch fp32: {len(X)-len(flip)}/{len(X)} labels agree; flips: {[rows[i]['cite'] for i in flip]}")
+
+# ---- placement
+from coremltools.models.compute_plan import MLComputePlan
+for B, p in paths.items():
+    dst = os.path.join(OUT, f"CiteNet_b{B}.mlmodelc")
+    shutil.rmtree(dst, ignore_errors=True)        # compile_model will not overwrite
+    c = ct.utils.compile_model(p, dst)
+    for cu in ("CPU_AND_NE", "CPU_AND_GPU"):
+        plan = MLComputePlan.load_from_path(path=c, compute_units=getattr(ct.ComputeUnit, cu))
+        cnt = {}
+        for fn in plan.model_structure.program.functions.values():
+            for op in fn.block.operations:
+                u = plan.get_compute_device_usage_for_mlprogram_operation(op)
+                if u:
+                    k = type(u.preferred_compute_device).__name__.replace("ML", "").replace("ComputeDevice", "")
+                    cnt[k] = cnt.get(k, 0) + 1
+        print(f"b{B} {cu} placement:", cnt)

scripts/evaluate.py

@@ -0,0 +1,44 @@
+"""Score the hand-written CiteNet at citation level on a LePhantomCite split."""
+import argparse, collections, os, sys
+import numpy as np, torch
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from citenet import net as cn, text
+from lepc import load
+
+ap = argparse.ArgumentParser()
+ap.add_argument("split", default="aux_train", nargs="?")
+ap.add_argument("--show", type=int, default=25)
+a = ap.parse_args()
+
+model, meta = cn.make()
+rows = load(a.split)
+x = torch.from_numpy(text.encode([r["cite"] for r in rows]))
+with torch.no_grad():
+    p, ev, _ = model(x)
+p = p[:, 0].numpy(); ev = ev.numpy()
+lab = np.array([r["label"] for r in rows])
+flag = p >= 0.5
+tot, nz = cn.param_counts(model)
+print(f"params {tot:,} (nonzero {nz:,})")
+print(collections.Counter(lab))
+tp = int((flag & (lab == "phantom")).sum()); fn = int((~flag & (lab == "phantom")).sum())
+fp = int((flag & (lab == "genuine")).sum()); tn = int((~flag & (lab == "genuine")).sum())
+oth = int((flag & (lab == "other")).sum())
+print(f"phantom recall {tp}/{tp+fn} = {tp/max(1,tp+fn):.3f}")
+print(f"genuine false-flag {fp}/{fp+tn} = {fp/max(1,fp+tn):.4f}")
+print(f"precision {tp/max(1,tp+fp):.3f}")
+print(f"other-hallucination cites flagged {oth}/{int((lab=='other').sum())}")
+C = meta["concepts"]
+cls = [i for i, n in enumerate(C) if n.startswith("class:")]
+with torch.no_grad():
+    conc = model(x)[2].numpy()
+multi = np.where(conc[:, cls].sum(1) > 1.5)[0]
+print(f"cites where >1 reporter class fired: {len(multi)}", [rows[i]["cite"] for i in multi[:5]])
+names = meta["evidence"]
+def why(i):
+    return ", ".join(f"{n}={ev[i,j]:.2f}" for j, n in enumerate(names) if ev[i, j] > 0.01)
+print("\n-- missed phantoms"); [print(f"  {p[i]:.3f} {rows[i]['cite']!r} -> {text.normalize(rows[i]['cite'])!r} [{why(i)}]") for i in np.where(~flag & (lab=='phantom'))[0][:a.show]]
+print("\n-- false flags"); [print(f"  {p[i]:.3f} {rows[i]['cite']!r} -> {text.normalize(rows[i]['cite'])!r} [{why(i)}]") for i in np.where(flag & (lab=='genuine'))[0][:a.show]]
+amber = np.where((p > 0.1) & (p < 0.5) & (lab == "genuine"))[0]
+print(f"\n-- genuine but amber (0.1-0.5): {len(amber)}")
+for i in amber[:a.show]: print(f"  {p[i]:.3f} {text.normalize(rows[i]['cite'])!r} [{why(i)}]")

scripts/lepc.py

@@ -0,0 +1,34 @@
+"""Citation-level labels from LePhantomCite (ai-law-society-lab/Legal_Phantom_Citation).
+
+phantom  = citation tagged non_existent_citation
+genuine  = citation with no hallucination tag at all
+other    = tagged case_name_mismatch / wrong_pincite / misquote / content_misrepresentation
+           (needs a case-law lookup; out of scope for a string-only model, reported separately)
+'optional' tags (typos in the source brief) are dropped.
+"""
+import json, os, sys
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from citenet.text import normalize
+
+ROOT = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "data")
+
+
+def load(split):
+    rows = [json.loads(l) for l in open(os.path.join(ROOT, split + ".jsonl"))]
+    out = []
+    for r in rows:
+        tags = r.get("list_hallucination_types") or {}
+        opt = {k for k, v in (r.get("list_hallucinations") or {}).items() if v == "optional"}
+        cites = list(dict.fromkeys(list(r["citations_in_segment"]) + list(tags)))
+        seen = set()
+        for c in cites:
+            key = normalize(c)
+            if key in seen or c in opt:
+                continue
+            seen.add(key)
+            ts = tags.get(c, [])
+            if "optional" in ts:
+                continue
+            label = "phantom" if "non_existent_citation" in ts else ("other" if ts else "genuine")
+            out.append(dict(cite=c, label=label, types=ts, file=r["filename"]))
+    return out

scripts/scan_parity.py

@@ -0,0 +1,29 @@
+"""Check bench/scanparity (native Swift scanner) against citenet.text on a text file."""
+import subprocess, sys, os
+import numpy as np
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from citenet import text, spec
+
+path = sys.argv[1]
+s = open(path, encoding="utf-8", newline="").read()
+found = text.extract(s)
+py_cites = [c for _, _, c in found]
+py_codes = text.encode(py_cites).reshape(len(py_cites), spec.SEQ).astype(np.float16)
+out = subprocess.run([os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "bench", "scanparity"),
+                      path, "/tmp/scanparity_out"], capture_output=True, text=True)
+print(out.stdout.strip(), out.stderr.strip()[:500])
+sw_codes = np.fromfile("/tmp/scanparity_out.f16", dtype=np.float16).reshape(-1, spec.SEQ)
+sw_cites = [l.replace("\\r", "\r").replace("\\n", "\n") for l in open("/tmp/scanparity_out.txt", encoding="utf-8", newline="").read().split("\n")] if len(sw_codes) else []
+print(f"python {len(py_cites):,} citations, swift {len(sw_codes):,}")
+n = min(len(py_cites), len(sw_cites))
+cite_mis = [i for i in range(n) if py_cites[i] != sw_cites[i]]
+print(f"first {n:,}: cite text mismatches {len(cite_mis)}")
+for i in cite_mis[:5]:
+    print("  py:", repr(py_cites[i]), "\n  sw:", repr(sw_cites[i]))
+if not cite_mis and len(py_cites) == len(sw_cites):
+    bad = np.where((py_codes != sw_codes).any(1))[0]
+    print(f"code rows identical: {len(py_cites) - len(bad):,}/{len(py_cites):,}")
+    inv = {v: k for k, v in spec.PUNCT.items()}
+    dec = lambda r: "".join(chr(48 + int(c) - 3) if 3 <= c <= 12 else chr(97 + int(c) - 13) if 13 <= c <= 38 else inv.get(int(c), "?") if c > 2 else "" for c in r)
+    for i in bad[:6]:
+        print("  ", repr(py_cites[i]), "\n     py:", dec(py_codes[i]), "\n     sw:", dec(sw_codes[i]))

scripts/train_baseline.py

@@ -0,0 +1,66 @@
+"""Same CiteNet architecture, trained instead of hand-written.
+
+random  : random init, Adam + class-weighted BCE on aux_train (genuine vs phantom)
+handinit: start from the hand-written weights, same training
+Scored on the LePhantomCite eval split, and on the planted fakes in the demo brief
+(court mismatch / volume-year / state mismatch: kinds the train split's phantoms
+never show, since they are all invented series).
+"""
+import os, sys, copy
+import numpy as np, torch, torch.nn.functional as F
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from citenet import net as cn, text
+from lepc import load
+
+torch.manual_seed(0); np.random.seed(0)
+tr = [r for r in load("aux_train") if r["label"] != "other"]
+ev = load("eval")
+Xtr = torch.from_numpy(text.encode([r["cite"] for r in tr])); ytr = torch.tensor([r["label"] == "phantom" for r in tr], dtype=torch.float32)
+Xev = torch.from_numpy(text.encode([r["cite"] for r in ev])); lev = np.array([r["label"] for r in ev])
+brief = open(os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "demo", "sample_brief.txt")).read()
+bc = [c for _, _, c in text.extract(brief)]
+hand, _ = cn.make()
+with torch.no_grad():
+    bl = (hand(torch.from_numpy(text.encode(bc)))[0][:, 0] >= 0.5).numpy()   # hand-written labels = planted truth here
+Xb = torch.from_numpy(text.encode(bc))
+
+
+def score(m, tag):
+    with torch.no_grad():
+        p = m(Xev)[0][:, 0].numpy(); pb = m(Xb)[0][:, 0].numpy()
+    f = p >= 0.5
+    rec = (f & (lev == "phantom")).sum(), (lev == "phantom").sum()
+    ff = (f & (lev == "genuine")).sum(), (lev == "genuine").sum()
+    fb = pb >= 0.5
+    ood = [c for c, t, y in zip(bc, bl, fb) if t and "th " not in c.split("(")[0]]
+    caught = sum(1 for c, t, y in zip(bc, bl, fb) if t and y and "th " not in c.split("(")[0])
+    series = sum(1 for c, t, y in zip(bc, bl, fb) if t and y and "th " in c.split("(")[0])
+    fpb = sum(1 for t, y in zip(bl, fb) if y and not t)
+    print(f"{tag:22s} eval phantoms {rec[0]}/{rec[1]}  eval false flags {ff[0]}/{ff[1]}  | brief: series fakes {series}/2, "
+          f"other fakes {caught}/{len(ood)}, real flagged {fpb}/{int((~bl).sum())}")
+
+
+def train(m, steps=1500, lr=3e-3):
+    m.train()
+    opt = torch.optim.Adam(m.parameters(), lr=lr)
+    pw = torch.tensor((1 - ytr.mean()) / ytr.mean())
+    for s in range(steps):
+        idx = torch.randint(0, len(Xtr), (256,))
+        p = m(Xtr[idx])[0][:, 0].clamp(1e-6, 1 - 1e-6)
+        logit = torch.log(p) - torch.log1p(-p)
+        loss = F.binary_cross_entropy_with_logits(logit, ytr[idx], pos_weight=pw)
+        opt.zero_grad(); loss.backward(); opt.step()
+    return m.eval()
+
+
+score(hand, "hand-written (0 steps)")
+for seed in (0, 1, 2):
+    torch.manual_seed(seed)
+    rnd = cn.CiteNet(cn.build()[0])
+    for mod in rnd.modules():
+        if isinstance(mod, (torch.nn.Conv2d, torch.nn.Linear)):
+            mod.reset_parameters()
+    score(train(rnd), f"random init, seed {seed}")
+torch.manual_seed(0)
+score(train(copy.deepcopy(hand), lr=1e-4), "hand init + fine-tune")