# Authoritative Overlay Node

Part of the **Audit-grade financial extraction node suite**.

## Overview
The `authoritative_overlay` node is a pipeline filter that cross-checks extracted financial numbers against the live US SEC EDGAR company-concept API for a configured CIK.

Currently supported regulators:
- US SEC (EDGAR)

## Behavior

- **Input**: Pipeline `answers` (or `text` containing a JSON payload).
- **Process**: The node queries `https://data.sec.gov/api/xbrl/companyconcept/CIK{cik}/us-gaap/{concept}.json` and compares the extracted number against measurements that match the requested filing period.
- **Output**:
  - If the extracted number matches an official value **for that period**, the answer is forwarded downstream (once).
  - If there is a mismatch, missing period, failed lookup, or unrecognized regulator, the node **abstains** by dropping the answer and logging a warning.

### Period-scoped matching

A match is **not** "this number appears somewhere in the company's filing history." The answer payload must include at least one of `form`, `fy`, `fp`, `end`, `unit`, or `frame`. All provided filters are applied together. Typical payload:

```json
{
  "concept": "AccountsPayableCurrent",
  "value": "$69,860,000,000",
  "form": "10-K",
  "fy": 2025
}
```

Without a period the node abstains. A value that is correct for a 2010 10-K will not verify a 2025 extraction.

> [!NOTE]
> **Strict Matching**: The node uses exact matching (`math.isclose` with `rel_tol=1e-9`). This ensures that only exact financial figures are passed through. Filings restated to the nearest thousand will not match a value extracted to the unit.

## Configuration

See `services.json` for node configuration schemas.

The live `services.json` test block hits `data.sec.gov` and is excluded from the default `builder nodes:test` run (opt in with `ROCKETRIDE_INCLUDE_SKIP=authoritative_overlay`). Unit tests under `nodes/test/authoritative_overlay/` mock the API and do not require the network.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `authoritative_overlay.cik` | `string` | **Company CIK**<br/>The SEC Central Index Key for the company. | `"320193"` |
| `authoritative_overlay.profile` | `string` | **Profile**<br/>Overlay profile | `"basic"` |
| `authoritative_overlay.regulator_type` | `string` | **Regulator Source**<br/>Which regulator database to cross-check against | `"sec"` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/authoritative_overlay)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->