Unified power-user entry point for edgarjure.
Require as: (require '[edgar.api :as e])

Design principles:
- Every function accepts ticker or CIK interchangeably
- Keyword args throughout; no positional form/type args
- Sensible defaults for taxonomy (us-gaap), unit (USD), form (10-K)
- :concept accepts a string or a collection of strings
- Functions that return datasets always return tech.ml.dataset, never seq-of-maps

Financial statement extraction with normalization and standardization.

Four output views for each statement (:view option):
  :as-reported   - raw XBRL observations for the statement's concepts,
                   exactly as filed; no deduplication, no label mapping
  :normalized    - (default) fallback chains map variant tags to canonical
                   labels; restatements deduplicated by most-recent-filed
  :standardized  - :normalized plus derived line items imputed from
                   arithmetic identities (e.g. Gross Profit = Revenue -
                   Cost of Revenue). Derived rows carry :method :derived
                   and :derived-from for auditability.
  :compustat     - :standardized plus line items reclassified to
                   approximate Compustat definitions (D&A out of COGS,
                   R&D folded into XSGA, special items added back to
                   operating income, ...). Reclassified rows carry
                   :method :reclassified, :rule and :derived-from.
                   Rules live in resources/edgar/reclass/ (edgar.reclass);
                   income statement only for now.

Concept fallback chains: each line item is a vector of concept names tried
in order; the first one present in the facts data wins. Chains are loaded
from EDN files under resources/edgar/concepts/ and exposed as public vars,
so power users can inspect them or pass their own via :concepts.

Industry routing: banks (SIC 6000-6199, 6712) and insurers (SIC 6300-6399,
6411) use fundamentally different income statement line items. When no
explicit :industry or :concepts is given, income-statement auto-routes on
the company's SIC code. Pass :industry :standard to force generic chains.

Duration vs instant:
  Income statement + cash flow -> duration observations (row has :start date)
  Balance sheet               -> instant observations  (row has no :start date)

Point-in-time / look-ahead-safe mode:
  Pass :as-of "YYYY-MM-DD" to any public function to restrict to filings
  where :filed <= as-of-date.  Without :as-of the latest restated value is
  returned (always-latest behaviour).

Quarterly and LTM derivation (10-Q only, flow variables only):
  :duration-months - 3/6/9/12 classification of the observation window
  :val-q   - single-quarter value. Derived from actual period dates:
             a ~3-month row is used as-is; a YTD row minus the YTD row one
             quarter shorter (same fiscal-year start) yields the quarter
             ending at the longer row's end. The SEC :fy/:fp fields are
             deliberately NOT used — they describe the filing, not the
             observation, and collide across comparative periods.
  :val-ltm - last-twelve-months: sum of four consecutive derived quarters
             matched on period-end dates (±14 days tolerance for 52/53-week
             fiscal calendars). 10-K annual rows participate in the
             derivation so that Q4 = FY - 9M YTD.

Unmapped-concept logging: every statement call records us-gaap concepts in
the company's facts that no active chain matched. See unmapped-concepts,
clear-unmapped-concepts!, save-unmapped-concepts!.

Central loader for all built-in edgarjure form parsers.

Requiring this namespace registers filing-obj methods for all supported
form types. Individual parsers can also be required directly.

Usage:
  (require '[edgar.forms])          ; loads all built-in parsers
  (edgar.filing/filing-obj filing)  ; dispatches to the appropriate parser

Supported form types after loading:
  "4"       — Form 4: insider trades (edgar.forms.form4)
  "13F-HR"  — Form 13F-HR: institutional holdings (edgar.forms.form13f)
  "13F-HR/A" — Form 13F-HR/A: amended institutional holdings (edgar.forms.form13f)

Form 13F-HR parser — Institutional Investment Manager Holdings Report.
Registers a filing-obj method for form type "13F-HR".

Only handles XML-era filings (post-2013 Q2). Earlier filings use
heterogeneous plain-text infotables and are not supported.

Usage:
  (require '[edgar.forms.form13f])  ; side-effectful load registers the method
  (edgar.filing/filing-obj filing)  ; => {:form "13F-HR" :holdings <dataset> ...}

Form 4 parser — Statement of Changes in Beneficial Ownership.
Registers a filing-obj method for form type "4".

Usage:
  (require '[edgar.forms.form4])   ; side-effectful load registers the method
  (edgar.filing/filing-obj filing) ; => {:form "4" :reporting-owner {...} :transactions [...]}

SEC Financial Statement Data Sets (DERA) access.
https://www.sec.gov/dera/data/financial-statement-data-sets

Quarterly ZIPs containing four tab-delimited tables:
  sub — one row per submission: adsh, cik, name, sic, form, period,
        fy, fp, filed, and filer metadata
  num — one row per numeric fact: adsh, tag, version, ddate, qtrs,
        uom, segments, value
  pre — statement placement: adsh, stmt (BS/IS/CF/EQ/CI), report, line,
        tag — i.e. which statement each tag appeared on and in what order
  tag — tag metadata: version, custom flag, datatype, iord (instant/
        duration), crdr (credit/debit), label, documentation

Why this matters for standardization: unlike the companyfacts API, these
sets include company extension tags and statement placement — the two
ingredients Compustat-style cross-company standardization needs most.
One bulk download covers every filer for a quarter, instead of one HTTP
call per company.

Usage:
  (require '[edgar.fsds :as fsds])
  (def zip (fsds/download-quarter! 2024 1 "/data/fsds"))
  (def sub (fsds/load-table zip :sub))
  (def num (fsds/load-table zip :num))
  (def pre (fsds/load-table zip :pre))

  ;; e.g. income statement placement for one filing:
  ;; (-> pre
  ;;     (ds/filter-column :adsh #(= % "0000320193-24-000006"))
  ;;     (ds/filter-column :stmt #(= % "IS")))

Reclassification rule engine (roadmap 4.1c).

Approximates commercial-database item definitions (currently Compustat)
by reclassifying standardized line items: stripping D&A out of COGS,
folding R&D into SG&A, adding special-item charges back to operating
income, netting excise taxes from revenue, etc.

Rules are data, loaded from EDN under resources/edgar/reclass/ and applied
per [unit start end] period group on top of the :standardized row set.
Reclassified rows are ADDED alongside the original items (never replacing
them) and carry provenance:
  :method       :reclassified
  :rule         the rule :id that produced the row
  :derived-from labels of the operand line items actually used

Rule format:
  {:id      :cogs-ex-da           ; unique keyword
   :target  "COGS (Compustat)"  ; emitted line-item label
   :formula [:- "Cost of Revenue" "D&A"]
   :guards  [[:lt "D&A" "Cost of Revenue"]]
   :compustat "COGS"            ; documentation only
   :notes   "..."}              ; documentation only

Formula operators:
  [:= a]          - copy operand a
  [:+ a b ...]    - sum
  [:- a b ...]    - first minus the rest
  [:neg-sum a ..] - negated sum of the operands present with a non-zero
                    value (nil when none are)
Operands are line-item labels; wrap as [:opt label] to treat a missing
operand as 0 instead of blocking the rule. Targets of earlier rules can be
operands of later ones (applied iteratively, capped at 4 passes).

Guards (all must pass; operands referenced by label):
  [:lt a b]                    - value of a strictly less than value of b
  [:gt a b]                    - value of a strictly greater than value of b
  [:concept-not-in a #{c ...}] - a's winning XBRL concept is not in the set
                                 (rows without a concept, e.g. derived rows,
                                 pass)

Rules are tried in order; for a given :target the first rule whose operands
and guards are satisfied wins (the target is skipped once present).

Malli schemas and validation helpers for the edgarjure public API.

Usage (in edgar.api):
  (schema/validate! ::filings-args {:ticker-or-cik toc :form form ...})

All public validate! calls throw ex-info with :type ::invalid-args on failure.
The error message includes the human-readable Malli explanation.

HTML table extraction from SEC filings.

Extracts <table> elements from filing HTML and converts them to
tech.ml.dataset objects. Handles iXBRL inline-tagged content,
colspan expansion, and mixed numeric/string columns.

Usage:
  (require '[edgar.tables :as tables])
  (tables/extract-tables filing)        ; => seq of datasets
  (tables/extract-tables filing :nth 0) ; => first table as dataset
  (tables/extract-tables filing :min-rows 5) ; => only tables with >=5 data rows

Validation harness — quantify how close edgarjure's statement output is to
a benchmark (Compustat/Capital IQ extract, hand-collected figures, academic
reconciliation datasets).

Usage:
  (require '[edgar.validation :as validation])
  (validation/compare-to-benchmark "AAPL"
    [{:line-item "Revenue"    :end "2023-09-30" :val 383285000000}
     {:line-item "Net Income" :end "2023-09-30" :val 96995000000}])
  ;=> {:match-rate 1.0 :matched [...] :mismatched [] :missing []}

Track :match-rate over time as concept files and identities improve.