@yottagraph-app/data-model-skill 0.0.31 → 0.0.33

package/skill/fdic/schema.yaml

@@ -6,11 +6,15 @@
 # passive — they are created by the atomizer from parsed JSON fields, not
 # by LLM extraction.
 #
-# Two source identifiers are used on records:
+# Three source identifiers are used on records:
 #   - "fdic"          — institution profiles + quarterly financials
-#   - "fdic_failure"  — bank failure and resolution data
+#   - "fdic_failure"  — bank failure and resolution data (from /failures endpoint)
+#   - "fdic_history"  — institution-level structure-change events (mergers,
+#                       consolidations, voluntary closings, name changes,
+#                       regulator changes, failures, etc., from /history endpoint
+#                       filtered to ORG_ROLE_CDE:FI)
 name: "fdic"
-description: "FDIC-insured depository institution profiles, quarterly Call Report financials, and bank failure/resolution data from the FDIC BankFind Suite API"
+description: "FDIC-insured depository institution profiles, quarterly Call Report financials, bank failure/resolution data, and institution-level structure-change events (mergers, consolidations, name/regulator/charter changes, voluntary closings, failures) from the FDIC BankFind Suite API"
 
 extraction:
   flavors: closed
@@ -34,6 +38,14 @@ flavors:
     examples: ["New York City", "San Francisco", "North America", "Bakery Square"]
     passive: true
 
+  - name: "bank_structure_event"
+    description: "An institution-level structure-change transaction recorded by the FDIC against an FDIC-insured (or FDIC-tracked) depository institution. Each row in the FDIC History API at the institution level (ORG_ROLE_CDE='FI') becomes one event entity, covering unassisted mergers, consolidations, absorptions, FDIC-assisted resolutions, voluntary closings, new charters, name changes, regulator and chartering-agency changes, class changes, and trust-power grants. Each event carries explicit relationships to every involved institution (subject, outgoing, surviving, acquiring) so a transaction is queryable as a first-class graph object."
+    display_name: "Bank Structure Event"
+    mergeability: not_mergeable
+    strong_id_properties: ["fdic_transaction_number", "fdic_history_event_id"]
+    examples: ["FDIC TXN 2026008583 — Merger -Without Assistance: Flint Hills Bank → The Bennington State Bank (2026-04-08)"]
+    passive: true
+
 # --- Identity and Registration (source: fdic) ---
 
 properties:
@@ -336,6 +348,100 @@ properties:
     domain_flavors: ["organization"]
     passive: true
 
+  # --- Bank Structure Event Properties (source: fdic_history) ---
+  # From FDIC BankFind Suite History API filtered to ORG_ROLE_CDE:FI.
+  # All elements are passive (atomized from JSON, no LLM extraction).
+
+  - name: "fdic_transaction_number"
+    type: string
+    description: "FDIC transaction number (TRANSNUM) uniquely identifying a transaction-backed structure-change in the FDIC History API; serves as the bank_structure_event entity's strong ID for the ~91% of FI-level events that are transaction-backed. The ~9% of FI-level events without a TRANSNUM (TRANSNUM=0, dominated by new-institution rows, location changes, and cert reassignments) instead carry an fdic_history_event_id strong ID"
+    display_name: "FDIC Transaction Number"
+    mergeability: not_mergeable
+    domain_flavors: ["bank_structure_event"]
+    examples: ["2026008583", "2026007976", "2026002845"]
+    passive: true
+
+  - name: "fdic_history_event_id"
+    type: string
+    description: "Per-row identifier from the ID field of the FDIC History API, used as the bank_structure_event entity's strong ID for the ~16K of ~185K FI-level events that have no TRANSNUM (TRANSNUM=0). The ID is a composite of effective date, CHANGECODE, and an internal identifier (e.g. \"1972-09-28T00:00:00_150_14384__\") and is unique per row. Emitted only when TRANSNUM=0, so the two strong-id properties are mutually exclusive for a given event"
+    display_name: "FDIC History Event ID"
+    mergeability: not_mergeable
+    domain_flavors: ["bank_structure_event"]
+    examples: ["1972-09-28T00:00:00_150_14384__", "1970-03-31T00:00:00_150_13853__"]
+    passive: true
+
+  - name: "event_change_code"
+    type: string
+    description: "FDIC structure-change event code (CHANGECODE) identifying the kind of structure change at the institution level — e.g. 110 (new institution), 211 (failure - whole institution), 221/222/223/224 (unassisted absorption/consolidation/merger/affiliated-pooling), 240 (voluntary closing), 310/320 (FRS membership change), 420/430/440/470 (chartering/class/org-type/regulator change), 510/520 (legal-name/physical-location change), 610 (trust powers granted), 810 (participated in absorption/consolidation/merger), 811 (participated in FDIC-assisted merger)"
+    display_name: "Event Change Code"
+    mergeability: not_mergeable
+    domain_flavors: ["bank_structure_event"]
+    examples: ["223", "211", "510", "240", "110", "810", "440"]
+    passive: true
+
+  - name: "event_change_description"
+    type: string
+    description: "Human-readable description of the FDIC structure-change event code (CHANGECODE_DESC) as published by the FDIC"
+    display_name: "Event Change Description"
+    mergeability: not_mergeable
+    domain_flavors: ["bank_structure_event"]
+    examples: ["Merger -Without Assistance", "Failure - Whole Institution", "Closing - Voluntary", "Change in Legal Name (FO or BR)", "New Institution"]
+    passive: true
+
+  - name: "event_category"
+    type: string
+    description: "Normalized bucket for the FDIC structure-change event, derived from CHANGECODE so consumers can filter without memorizing numeric codes. One of: merger (unassisted absorptions/consolidations/mergers/affiliated-pooling/branch-purchases and the partner-side merger rows: CC 221/222/223/224/225/712/810/811/812); failure (FDIC-assisted resolutions, conservatorships, RTC payoffs, open-bank assistance, and any closure driven by the chartering agency: CC 211/213/215/216/217/230/235/260/350/360/830); voluntary_closing (CC 240); new_institution (newly chartered institutions and admin cert reassignments: CC 110/150); name_change (CC 510); location_change (physical-address moves: CC 520); charter_change (FRS membership changes, insurance-status changes, chartering-agency/class/org-type/primary-regulator changes, trust powers granted, and phantom holding-company reorgs: CC 310/320/340/410/420/430/440/470/610/820); other (any CHANGECODE not in the above buckets, currently only CC 1 History Record Initiation). CHANGECODE definitions: https://banks.data.fdic.gov/docs/history_properties.yaml"
+    display_name: "Event Category"
+    mergeability: not_mergeable
+    domain_flavors: ["bank_structure_event"]
+    examples: ["merger", "failure", "name_change", "location_change", "charter_change", "new_institution", "voluntary_closing", "other"]
+    passive: true
+
+  - name: "is_fdic_assisted"
+    type: string
+    description: "String-encoded boolean (\"true\"/\"false\") indicating whether the FDIC (or its predecessor RTC) provided financial assistance, brokered the resolution, or otherwise stepped in to handle the institution. True for CHANGECODEs 211/213/215/216/217/230/235/260/350/360/811/812/830 (all failure-bucket codes plus the two partner-side rows for FDIC-Assisted Merger and Rtc Assisted Merger); false for all other codes. Orthogonal to event_category: 811/812 are in the merger bucket but are also FDIC-assisted. CHANGECODE definitions: https://banks.data.fdic.gov/docs/history_properties.yaml"
+    display_name: "FDIC-Assisted Resolution"
+    mergeability: not_mergeable
+    domain_flavors: ["bank_structure_event"]
+    examples: ["true", "false"]
+    passive: true
+
+  - name: "event_charter_class"
+    type: string
+    description: "FDIC institution charter class code in effect for the subject institution at the time of the event, sourced from the History API CLASS field. Same code set as the organization-level charter_class property (N/SM/NM/SB/SA/...). Critical for charter/regulator-change events (CC 430 Change in Class, CC 440 Change in Organization Type, CC 470 Change in Primary Regulatory Agency), where this is the class the institution changed TO. CHANGECODE and CLASS definitions: https://banks.data.fdic.gov/docs/history_properties.yaml"
+    display_name: "Event Charter Class"
+    mergeability: not_mergeable
+    domain_flavors: ["bank_structure_event"]
+    examples: ["N", "SM", "NM", "SB", "SA"]
+    passive: true
+
+  - name: "event_effective_date"
+    type: string
+    description: "Date the FDIC structure-change event took legal effect, formatted YYYY-MM-DD; derived from the EFFDATE field of the History API"
+    display_name: "Event Effective Date"
+    mergeability: not_mergeable
+    domain_flavors: ["bank_structure_event"]
+    examples: ["2026-04-08", "2008-12-31", "2004-07-01"]
+    passive: true
+
+  - name: "previous_legal_name"
+    type: string
+    description: "An institution's prior legal name immediately preceding a structure-change event that altered the legal name; derived from the FRM_INSTNAME field of the History API and emitted only when distinct from the current INSTNAME"
+    display_name: "Previous Legal Name"
+    mergeability: not_mergeable
+    domain_flavors: ["bank_structure_event"]
+    examples: ["ASSOCIATED CREDIT UNION", "Wachovia Bank, National Association"]
+    passive: true
+
+  - name: "previous_fdic_certificate_number"
+    type: string
+    description: "An institution's prior FDIC certificate number, derived from the FRM_CERT field of the History API and emitted only when present and distinct from the current CERT. The canonical case is CHANGECODE 150 (Cert Changed from Old Cert by Administrative Order). The same prior CERT is also added as an additional fdic_certificate_number strong-id alias on the subject_institution organization entity, so entity resolution merges the bank's old-cert and new-cert identities. CHANGECODE definitions: https://banks.data.fdic.gov/docs/history_properties.yaml"
+    display_name: "Previous FDIC Certificate Number"
+    mergeability: not_mergeable
+    domain_flavors: ["bank_structure_event"]
+    examples: ["90054", "90465", "90337"]
+    passive: true
+
 relationships:
   - name: "is_located_at"
     description: "An entity is located at, operates in, resides in, is headquartered in, was born in, visits, or died in a location"
@@ -347,10 +453,46 @@ relationships:
     passive: true
 
   - name: "acquired_by"
-    description: "Links a failed institution to the acquiring institution that purchased its assets and/or assumed its deposits during FDIC resolution; derived from the BIDNAME field in the Failures API"
+    description: "Links a failed institution to the acquiring institution that purchased its assets and/or assumed its deposits during FDIC resolution; derived from the BIDNAME field in the Failures API. Coexists with the more general succeeded_by relationship and with bank_structure_event entities; the parallel representations are intentional"
     display_name: "Acquired By"
     mergeability: not_mergeable
     domain_flavors: ["organization"]
     target_flavors: ["organization"]
     examples: ["First Independence Bank acquired Metropolitan Capital B&T"]
     passive: true
+
+  - name: "succeeded_by"
+    description: "Links a depository institution that ceased to exist (via merger, consolidation, absorption, or FDIC resolution) directly to its successor institution. Sourced from the FDIC History API (fdic_history) whenever a 2-party event has both an outgoing party (OUT_CERT) and a distinct surviving/acquiring party (ACQ_CERT, falling back to SUR_CERT) AND the outgoing party actually disappeared (ORG_STAT_FLG=N). Provides a direct bank-to-bank lineage edge alongside the richer bank_structure_event entity model; both representations are emitted intentionally so consumers can pick whichever shape fits their query."
+    display_name: "Succeeded By"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    target_flavors: ["organization"]
+    examples: ["Wachovia Bank of Delaware succeeded by Wells Fargo Bank, National Association", "Silicon Valley Bank succeeded by Deposit Insurance National Bank of Santa Clara"]
+    passive: true
+
+  - name: "subject_institution"
+    description: "Links a bank structure-change event to the FDIC-tracked institution this History API row is filed against (the row's primary CERT). For mergers/failures this is the disappearing party (also surfaced as outgoing_institution); for name changes, regulator changes, charter changes, voluntary closings, and new institutions, this is the affected institution itself."
+    display_name: "Subject Institution"
+    mergeability: not_mergeable
+    domain_flavors: ["bank_structure_event"]
+    target_flavors: ["organization"]
+    examples: ["FDIC TXN 2026007976 → Openland Credit Union (subject of legal-name change)"]
+    passive: true
+
+  - name: "outgoing_institution"
+    description: "Links a bank structure-change event to the FDIC-tracked institution that ceased to exist as a result of the event; derived from the OUT_CERT and OUT_INSTNAME fields of the History API and emitted only when populated"
+    display_name: "Outgoing Institution"
+    mergeability: not_mergeable
+    domain_flavors: ["bank_structure_event"]
+    target_flavors: ["organization"]
+    examples: ["FDIC TXN 2026008583 → Flint Hills Bank (disappearing party of unassisted merger)"]
+    passive: true
+
+  - name: "successor_institution"
+    description: "Links a bank structure-change event to the FDIC-tracked institution that took the outgoing party's deposits and/or assets following a merger, consolidation, absorption, or assisted resolution. Sourced preferentially from the ACQ_CERT/ACQ_INSTNAME fields of the History API (the conventional acquirer), falling back to SUR_CERT/SUR_INSTNAME (the legal-survivor designation) when only the survivor side is populated. Collapses the FDIC's split ACQ/SUR signals because empirically they agree on the CERT in 99.99% of 2-party events (only 3 of 23,114 disagree across 90 years of FI-level history, and those 3 are administrative same-name cert renumberings rather than genuinely distinct parties). Consumers that need the raw distinction can re-derive it from the source by inspecting the original History API row's ACQ_CERT vs SUR_CERT."
+    display_name: "Successor Institution"
+    mergeability: not_mergeable
+    domain_flavors: ["bank_structure_event"]
+    target_flavors: ["organization"]
+    examples: ["FDIC TXN 2026008583 → The Bennington State Bank (unassisted-merger acquirer)", "FDIC TXN 2026002845 → First Independence Bank (acquirer of Metropolitan Capital B&T after FDIC-assisted resolution)"]
+    passive: true