@yottagraph-app/data-model-skill 0.0.22 → 0.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottagraph-app/data-model-skill",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "description": "Data model skill documentation for AI agents - entity types, properties, and schemas from Lovelace fetch sources",
   "repository": {
     "type": "git",

package/skill/faaregistry/DATA_DICTIONARY.md

@@ -0,0 +1,381 @@
+# Data Dictionary: FAA Aircraft Registry
+
+## Source Overview
+
+The FAA Releasable Aircraft Database is published by the Federal Aviation Administration, Civil Aviation Registry, Aircraft Registration Branch (AFS-750). It contains registration records for all U.S. civil aircraft, plus reference tables, deregistered aircraft, dealer certificates, document indices, and reserved N-numbers.
+
+The database is distributed as a single ZIP archive (~60MB) refreshed daily at 11:30 PM Central Time. It contains 7 comma-delimited `.txt` files. Field definitions are documented in [ardata.pdf](https://registry.faa.gov/database/ardata.pdf).
+
+Download URL: `https://registry.faa.gov/database/ReleasableAircraft.zip`
+
+The implementation joins ACFTREF.txt and ENGINE.txt as in-memory lookup tables into MASTER.txt rows, producing denormalized aircraft registration records. DEREG.txt uses a similar structure and is processed alongside MASTER.txt. DEALER.txt, DOCINDEX.txt, and RESERVED.txt are processed as separate entity types.
+
+| File | Record Count (approx) | Entity Type |
+|------|----------------------|-------------|
+| MASTER.txt | ~300,000+ | `aircraft` |
+| ACFTREF.txt | ~few thousand | Lookup table (joined into `aircraft`) |
+| ENGINE.txt | ~few thousand | Lookup table (joined into `aircraft`) |
+| DEREG.txt | ~300,000+ | `aircraft` (deregistered) |
+| DEALER.txt | ~few thousand | `organization` (aircraft dealers) |
+| DOCINDEX.txt | ~millions | `document` (aircraft document index) |
+| RESERVED.txt | ~tens of thousands | `aircraft` (reserved N-numbers) |
+
+| Pipeline | `Record.Source` |
+|----------|----------------|
+| All files | `faaregistry` |
+
+---
+
+## Entity Types
+
+### `aircraft`
+
+A U.S. civil aircraft identified by its FAA registration N-number. Includes active registrations (MASTER.txt), deregistered aircraft (DEREG.txt), and reserved N-numbers (RESERVED.txt).
+
+- Primary key: N-Number (e.g., `"12345"` for N12345)
+- Entity resolver: named entity. Strong ID = `n_number`. Mode S hex code as secondary identifier. Disambiguation via manufacturer, model, serial number, registrant name.
+
+### `organization`
+
+An aircraft dealer or manufacturer holding an FAA Dealer's Aircraft Registration Certificate.
+
+- Primary key: Certificate number (e.g., `"24-0001"`)
+- Entity resolver: named entity. Strong ID = `dealer_certificate_number`. Disambiguation via name, address.
+
+### `document`
+
+A document recorded with the FAA Aircraft Registry, indexed by collateral identification (usually the N-number).
+
+- Primary key: Document ID (12-character unique identifier)
+- Entity resolver: named entity. Strong ID = `faa_document_id`. Not mergeable.
+
+### `location`
+
+A geographic location derived from the registrant's address (city + state).
+
+- Primary key: city + state combination
+- Entity resolver: named entity. Disambiguation via city name, state code.
+
+---
+
+## Properties
+
+### Aircraft Properties (from MASTER.txt + ACFTREF.txt + ENGINE.txt joins)
+
+#### Identity and Registration
+
+* `n_number`
+  * Definition: FAA registration number assigned to the aircraft (without the "N" prefix).
+  * Examples: `"12345"`, `"789AB"`, `"5NJ"`
+  * Derivation: `N-NUMBER` field from MASTER.txt, positions 1-5.
+
+* `serial_number`
+  * Definition: Complete aircraft serial number assigned by the manufacturer.
+  * Examples: `"28-7990244"`, `"172S10245"`
+  * Derivation: `SERIAL NUMBER` field from MASTER.txt, positions 7-36.
+
+* `mode_s_code_hex`
+  * Definition: Aircraft Mode S transponder code in hexadecimal format (ICAO 24-bit address).
+  * Examples: `"A12345"`, `"ABCDEF"`
+  * Derivation: `MODE S CODE HEX` field from MASTER.txt, positions 602-611.
+  * Note: This corresponds to the `icaoAddress` property in the KG aircraft flavor schema.
+
+* `mode_s_code`
+  * Definition: Aircraft Mode S transponder code in octal format.
+  * Examples: `"50712345"`
+  * Derivation: `MODE S CODE` field from MASTER.txt, positions 257-264.
+
+* `unique_id`
+  * Definition: FAA-assigned unique identification number for the registration record.
+  * Examples: `"01234567"`
+  * Derivation: `UNIQUE ID` field from MASTER.txt, positions 541-548.
+
+#### Aircraft Details (joined from ACFTREF.txt)
+
+* `manufacturer_name`
+  * Definition: Name of the aircraft manufacturer.
+  * Examples: `"CESSNA"`, `"BOEING"`, `"PIPER"`, `"BEECH"`
+  * Derivation: Joined from ACFTREF.txt `AIRCRAFT MANUFACTURER NAME` (positions 9-38) via `AIRCRAFT MFR MODEL CODE` foreign key.
+
+* `model_name`
+  * Definition: Aircraft model and series name.
+  * Examples: `"172S"`, `"737-800"`, `"PA-28-181"`
+  * Derivation: Joined from ACFTREF.txt `MODEL NAME` (positions 40-59) via `AIRCRAFT MFR MODEL CODE` foreign key.
+
+* `aircraft_type`
+  * Definition: Type of aircraft.
+  * Examples: `"Fixed wing single engine"`, `"Rotorcraft"`, `"Balloon"`
+  * Derivation: `TYPE AIRCRAFT` field from MASTER.txt (position 249), decoded: 1=Glider, 2=Balloon, 3=Blimp/Dirigible, 4=Fixed wing single engine, 5=Fixed wing multi engine, 6=Rotorcraft, 7=Weight-shift-control, 8=Powered Parachute, 9=Gyroplane, H=Hybrid Lift, O=Other.
+
+* `engine_type`
+  * Definition: Type of engine installed.
+  * Examples: `"Reciprocating"`, `"Turbo-fan"`, `"Electric"`
+  * Derivation: `TYPE ENGINE` field from MASTER.txt (positions 251-252), decoded: 0=None, 1=Reciprocating, 2=Turbo-prop, 3=Turbo-shaft, 4=Turbo-jet, 5=Turbo-fan, 6=Ramjet, 7=2 Cycle, 8=4 Cycle, 9=Unknown, 10=Electric, 11=Rotary.
+
+* `year_manufactured`
+  * Definition: Year the aircraft was manufactured.
+  * Examples: `"1978"`, `"2023"`
+  * Derivation: `YEAR MFR` field from MASTER.txt, positions 52-55.
+
+* `number_of_engines`
+  * Definition: Number of engines on the aircraft.
+  * Examples: `"1"`, `"2"`, `"4"`
+  * Derivation: Joined from ACFTREF.txt `NUMBER OF ENGINES` (positions 70-71).
+
+* `number_of_seats`
+  * Definition: Maximum number of seats in the aircraft.
+  * Examples: `"4"`, `"189"`, `"12"`
+  * Derivation: Joined from ACFTREF.txt `NUMBER OF SEATS` (positions 73-75).
+
+* `aircraft_weight_class`
+  * Definition: Maximum gross takeoff weight class.
+  * Examples: `"Up to 12,499 lbs"`, `"12,500 - 19,999 lbs"`, `"20,000 and over"`, `"UAV up to 55 lbs"`
+  * Derivation: Joined from ACFTREF.txt `AIRCRAFT WEIGHT` (positions 77-83), decoded: 1=Up to 12,499, 2=12,500-19,999, 3=20,000 and over, 4=UAV up to 55.
+
+* `cruising_speed`
+  * Definition: Average cruising speed in miles per hour.
+  * Examples: `"124"`, `"530"`
+  * Derivation: Joined from ACFTREF.txt `AIRCRAFT CRUISING SPEED` (positions 85-88).
+  * Note: Not present on all records.
+
+* `aircraft_category`
+  * Definition: Land/sea/amphibian classification.
+  * Examples: `"Land"`, `"Sea"`, `"Amphibian"`
+  * Derivation: Joined from ACFTREF.txt `AIRCRAFT CATEGORY CODE` (position 66), decoded: 1=Land, 2=Sea, 3=Amphibian.
+
+* `builder_certification`
+  * Definition: Builder certification classification.
+  * Examples: `"Type Certificated"`, `"Not Type Certificated"`, `"Light Sport"`
+  * Derivation: Joined from ACFTREF.txt `BUILDER CERTIFICATION CODE` (position 68), decoded: 0=Type Certificated, 1=Not Type Certificated, 2=Light Sport.
+
+* `type_certificate_data_sheet`
+  * Definition: FAA Type Certificate Data Sheet reference.
+  * Derivation: Joined from ACFTREF.txt `TC DATA SHEET` (positions 90-105).
+
+* `type_certificate_holder`
+  * Definition: Name of the Type Certificate holder.
+  * Derivation: Joined from ACFTREF.txt `TC DATA HOLDER` (positions 107-157).
+
+#### Engine Details (joined from ENGINE.txt)
+
+* `engine_manufacturer`
+  * Definition: Name of the engine manufacturer.
+  * Examples: `"LYCOMING"`, `"CONT MOTOR"`, `"P&W"`
+  * Derivation: Joined from ENGINE.txt `ENGINE MANUFACTURER NAME` (positions 7-16) via `ENGINE MFR MODEL CODE` foreign key.
+
+* `engine_model`
+  * Definition: Engine model name.
+  * Examples: `"O-320-D2J"`, `"IO-540"`
+  * Derivation: Joined from ENGINE.txt `ENGINE MODEL NAME` (positions 18-30).
+
+* `engine_horsepower`
+  * Definition: Engine horsepower (for reciprocating, turbo-prop, turbo-shaft, 2-cycle, 4-cycle engines). Unit: HP.
+  * Examples: `"180"`, `"310"`
+  * Derivation: Joined from ENGINE.txt `ENGINE HORSEPOWER` (positions 35-39).
+  * Note: Only populated for engine types 1, 2, 3, 7, 8.
+
+* `engine_thrust`
+  * Definition: Engine thrust (for turbo-jet, turbo-fan, ramjet engines). Unit: pounds of thrust.
+  * Examples: `"27300"`, `"56000"`
+  * Derivation: Joined from ENGINE.txt `POUNDS OF THRUST` (positions 41-46).
+  * Note: Only populated for engine types 4, 5, 6.
+
+#### Registration Status
+
+* `registration_status`
+  * Definition: Current status of the aircraft registration.
+  * Examples: `"Valid Registration"`, `"Registration Expired"`, `"Sale Reported"`, `"Administratively Canceled"`
+  * Derivation: `STATUS CODE` field from MASTER.txt (positions 254-255), decoded to human-readable text. Codes include V=Valid, R=Pending, E=Revoked by enforcement, M=Manufacturer, etc.
+
+* `registrant_type`
+  * Definition: Type of entity that owns the aircraft.
+  * Examples: `"Individual"`, `"Corporation"`, `"LLC"`, `"Government"`
+  * Derivation: `TYPE REGISTRANT` field from MASTER.txt (position 57), decoded: 1=Individual, 2=Partnership, 3=Corporation, 4=Co-Owned, 5=Government, 7=LLC, 8=Non Citizen Corporation, 9=Non Citizen Co-Owned.
+
+* `fractional_ownership`
+  * Definition: Whether the registration has fractional ownership.
+  * Examples: `"true"`, `"false"`
+  * Derivation: `FRACTIONAL OWNERSHIP` field from MASTER.txt (position 266), `Y` = true, blank = false.
+
+#### Certification
+
+* `airworthiness_class`
+  * Definition: Airworthiness certificate classification.
+  * Examples: `"Standard"`, `"Experimental"`, `"Restricted"`, `"Light Sport"`
+  * Derivation: `CERTIFICATION A - AIRWORTHINESS CLASSIFICATION CODE` from MASTER.txt (position 238), decoded: 1=Standard, 2=Limited, 3=Restricted, 4=Experimental, 5=Provisional, 6=Multiple, 7=Primary, 8=Special Flight Permit, 9=Light Sport.
+
+* `approved_operations`
+  * Definition: Approved operations for the airworthiness certificate.
+  * Examples: `"Normal"`, `"Utility"`, `"Agriculture and Pest Control"`, `"Amateur Built"`
+  * Derivation: `CERTIFICATION B - APPROVED OPERATION CODES` from MASTER.txt (positions 239-247), decoded based on airworthiness class.
+
+#### Registrant Information
+
+* `registrant_name`
+  * Definition: Name of the registered owner as it appears on the Application for Registration.
+  * Examples: `"SMITH JOHN"`, `"DELTA AIR LINES INC"`, `"UNITED STATES GOVERNMENT"`
+  * Derivation: `REGISTRANT'S NAME` field from MASTER.txt, positions 59-108.
+
+* `registrant_address`
+  * Definition: Formatted street address of the registrant.
+  * Derivation: Concatenation of `STREET1` (positions 110-142) and `STREET2` (positions 144-176) from MASTER.txt.
+
+* `registrant_city`
+  * Definition: City of the registrant.
+  * Examples: `"ATLANTA"`, `"WICHITA"`, `"SEATTLE"`
+  * Derivation: `REGISTRANT'S CITY` field from MASTER.txt, positions 178-195.
+
+* `registrant_state`
+  * Definition: Two-letter state code of the registrant.
+  * Examples: `"GA"`, `"KS"`, `"WA"`
+  * Derivation: `REGISTRANT'S STATE` field from MASTER.txt, positions 197-198.
+
+* `registrant_zip_code`
+  * Definition: Postal ZIP code of the registrant.
+  * Examples: `"30320"`, `"67201-1234"`
+  * Derivation: `REGISTRANT'S ZIP CODE` field from MASTER.txt, positions 200-209.
+
+* `registrant_region`
+  * Definition: FAA region of the registrant.
+  * Examples: `"Eastern"`, `"Western-Pacific"`, `"Great Lakes"`
+  * Derivation: `REGISTRANT'S REGION` field from MASTER.txt (position 211), decoded: 1=Eastern, 2=Southwestern, 3=Central, 4=Western-Pacific, 5=Alaskan, 7=Southern, 8=European, C=Great Lakes, E=New England, S=Northwest Mountain.
+
+#### Dates
+
+* `last_activity_date`
+  * Definition: Date of last registration activity.
+  * Examples: `"2024/03/15"`
+  * Derivation: `LAST ACTIVITY DATE` from MASTER.txt (positions 220-227), format YYYY/MM/DD.
+
+* `certificate_issue_date`
+  * Definition: Date the registration certificate was issued.
+  * Examples: `"2023/06/01"`
+  * Derivation: `CERTIFICATE ISSUE DATE` from MASTER.txt (positions 229-236), format YYYY/MM/DD.
+
+* `airworthiness_date`
+  * Definition: Date of airworthiness certification.
+  * Examples: `"2001/09/14"`
+  * Derivation: `AIRWORTHINESS DATE` from MASTER.txt (positions 268-275).
+
+* `expiration_date`
+  * Definition: Certificate of Registration expiration date.
+  * Examples: `"2027/03/31"`
+  * Derivation: `EXPIRATION DATE` from MASTER.txt (positions 532-539), format YYYY/MM/DD.
+
+#### Co-Owners
+
+* `other_owner_name`
+  * Definition: Co-owner or partnership name (up to 5 additional names).
+  * Derivation: `OTHER NAME 1` through `OTHER NAME 5` from MASTER.txt (positions 277-530).
+  * Note: Stored as multiple atoms when multiple co-owners exist.
+
+#### Kit Aircraft
+
+* `kit_manufacturer`
+  * Definition: Kit manufacturer name (for kit-built aircraft).
+  * Derivation: `KIT MFR` from MASTER.txt (positions 550-579).
+
+* `kit_model`
+  * Definition: Kit model name.
+  * Derivation: `KIT MODEL` from MASTER.txt (positions 581-600).
+
+### Aircraft Properties (from DEREG.txt -- additional fields)
+
+Deregistered aircraft share all properties above where available, plus:
+
+* `cancel_date`
+  * Definition: Date the registration was canceled.
+  * Examples: `"2023/01/15"`
+  * Derivation: `CANCEL DATE` from DEREG.txt (positions 240-247).
+
+* `export_country`
+  * Definition: Country the aircraft was exported to upon deregistration.
+  * Examples: `"CANADA"`, `"BRAZIL"`
+  * Derivation: `EXPORT COUNTRY` from DEREG.txt (positions 260-277).
+
+### Organization Properties (from DEALER.txt)
+
+#### Identity
+
+* `dealer_certificate_number`
+  * Definition: FAA dealer certificate number.
+  * Examples: `"24-0001"`, `"23-1234"`
+  * Derivation: `CERTIFICATE NUMBER` from DEALER.txt (positions 1-7), format YY-NNNN.
+
+* `dealer_ownership_type`
+  * Definition: Ownership type of the dealer.
+  * Examples: `"Individual"`, `"Corporation"`, `"LLC"`
+  * Derivation: `OWNERSHIP` from DEALER.txt (position 9), decoded: 1=Individual, 2=Partnership, 3=Corporation, 4=Co-Ownership, 7=LLC, 8=Non Citizen Corporation.
+
+* `dealer_certificate_issue_date`
+  * Definition: Date the dealer certificate was issued.
+  * Derivation: `CERTIFICATE ISSUE DATE` from DEALER.txt (positions 11-18), format YYYYMMDD.
+
+* `dealer_expiration_date`
+  * Definition: Dealer certificate expiration date.
+  * Derivation: `EXPIRATION DATE` from DEALER.txt (positions 20-27), format YYYYMMDD.
+
+* `dealer_expired`
+  * Definition: Whether the dealer certificate has expired.
+  * Examples: `"true"`, `"false"`
+  * Derivation: `EXPIRATION FLAG` from DEALER.txt (position 29), `*` = true.
+
+#### Address
+
+* `dealer_address`
+  * Definition: Mailing address of the dealer.
+  * Derivation: Concatenation of DEALER.txt address fields (STREET1, STREET2, CITY, STATE, ZIP CODE).
+
+### Document Properties (from DOCINDEX.txt)
+
+* `faa_document_id`
+  * Definition: Unique document identifier assigned by the FAA.
+  * Examples: `"000123456789"`
+  * Derivation: `DOCUMENT ID` from DOCINDEX.txt (positions 92-103).
+
+* `collateral_type`
+  * Definition: Type of collateral the document pertains to.
+  * Examples: `"Aircraft"`, `"Engine"`, `"Propeller"`, `"Spare Parts"`
+  * Derivation: `TYPE COLLATERAL` from DOCINDEX.txt (position 1), decoded: 1=Aircraft, 2=Engine, 3=Propeller, 4=Spare Parts, 5=Document, 9=Unidentified.
+
+* `collateral_identifier`
+  * Definition: Collateral identification -- typically an N-number for aircraft, or make/model/serial for engines and propellers.
+  * Derivation: `COLLATERAL` from DOCINDEX.txt (positions 3-39).
+
+* `document_receipt_date`
+  * Definition: Date the document was filed for recordation with the Aircraft Registry.
+  * Derivation: `DOCUMENT RECEIPT DATE` from DOCINDEX.txt (positions 105-112), format YYYYMMDD.
+
+* `document_type`
+  * Definition: Type of document being indexed.
+  * Examples: `"BOS"` (Evidence of Ownership), `"S/A"` (Security Conveyance/Lien), `"REL"` (Lien Release)
+  * Derivation: `DOC TYPE` from DOCINDEX.txt (positions 165-167).
+
+### Aircraft Properties (from RESERVED.txt)
+
+Reserved N-numbers produce minimal `aircraft` records:
+
+* `reservation_type`
+  * Definition: Type of N-number reservation.
+  * Examples: `"Fee paid"`, `"Reserved to manufacturer"`, `"N-Number change in process"`
+  * Derivation: `TYPE RESERVATION` from RESERVED.txt (positions 168-169), decoded.
+
+* `reservation_date`
+  * Definition: Date the N-number was reserved.
+  * Derivation: `RESERVE DATE` from RESERVED.txt (positions 159-166), format YYYYMMDD.
+
+* `reservation_expiration_date`
+  * Definition: Date the reservation expiration notice was sent.
+  * Derivation: `EXPIRATION NOTICE DATE` from RESERVED.txt (positions 171-178), format YYYYMMDD.
+
+---
+
+## Entity Relationships
+
+```
+aircraft      ──[is_located_at]──────→ location        (registrant city/state)
+aircraft      ──[has_document]───────→ document         (via N-number in DOCINDEX collateral)
+organization  ──[is_located_at]──────→ location         (dealer address)
+```
+
+---

package/skill/faaregistry/schema.yaml

@@ -0,0 +1,386 @@
+# Dataset schema for FAA Releasable Aircraft Database.
+#
+# Source: https://www.faa.gov/licenses_certificates/aircraft_certification/aircraft_registry/releasable_aircraft_download
+# Updated daily at 11:30 PM CT.
+#
+# This schema describes U.S. civil aircraft registrations from the FAA
+# Aircraft Registry, including MASTER.txt records joined with ENGINE.txt
+# reference data for engine manufacturer, model, and performance details.
+name: "faaregistry"
+description: "FAA aircraft registration data including N-number identity, aircraft and engine details, registration status, certification, and registrant information"
+
+extraction:
+  flavors: closed
+  properties: closed
+  relationships: closed
+  attributes: closed
+  events: closed
+
+flavors:
+  - name: "aircraft"
+    description: "An aircraft such as a plane, helicopter, glider, or unmanned aerial vehicle"
+    display_name: "Aircraft"
+    mergeability: not_mergeable
+    strong_id_properties: ["aircraft_id"]
+    passive: true
+
+  - name: "organization"
+    description: "A particular business, institution, or organization such as a corporation, university, government agency, or non-profit"
+    display_name: "Organization"
+    mergeability: not_mergeable
+    passive: true
+
+  - name: "person"
+    description: "A named individual such as a business owner, executive, or public figure"
+    display_name: "Person"
+    mergeability: not_mergeable
+    passive: true
+
+  - name: "location"
+    description: "A specific named geographic location such as a city, country, region, or landmark"
+    display_name: "Location"
+    mergeability: not_mergeable
+    examples: ["WICHITA, KS", "SEATTLE, WA", "ATLANTA, GA"]
+    passive: true
+
+properties:
+  # Identity and Registration
+  - name: "aircraft_id"
+    type: string
+    description: "Composite aircraft identifier combining manufacturer name and serial number (format: MANUFACTURER:SERIAL)"
+    display_name: "Aircraft ID"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["CESSNA:172S10245", "BOEING:28-7990244"]
+    passive: true
+
+  - name: "n_number"
+    type: string
+    description: "FAA registration N-number uniquely identifying a U.S. civil aircraft"
+    display_name: "N-Number"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["12345", "789AB"]
+    passive: true
+
+  - name: "serial_number"
+    type: string
+    description: "Complete aircraft serial number assigned by the manufacturer"
+    display_name: "Serial Number"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["28-7990244", "172S10245"]
+    passive: true
+
+  - name: "mode_s_code_hex"
+    type: string
+    description: "Aircraft Mode S transponder code in hexadecimal format (ICAO 24-bit address)"
+    display_name: "Mode S Code (Hex)"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["A12345", "ABCDEF"]
+    passive: true
+
+  - name: "mode_s_code"
+    type: string
+    description: "Aircraft Mode S transponder code in octal format"
+    display_name: "Mode S Code"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    passive: true
+
+  - name: "unique_id"
+    type: string
+    description: "FAA-assigned unique identification number for the registration record"
+    display_name: "Unique ID"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    passive: true
+
+  # Aircraft Details (joined from ACFTREF.txt)
+  - name: "manufacturer_name"
+    type: string
+    description: "Name of the aircraft manufacturer, joined from the FAA aircraft reference table"
+    display_name: "Manufacturer Name"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["CESSNA", "BOEING", "PIPER", "BEECH"]
+    passive: true
+
+  - name: "model_name"
+    type: string
+    description: "Aircraft model and series name, joined from the FAA aircraft reference table"
+    display_name: "Model Name"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["172S", "737-800", "PA-28-181"]
+    passive: true
+
+  - name: "number_of_engines"
+    type: string
+    description: "Number of engines on the aircraft, from the FAA aircraft reference table"
+    display_name: "Number of Engines"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["1", "2", "4"]
+    passive: true
+
+  - name: "number_of_seats"
+    type: string
+    description: "Maximum number of seats in the aircraft, from the FAA aircraft reference table"
+    display_name: "Number of Seats"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["4", "189", "12"]
+    passive: true
+
+  - name: "aircraft_weight_class"
+    type: string
+    description: "Maximum gross takeoff weight classification of the aircraft"
+    display_name: "Aircraft Weight Class"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["Up to 12,499 lbs", "12,500 - 19,999 lbs", "20,000 and over"]
+    passive: true
+
+  - name: "cruising_speed"
+    type: string
+    description: "Average cruising speed of the aircraft in miles per hour, from the FAA aircraft reference table"
+    display_name: "Cruising Speed"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["124", "530"]
+    passive: true
+
+  - name: "aircraft_category"
+    type: string
+    description: "Land, sea, or amphibian classification of the aircraft"
+    display_name: "Aircraft Category"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["Land", "Sea", "Amphibian"]
+    passive: true
+
+  - name: "builder_certification"
+    type: string
+    description: "Builder certification classification indicating whether the aircraft is type certificated"
+    display_name: "Builder Certification"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["Type Certificated", "Not Type Certificated", "Light Sport"]
+    passive: true
+
+  - name: "type_certificate_data_sheet"
+    type: string
+    description: "FAA Type Certificate Data Sheet reference number"
+    display_name: "TC Data Sheet"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    passive: true
+
+  - name: "type_certificate_holder"
+    type: string
+    description: "Name of the Type Certificate holder for this aircraft model"
+    display_name: "TC Data Holder"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    passive: true
+
+  - name: "aircraft_type"
+    type: string
+    description: "Type of aircraft such as fixed wing, rotorcraft, glider, or balloon"
+    display_name: "Aircraft Type"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["Fixed wing single engine", "Rotorcraft", "Balloon"]
+    passive: true
+
+  - name: "engine_type"
+    type: string
+    description: "Type of engine installed on the aircraft"
+    display_name: "Engine Type"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["Reciprocating", "Turbo-fan", "Electric"]
+    passive: true
+
+  - name: "year_manufactured"
+    type: string
+    description: "Year the aircraft was manufactured"
+    display_name: "Year Manufactured"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["1978", "2023"]
+    passive: true
+
+  # Joined Engine Details (from ENGINE.txt)
+  - name: "engine_manufacturer"
+    type: string
+    description: "Name of the engine manufacturer, joined from the FAA engine reference table"
+    display_name: "Engine Manufacturer"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["LYCOMING", "CONT MOTOR", "P&W"]
+    passive: true
+
+  - name: "engine_model"
+    type: string
+    description: "Engine model name, joined from the FAA engine reference table"
+    display_name: "Engine Model"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["O-320-D2J", "IO-540"]
+    passive: true
+
+  - name: "engine_horsepower"
+    type: string
+    description: "Engine horsepower for reciprocating and turboprop engines, from the FAA engine reference table"
+    display_name: "Engine Horsepower"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["180", "310"]
+    passive: true
+
+  - name: "engine_thrust"
+    type: string
+    description: "Engine thrust in pounds for turbojet and turbofan engines, from the FAA engine reference table"
+    display_name: "Engine Thrust"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["27300", "56000"]
+    passive: true
+
+  # Registration Status
+  - name: "aircraft_registration_status"
+    type: string
+    description: "Current FAA registration status of the aircraft"
+    display_name: "Registration Status"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["Valid Registration", "Registration Expired", "Sale reported"]
+    passive: true
+
+  - name: "registrant_type"
+    type: string
+    description: "Type of entity that owns the aircraft"
+    display_name: "Registrant Type"
+    mergeability: not_mergeable
+    domain_flavors: ["person", "organization"]
+    examples: ["Individual", "Corporation", "LLC", "Government"]
+    passive: true
+
+  - name: "fractional_ownership"
+    type: string
+    description: "Whether the aircraft registration has fractional ownership"
+    display_name: "Fractional Ownership"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["true", "false"]
+    passive: true
+
+  # Certification
+  - name: "airworthiness_class"
+    type: string
+    description: "FAA airworthiness certificate classification"
+    display_name: "Airworthiness Class"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["Standard", "Experimental", "Restricted", "Light Sport"]
+    passive: true
+
+  # Registrant address (on person/organization entities)
+  - name: "address"
+    type: string
+    description: "Physical street address of the entity"
+    display_name: "Address"
+    mergeability: not_mergeable
+    domain_flavors: ["person", "organization"]
+    examples: ["1030 DELTA BLVD, ATLANTA, GA 30354"]
+    passive: true
+
+  # Dates
+  - name: "last_activity_date"
+    type: string
+    description: "Date of last registration activity"
+    display_name: "Last Activity Date"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    passive: true
+
+  - name: "certificate_issue_date"
+    type: string
+    description: "Date the registration certificate was issued"
+    display_name: "Certificate Issue Date"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    passive: true
+
+  - name: "airworthiness_date"
+    type: string
+    description: "Date of airworthiness certification"
+    display_name: "Airworthiness Date"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    passive: true
+
+  - name: "expiration_date"
+    type: string
+    description: "Certificate of Registration expiration date"
+    display_name: "Expiration Date"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    passive: true
+
+  # DEREG.txt-specific
+  - name: "cancel_date"
+    type: string
+    description: "Date the aircraft registration was canceled"
+    display_name: "Cancel Date"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    passive: true
+
+  - name: "export_country"
+    type: string
+    description: "Country the aircraft was exported to upon deregistration"
+    display_name: "Export Country"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["AUSTRALIA", "CANADA", "BRAZIL"]
+    passive: true
+
+  # Kit Aircraft
+  - name: "kit_manufacturer"
+    type: string
+    description: "Kit manufacturer name for kit-built aircraft"
+    display_name: "Kit Manufacturer"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    passive: true
+
+  - name: "kit_model"
+    type: string
+    description: "Kit model name for kit-built aircraft"
+    display_name: "Kit Model"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    passive: true
+
+relationships:
+  - name: "owns_aircraft"
+    description: "A person or organization owns (is the registered owner of) an aircraft"
+    display_name: "Owns Aircraft"
+    mergeability: not_mergeable
+    domain_flavors: ["person", "organization"]
+    target_flavors: ["aircraft"]
+    examples: ["DELTA AIR LINES INC owns aircraft N12345"]
+    passive: true
+
+  - 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"
+    display_name: "Located At"
+    mergeability: not_mergeable
+    domain_flavors: ["person", "organization"]
+    target_flavors: ["location"]
+    examples: ["DELTA AIR LINES INC is located at ATLANTA, GA"]
+    passive: true

package/skill/lda/DATA_DICTIONARY.md

@@ -0,0 +1,101 @@
+# Data Dictionary: LDA (Lobbying Disclosure Act)
+
+Last updated: 2026-05-04
+
+## Source Overview
+
+Lobbying Disclosure Act filings (registrations, quarterly activity, etc.) from the **unified LDA.gov REST API**. The streamer polls `GET /api/v1/filings/`, stores raw JSON pages, and emits v2 `FetchMessage` records.
+
+| Item | Value |
+|------|--------|
+| Pipeline / stream | Configured in `streams.yaml` (see deployment) |
+| `Record.Source` | `lda` |
+
+Anonymous access is rate-limited; optional API token improves throughput.
+
+---
+
+## Entity Types
+
+### `lda_filing`
+
+One disclosure identified by API `filing_uuid`.
+
+- **Subject name:** `filing_uuid` (stable, unique per disclosure).
+- **Strong id:** `lda_filing_uuid` on the filing subject.
+- **Resolver:** `NOT_MERGEABLE` passive filing entity.
+- **Timestamp:** Parsed from `dt_posted` only (no wall-clock fallback). If `dt_posted` is missing or invalid, the filing is not atomized.
+
+### `organization`
+
+Either the **registrant** (lobbying firm) or **client** on a filing.
+
+- **Subject name:** API `name` (legal / display name).
+- **Strong ids:** `lda_registrant_id` (registrant rows) or `lda_client_internal_id` (client rows).
+- **Role:** Property `lda_party_role` = `registrant` or `client` on the organization **record** (not on the filing).
+- **Resolver:** Named-entity info is `MERGEABLE` (resolver / recordeval ER search) while retaining LDA **strong ids**; flavor-level resolver info remains `NOT_MERGEABLE` per passive schema.
+- **Snippets:** Formatted **address** only when present (no LDA filing UUID prefix).
+
+### `location`
+
+Geographic label derived from registrant or client address fields for `is_located_at` edges.
+
+- **Name:** Typically `City, State` or `City, State, Country`; when city is absent, `State, Country` or state-only per atomizer rules.
+- **Resolver:** `MERGEABLE` named entity (no strong id), for soft clustering with other sources.
+
+---
+
+## Properties
+
+### Filing
+
+| Property | Description |
+|----------|-------------|
+| `lda_filing_uuid` | API `filing_uuid`. |
+| `lda_filing_type` | Machine code (`filing_type`), e.g. `RR`, `Q1`. |
+| `lda_filing_type_display` | Human label (`filing_type_display`). |
+| `lda_filing_year` | Reporting year (float in schema). |
+| `lda_filing_period_display` | Period label, e.g. quarter. |
+| `lda_income` | Income string when present. |
+| `lda_expenses` | Expenses string when present. |
+| `lda_dt_posted` | Raw ISO `dt_posted` from API. |
+| `lda_filing_document_url` | Public document URL. |
+| `lda_posted_by_name` | Poster name when present. |
+| `lda_lobbying_causes` | Repeated **once per** `lobbying_activities[]` row (`CODE (Display)`). Same pattern as patent **`cpc_code`**: narrative text is quad attribute **`lda_lobbying_cause_description`** on that atom (API `description` field). **Only on filing**; omitted if activities array is empty. |
+
+### Organization
+
+| Property | Description |
+|----------|-------------|
+| `lda_party_role` | `registrant` or `client`. |
+| `lda_registrant_id` | Registrant API id as string. |
+| `lda_client_internal_id` | Client row id (`client.id`) as string. |
+| `address` | Single-line formatted address (street/city/state/zip + country). |
+
+---
+
+## Entity Relationships
+
+```
+lda_filing  ──[lda_registrant]──→  organization (registrant)
+lda_filing  ──[lda_client]──────→  organization (client)
+
+organization  ──[is_located_at]──→  location
+```
+
+- **`lda_registrant` / `lda_client`:** Target atoms on the **`lda_filing`** record point at the same organization identities emitted as separate **organization** records for that page (strong ids + properties).
+- **`is_located_at`:** On each **organization** record when the atomizer can derive a location name from city/state/country rules.
+
+---
+
+## Records Per Filing
+
+For a typical filing with registrant and client, atomization yields **up to three** records: one filing, one registrant organization, one client organization. Either org may be omitted if required API fields are missing.
+
+---
+
+## Citations
+
+Primary citation text is the filing `url` when present; otherwise a synthetic label referencing `filing_uuid`.
+
+---

package/skill/lda/schema.yaml

@@ -0,0 +1,209 @@
+# Dataset schema for U.S. Lobbying Disclosure Act (LDA) filings from the
+# Congress/Senate unified REST API (https://lda.gov/api/).
+#
+# Atomizer output uses Record.Source "lda". Filings are passive filing entities
+# keyed by lda_filing_uuid; registrant and client are organization entities linked
+# from the filing via lda_registrant / lda_client relationships.
+name: "lda"
+description: "Lobbying Disclosure Act LD-1/LD-2 filings (registrations and quarterly activity) from the LDA.gov REST API"
+
+extraction:
+  flavors: closed
+  properties: closed
+  relationships: closed
+  attributes: closed
+  events: closed
+
+flavors:
+  - name: "lda_filing"
+    description: "A lobbying disclosure (registration or quarterly activity) identified by filing_uuid"
+    display_name: "LDA filing"
+    mergeability: not_mergeable
+    strong_id_properties: ["lda_filing_uuid"]
+    passive: true
+
+  - name: "organization"
+    description: "A particular business, institution, or organization such as a corporation, university, government agency, or non-profit"
+    display_name: "Organization"
+    mergeability: not_mergeable
+    strong_id_properties: ["lda_registrant_id", "lda_client_internal_id"]
+    passive: true
+
+  - name: "location"
+    description: "A specific named geographic location such as a city, country, region, or landmark"
+    display_name: "Location"
+    mergeability: not_mergeable
+    examples: ["Washington, DC, US", "Arlington, VA, US"]
+    passive: true
+
+properties:
+  - name: "lda_filing_uuid"
+    type: string
+    description: "Stable UUID of the filing in the LDA REST API"
+    display_name: "LDA Filing UUID"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    passive: true
+
+  - name: "lda_filing_type"
+    type: string
+    description: "Machine filing type code (e.g. RR, Q1) from the API filing_type field; human label is attribute lda_filing_type_display when present"
+    display_name: "LDA Filing Type Code"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    passive: true
+
+  - name: "lda_filing_year"
+    type: float
+    description: "Reporting year associated with the filing"
+    display_name: "LDA Filing Year"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    passive: true
+
+  - name: "lda_filing_period"
+    type: string
+    description: "Reporting period code from filing_period (string or number in JSON); human label is attribute lda_filing_period_display when present"
+    display_name: "LDA Filing Period Code"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    passive: true
+
+  - name: "lda_income"
+    type: string
+    description: "Income amount reported on the filing when present (API decimal as string)"
+    display_name: "LDA Reported Income"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    passive: true
+
+  - name: "lda_expenses"
+    type: string
+    description: "Expenses amount reported on the filing when present (API decimal as string)"
+    display_name: "LDA Reported Expenses"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    passive: true
+
+  - name: "lda_dt_posted"
+    type: string
+    description: "Date and time the filing was posted (dt_posted), ISO-8601 string from the API"
+    display_name: "LDA Date Posted"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    passive: true
+
+  - name: "lda_filing_document_url"
+    type: string
+    description: "Public URL of the filing document (HTML/PDF) from filing_document_url"
+    display_name: "LDA Filing Document URL"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    passive: true
+
+  - name: "lda_posted_by_name"
+    type: string
+    description: "Name of the individual who posted the filing (posted_by_name)"
+    display_name: "LDA Posted By"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    passive: true
+
+  - name: "lda_lobbying_causes"
+    type: string
+    description: >-
+      One atom per lobbying_activities row: "CODE (Display)" from general_issue_code and
+      general_issue_code_display. Narrative text is attribute lda_lobbying_cause_description on the
+      same atom when present (same pattern as patent cpc_code + cpc_description).
+    display_name: "LDA Lobbying Causes"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    examples:
+      - "BUD (Budget/Appropriations)"
+      - "HCR (Health Issues)"
+    passive: true
+
+  - name: "lda_party_role"
+    type: string
+    description: "Whether this organization row is the lobbying registrant or the client on the linked LDA filing"
+    display_name: "LDA Party Role"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["registrant", "client"]
+    passive: true
+
+  - name: "lda_registrant_id"
+    type: string
+    description: "Stable LDA API registrant id (registrant.id) as a string, for entity resolution"
+    display_name: "LDA Registrant ID"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    passive: true
+
+  - name: "lda_client_internal_id"
+    type: string
+    description: "Stable LDA API internal client row id (client.id) as a string, for entity resolution"
+    display_name: "LDA Client Internal ID"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    passive: true
+
+  - name: "address"
+    type: string
+    description: "Physical street address of the entity"
+    display_name: "Address"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    passive: true
+
+relationships:
+  - name: "lda_registrant"
+    description: "The lobbying registrant firm that filed this LDA disclosure"
+    display_name: "LDA Registrant"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    target_flavors: ["organization"]
+    passive: true
+
+  - name: "lda_client"
+    description: "The client organization on whose behalf lobbying is reported for this LDA filing"
+    display_name: "LDA Client"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    target_flavors: ["organization"]
+    passive: true
+
+  - 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"
+    display_name: "Located At"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    target_flavors: ["location"]
+    passive: true
+
+attributes:
+  - property: "lda_filing_period"
+    name: "lda_filing_period_display"
+    type: string
+    description: "Human-readable reporting period label from filing_period_display on the same atom as the period code"
+    display_name: "LDA Filing Period"
+    mergeability: not_mergeable
+
+  - property: "lda_filing_type"
+    name: "lda_filing_type_display"
+    type: string
+    description: "Human-readable filing type label from filing_type_display on the same atom as the type code"
+    display_name: "LDA Filing Type"
+    mergeability: not_mergeable
+
+# Narrative for one lobbying issue row. Stored as a quad attribute on each lda_lobbying_causes atom.
+  - property: "lda_lobbying_causes"
+    name: "lda_lobbying_cause_description"
+    type: string
+    description: >-
+      lobbying_activities[].description for that row (optional trailing posted timestamp stripped).
+      Omitted as an attribute when the description is empty.
+    display_name: "LDA Lobbying Cause Description"
+    mergeability: not_mergeable
+
+events: []

package/skill/sanctions/schema.yaml

@@ -51,7 +51,7 @@ flavors:
     passive: true
 
   - name: "aircraft"
-    description: "An airplane identified in sanctions designations"
+    description: "An aircraft such as a plane, helicopter, glider, or unmanned aerial vehicle"
     display_name: "Aircraft"
     mergeability: not_mergeable
     strong_id_properties: ["sanctions_id"]