new-site/api/migrations/054_499a_form_fidelity.sql

-- 054: 499-A form-fidelity columns + FCC reference tables
--
-- Migration 048 added most of Blocks 1/2/6 columns (affiliated_filer_*,
-- trade_names, officer 2+3, jurisdictions_served, first_telecom_service_*,
-- exempt_usf/trs/nanpa/lnp, is_state_local_gov, is_tax_exempt_501c,
-- regulatory_contact_*, itsp_regulatory_fee_email). Migration 038 gave us
-- ceo_name/ceo_title but no CEO address.
--
-- This migration closes the remaining gaps from the April 2026 audit of
-- the 2026 FCC Form 499-A Instructions (pdf at
-- docs/fcc-references/2026-FCC-Form-499A-Form-Instructions.pdf):
--
--  * Officer 1 business address (Lines 219-220 — required same as 2+3)
--  * entity_structure (drives officer count — sole-prop = 1, corp = 3)
--  * exempt_itsp (Line 603 — not in migration 048)
--  * nondisclosure_requested (Line 605)
--  * safe_harbor_election JSONB — per-category-per-quarter election state
--  * fcc_deminimis_factors reference table (Appendix A factor — 0.256 for 2026)
--  * fcc_safe_harbor_percentages reference table (64.9% VoIP / 37.1% cellular / 12.0% paging / 1.0% SMR for 2026)

-- ── Block 2-C: Officer 1 business address (CEO) ─────────────────────────
-- 2026 instructions Lines 219-226 require business address for every officer.
-- Officer 2 + 3 addresses were added in 048; Officer 1 / CEO was omitted.
ALTER TABLE telecom_entities ADD COLUMN IF NOT EXISTS officer_1_street TEXT;
ALTER TABLE telecom_entities ADD COLUMN IF NOT EXISTS officer_1_city   TEXT;
ALTER TABLE telecom_entities ADD COLUMN IF NOT EXISTS officer_1_state  TEXT;
ALTER TABLE telecom_entities ADD COLUMN IF NOT EXISTS officer_1_zip    TEXT;

-- How many officers did the filer claim? Drives REQUIRED_FIELDS conditional
-- for officer 2 + 3 blocks. 1 = sole prop; 2-3 = corp/LLC/partnership.
ALTER TABLE telecom_entities ADD COLUMN IF NOT EXISTS officer_count_claimed SMALLINT
    CHECK (officer_count_claimed IS NULL OR officer_count_claimed BETWEEN 1 AND 3);

-- Entity structure — drives officer requirements + Block 6 cert text.
ALTER TABLE telecom_entities ADD COLUMN IF NOT EXISTS entity_structure TEXT
    CHECK (entity_structure IS NULL OR entity_structure IN (
        'corp','llc','partnership','sole_prop','gov','nonprofit','other'
    ));

-- ── Block 6: ITSP exemption + nondisclosure request ─────────────────────
-- 048 gave us exempt_usf/trs/nanpa/lnp but not ITSP (per-revenue regulatory
-- fee — applies to interstate telecom service providers).
ALTER TABLE telecom_entities ADD COLUMN IF NOT EXISTS exempt_itsp BOOLEAN DEFAULT FALSE;

-- Line 605 — checkbox to request confidential treatment of revenue info.
-- Requires inline officer attestation text (not stored here, collected in Block6CertStep).
ALTER TABLE telecom_entities ADD COLUMN IF NOT EXISTS nondisclosure_requested BOOLEAN DEFAULT FALSE;

-- ── Safe harbor election state ──────────────────────────────────────────
-- Election must be consistent across affiliated filers per quarter per
-- category. Shape:
--   { voip_interconnected: {year:2025, q:"annual", method:"safe_harbor", pct:64.9},
--     wireless:            {year:2025, q:"annual", method:"traffic_study"} }
-- method ∈ {safe_harbor, traffic_study, actual_data}
ALTER TABLE telecom_entities ADD COLUMN IF NOT EXISTS safe_harbor_election JSONB DEFAULT '{}'::jsonb;

-- ── De minimis calculator persistence ───────────────────────────────────
-- Written to the order on /validate + re-computed at filing time.
-- Appendix A worksheet result (11 lines) stored in full for audit.
ALTER TABLE compliance_orders ADD COLUMN IF NOT EXISTS deminimis_worksheet_json JSONB;
ALTER TABLE compliance_orders ADD COLUMN IF NOT EXISTS deminimis_estimated_contrib_cents BIGINT;
ALTER TABLE compliance_orders ADD COLUMN IF NOT EXISTS deminimis_result_is_exempt BOOLEAN;

-- ── Yearly de minimis factor lookup ─────────────────────────────────────
-- 2026 Form 499-A Appendix A Line 10 = 0.256 — applied to the projected
-- interstate+intl contribution base. Filer is exempt if resulting
-- estimated contribution < $10,000. Factor changes annually; parameterize
-- so 2027's release is a one-row insert.
CREATE TABLE IF NOT EXISTS fcc_deminimis_factors (
    form_year        SMALLINT PRIMARY KEY,
    factor           NUMERIC(6,4) NOT NULL,
    threshold_usd    INTEGER NOT NULL DEFAULT 10000,
    source_citation  TEXT,
    created_at       TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

INSERT INTO fcc_deminimis_factors (form_year, factor, source_citation)
VALUES (2026, 0.2560, '2026 Form 499-A Appendix A Line 10')
ON CONFLICT (form_year) DO NOTHING;

-- ── Yearly safe harbor percentage lookup ────────────────────────────────
-- Per 2026 Form 499-A Section IV.C.5.g. Unchanged from prior years but
-- parameterized for future updates. Non-interconnected VoIP intentionally
-- omitted — has no safe harbor; code must refuse election.
CREATE TABLE IF NOT EXISTS fcc_safe_harbor_percentages (
    form_year         SMALLINT NOT NULL,
    line_105_category TEXT NOT NULL,
    interstate_pct    NUMERIC(5,2) NOT NULL,
    source_citation   TEXT,
    PRIMARY KEY (form_year, line_105_category)
);

INSERT INTO fcc_safe_harbor_percentages VALUES
    (2026, 'voip_interconnected', 64.9, '2026 Form 499-A IV.C.5.g'),
    (2026, 'cellular_pcs',        37.1, '2026 Form 499-A IV.C.5.g'),
    (2026, 'paging',              12.0, '2026 Form 499-A IV.C.5.g'),
    (2026, 'smr_dispatch',         1.0, '2026 Form 499-A IV.C.5.g')
ON CONFLICT (form_year, line_105_category) DO NOTHING;