@yottagraph-app/data-model-skill 0.0.17 → 0.0.19

package/package.json

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

package/skill/dotcensus/DATA_DICTIONARY.md

@@ -0,0 +1,157 @@
+# Data Dictionary: DOT Census
+
+## Source Overview
+
+The FMCSA Company Census File is a daily snapshot of all motor carriers, brokers, shippers, and hazmat carriers registered with the Federal Motor Carrier Safety Administration (FMCSA), part of the U.S. Department of Transportation.
+
+- **Publisher:** FMCSA / U.S. Department of Transportation
+- **URL:** https://data.transportation.gov/Trucking-and-Motorcoaches/Company-Census-File/az4n-8mr2
+- **Format:** CSV (~500K+ rows)
+- **Cadence:** Updated daily from a 24-hour-old FMCSA database snapshot
+- **Source name:** `dotcensus`
+
+Each row represents one registered entity identified by a unique USDOT number. The file contains identity, physical location, fleet composition, carrier operation type, and safety ratings.
+
+**Limitations:** The census reflects registration data, not real-time operational status. Fleet sizes and driver counts are self-reported by carriers during MCS-150 filings and may be stale. Safety ratings are assigned only after compliance reviews and are absent for most carriers.
+
+---
+
+## Entity Types
+
+### `organization`
+
+A motor carrier, broker, shipper, or other entity registered with FMCSA.
+
+- Primary key: `usdot_number` (USDOT Number, unique per registrant)
+- Entity resolver: named entity, MERGEABLE. Strong ID = `usdot_number`. Disambiguation snippet includes the physical address when available.
+- Name: uses `DBA_NAME` when it differs from `LEGAL_NAME`; otherwise uses `LEGAL_NAME`.
+
+### `legal_entity`
+
+The legal owner of a carrier when `LEGAL_NAME` differs from `DBA_NAME`. Represents the person or organization that legally owns the business operating under the DBA name.
+
+- Primary key: none (resolved by name)
+- Entity resolver: named entity, MERGEABLE. Disambiguation snippet includes the entity name.
+- Only produced when `DBA_NAME` is present and differs from `LEGAL_NAME`.
+
+### `location`
+
+The physical location (city + state) of a registered carrier.
+
+- Primary key: none (resolved by name)
+- Entity resolver: named entity, MERGEABLE. Disambiguation snippet includes the formatted location name.
+- Name format: `"{city}, {state}"` or `"{city}, {state}, {country}"` when country is present.
+
+---
+
+## Properties
+
+### Organization Properties
+
+#### Identity and Registration
+
+* `usdot_number`
+  * Definition: USDOT number assigned by FMCSA, unique per registered entity.
+  * Examples: `"12345"`, `"99999"`
+  * Derivation: `DOT_NUMBER` column. Emitted as both a strong ID for entity resolution and as a property atom on every record.
+
+* `address`
+  * Definition: Physical street address of the carrier.
+  * Examples: `"21154 HWY EAST, SILOAM SPRINGS, AR 72761"`, `"100 Main St, Dallas, TX 75201"`
+  * Derivation: Concatenation of `PHY_STREET`, `PHY_CITY`, `PHY_STATE`, and `PHY_ZIP` columns.
+
+* `dot_phone_number`
+  * Definition: Primary phone number on file with FMCSA.
+  * Examples: `"5551234567"`
+  * Derivation: `PHONE` column.
+
+* `dot_business_org_type`
+  * Definition: Business organization type of the registrant.
+  * Examples: `"Individual"`, `"Partnership"`, `"Corporation"`
+  * Derivation: `BUSINESS_ORG_ID` column decoded from numeric codes (1=Individual, 2=Partnership, 3=Corporation).
+
+* `dot_entity_type`
+  * Definition: FMCSA entity type indicating the registrant's role in freight transportation.
+  * Examples: `"Carrier"`, `"Carrier; Broker"`, `"Carrier; Shipper"`
+  * Derivation: `CARSHIP` column. Semicolon-delimited code list decoded from single-letter codes (C=Carrier, B=Broker, S=Shipper, T=Cargo Tank, R=Registrant).
+
+* `dot_operating_authority`
+  * Definition: Operating authority classification describing the carrier's authorization type.
+  * Examples: `"AUTHORIZED FOR HIRE"`, `"PRIVATE PROPERTY"`, `"EXEMPT FOR HIRE"`
+  * Derivation: `CLASSDEF` column, passed through as-is.
+
+#### Carrier Status and Operations
+
+* `dot_carrier_status`
+  * Definition: FMCSA carrier registration status.
+  * Examples: `"A (Active)"`, `"I (Inactive)"`, `"N (Not Authorized)"`
+  * Derivation: `STATUS_CODE` column decoded from single-letter codes.
+
+* `dot_carrier_operation_type`
+  * Definition: Type of carrier operation based on registration.
+  * Examples: `"A (Interstate)"`, `"B (Intrastate Hazmat)"`, `"C (Intrastate Non-Hazmat)"`
+  * Derivation: `CARRIER_OPERATION` column decoded from single-letter codes.
+  * Note: The B/C distinction reflects the carrier's registration type, not actual hazmat activity. A carrier registered as C (non-hazmat) can still transport hazmat (see `dot_hazmat_indicator`).
+
+* `dot_hazmat_indicator`
+  * Definition: Whether the carrier transports hazardous materials.
+  * Examples: `1.0` (yes), `0.0` (no)
+  * Derivation: `HM_Ind` column. `"Y"` → 1.0, `"N"` → 0.0. Omitted when blank.
+
+#### Fleet Composition
+
+* `dot_total_drivers`
+  * Definition: Total number of drivers reported by the carrier.
+  * Examples: `10.0`, `250.0`
+  * Derivation: `TOTAL_DRIVERS` column, parsed as float. Omitted when zero or blank.
+
+* `dot_total_power_units`
+  * Definition: Total number of power units (trucks, tractors) operated by the carrier.
+  * Examples: `5.0`, `1200.0`
+  * Derivation: `POWER_UNITS` column, parsed as float. Omitted when zero or blank.
+
+* `dot_total_bus_units`
+  * Definition: Total number of bus units operated by the carrier.
+  * Examples: `2.0`, `50.0`
+  * Derivation: `BUS_UNITS` column, parsed as float. Omitted when zero or blank.
+
+* `dot_fleet_size_category`
+  * Definition: Fleet size category assigned by FMCSA based on total power units.
+  * Examples: `"A (1-6 power units)"`, `"D (20-100 power units)"`, `"F (1000+ power units)"`
+  * Derivation: `FLEETSIZE` column decoded from single-letter codes. Omitted when `"0"` (none reported).
+
+#### Safety
+
+* `dot_safety_rating`
+  * Definition: FMCSA safety rating assigned during a compliance review.
+  * Examples: `"Satisfactory"`, `"Conditional"`, `"Unsatisfactory"`
+  * Derivation: `SAFETY_RATING` column decoded from single-letter codes (S, C, U).
+  * Note: Most carriers have no safety rating — it is only assigned after a compliance review.
+
+* `dot_safety_rating_date`
+  * Definition: Date the safety rating was assigned.
+  * Examples: `"2024-01-01"`
+  * Derivation: `SAFETY_RATING_DATE` column parsed from `YYYYMMDD` format, output as `YYYY-MM-DD`.
+
+#### Filing Dates
+
+* `dot_last_mcs150_filing_date`
+  * Definition: Date the carrier last filed or updated their MCS-150 Motor Carrier Identification Report.
+  * Examples: `"2024-01-01"`
+  * Derivation: `MCS150_DATE` column parsed from `YYYYMMDD HHMM` format, output as `YYYY-MM-DD`.
+
+### Timestamp Derivation
+
+Record timestamps are derived in priority order: `ADD_DATE` (carrier registration date), then `MCS150_DATE` (last MCS-150 filing). Rows where neither date parses successfully are dropped.
+
+---
+
+## Entity Relationships Summary
+
+```
+legal_entity  ──[doing_business_as]──→ organization
+organization  ──[is_located_at]──────→ location
+```
+
+- `doing_business_as`: Links the legal owner (`LEGAL_NAME`) to the business operating name (`DBA_NAME`). Only produced when the two names differ.
+- `is_located_at`: Links the carrier to its physical location. Only produced when both `PHY_CITY` and `PHY_STATE` are present.

package/skill/dotcensus/schema.yaml

@@ -0,0 +1,196 @@
+# Dataset schema for FMCSA Company Census File (DOT Motor Carrier Census).
+#
+# Source: https://data.transportation.gov/Trucking-and-Motorcoaches/Company-Census-File/az4n-8mr2
+# Updated daily by FMCSA from a 24-hour-old database snapshot.
+#
+# This schema describes motor carrier entities registered with the Federal
+# Motor Carrier Safety Administration, including identity, physical location,
+# fleet composition, and safety ratings.
+name: "dotcensus"
+description: "FMCSA motor carrier company census data including registration, fleet size, carrier operations, and safety ratings from the DOT Company Census File"
+
+extraction:
+  flavors: closed
+  properties: closed
+  relationships: closed
+  attributes: closed
+  events: closed
+
+flavors:
+  - 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: ["usdot_number"]
+    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: ["New York City", "San Francisco", "North America", "Bakery Square"]
+    passive: true
+
+properties:
+  - name: "usdot_number"
+    type: string
+    description: "USDOT number assigned by FMCSA, uniquely identifying a registered motor carrier, broker, or shipper"
+    display_name: "USDOT Number"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["12345", "99999"]
+    passive: true
+
+  - name: "address"
+    type: string
+    description: "Physical street address of the entity"
+    display_name: "Address"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["21154 HWY EAST, SILOAM SPRINGS, AR 72761"]
+    passive: true
+
+  - name: "dot_carrier_status"
+    type: string
+    description: "FMCSA carrier registration status"
+    display_name: "Carrier Status"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["A (Active)", "I (Inactive)", "N (Not Authorized)"]
+    passive: true
+
+  - name: "dot_phone_number"
+    type: string
+    description: "Primary phone number of the carrier"
+    display_name: "Phone Number"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["5551234567"]
+    passive: true
+
+  - name: "dot_carrier_operation_type"
+    type: string
+    description: "Type of carrier operation"
+    display_name: "Carrier Operation Type"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["A (Interstate)", "B (Intrastate Hazmat)", "C (Intrastate Non-Hazmat)"]
+    passive: true
+
+  - name: "dot_safety_rating"
+    type: string
+    description: "FMCSA safety rating assigned during compliance review"
+    display_name: "Safety Rating"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["Satisfactory", "Conditional", "Unsatisfactory"]
+    passive: true
+
+  - name: "dot_safety_rating_date"
+    type: string
+    description: "Date the safety rating was assigned, derived from the SAFETY_RATING_DATE field"
+    display_name: "Safety Rating Date"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    passive: true
+
+  - name: "dot_last_mcs150_filing_date"
+    type: string
+    description: "Date the carrier last filed or updated their MCS-150 Motor Carrier Identification Report with FMCSA"
+    display_name: "Last MCS-150 Filing Date"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    passive: true
+
+  - name: "dot_hazmat_indicator"
+    type: float
+    description: "Whether the carrier transports hazardous materials (1.0 = yes, 0.0 = no), derived from the HM_Ind field"
+    display_name: "Hazmat Indicator"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    passive: true
+
+  - name: "dot_total_drivers"
+    type: float
+    description: "Total number of drivers reported by the carrier"
+    display_name: "Total Drivers"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    passive: true
+
+  - name: "dot_total_power_units"
+    type: float
+    description: "Total number of power units (trucks, tractors) operated by the carrier"
+    display_name: "Total Power Units"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    passive: true
+
+  - name: "dot_total_bus_units"
+    type: float
+    description: "Total number of bus units operated by the carrier"
+    display_name: "Total Bus Units"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    passive: true
+
+  - name: "dot_fleet_size_category"
+    type: string
+    description: "Fleet size category assigned by FMCSA based on the number of power units"
+    display_name: "Fleet Size Category"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["A (1-6 power units)", "D (20-100 power units)", "F (1000+ power units)"]
+    passive: true
+
+  - name: "dot_business_org_type"
+    type: string
+    description: "Business organization type of the carrier"
+    display_name: "Business Organization Type"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["Individual", "Partnership", "Corporation"]
+    passive: true
+
+  - name: "dot_entity_type"
+    type: string
+    description: "FMCSA entity type indicating whether the entity operates as a carrier, broker, shipper, or combination"
+    display_name: "Entity Type"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["Carrier", "Carrier; Broker", "Carrier; Shipper"]
+    passive: true
+
+  - name: "dot_operating_authority"
+    type: string
+    description: "Operating authority classification describing the carrier's authorization type"
+    display_name: "Operating Authority"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["AUTHORIZED FOR HIRE", "PRIVATE PROPERTY", "EXEMPT FOR HIRE"]
+    passive: true
+
+relationships:
+  - name: "doing_business_as"
+    description: "A legal entity is doing business as (DBA) an organization"
+    display_name: "Doing Business As"
+    mergeability: not_mergeable
+    domain_flavors: ["person", "organization"]
+    target_flavors: ["organization"]
+    examples: ["LUIS GALVAN doing business as G & G TRANSPORTATION CO"]
+    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"]
+    examples: ["DAYSPRING CARDS INC is located at SILOAM SPRINGS, AR"]
+    passive: true

package/skill/edgar/schema.yaml

@@ -149,6 +149,14 @@ flavors:
     strong_id_properties: ["accession_number"]
     passive: true
 
+  - name: "form_d"
+    namespace: "sec"
+    description: "Regulation D offering notice (Form D or D/A) filed with the SEC to claim an exemption from registration for a private placement. Covers VC/PE funds, hedge funds, and operating company raises."
+    display_name: "Form D"
+    mergeability: not_mergeable
+    strong_id_properties: ["accession_number"]
+    passive: true
+
   - name: "valuation_method_change"
     namespace: "sec"
     description: "A material change to fund valuation methodology disclosed under N-CEN Item B.20. Each entity records one valuationMethodsChange record (date, asset type, regulatory basis, free-text explanation) and links to the disclosing N-CEN filing plus any per-series fund(s) affected."
@@ -166,7 +174,7 @@ flavors:
     passive: true
 
   - name: "person"
-    description: "A real person as opposed to a fictional character, such as a CEO, politician, or public figure"
+    description: "A real person as opposed to a fictional character, such as a CEO, politician, or public figure. Also used for individual registered broker-dealer representatives identified by their FINRA CRD number."
     display_name: "Person"
     mergeability: not_mergeable
     # crd_number is FINRA's individual Central Registration Depository
@@ -204,7 +212,7 @@ properties:
     description: "SEC Central Index Key, 10-digit zero-padded"
     display_name: "CIK"
     mergeability: not_mergeable
-    domain_flavors: ["organization", "sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::nport_p", "sec::ncen"]
+    domain_flavors: ["organization", "sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::nport_p", "sec::ncen", "sec::form_d"]
     passive: true
 
   - name: "ticker"
@@ -241,7 +249,7 @@ properties:
 
   - name: "state_of_incorporation"
     type: string
-    description: "Two-letter US state or country code of incorporation"
+    description: "State or country of incorporation or formation. Submission-derived values are two-letter US state / ISO country codes (e.g. DE, KY); Form D reports the same concept as a full uppercase jurisdiction name (e.g. DELAWARE, CAYMAN ISLANDS) and is emitted as-is. Consumers should treat the value as an opaque jurisdiction string and match by case-insensitive equality after normalising whitespace."
     display_name: "State of Incorporation"
     mergeability: not_mergeable
     domain_flavors: ["organization"]
@@ -626,7 +634,7 @@ properties:
     description: "SEC accession number uniquely identifying a filing"
     display_name: "Accession Number"
     mergeability: not_mergeable
-    domain_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::nport_p", "sec::ncen", "sec::filing"]
+    domain_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::nport_p", "sec::ncen", "sec::form_d", "sec::filing"]
     passive: true
 
   - name: "form_type"
@@ -634,7 +642,7 @@ properties:
     description: "Normalized SEC form type (e.g. 10-K, SC 13D, 4)"
     display_name: "Form Type"
     mergeability: not_mergeable
-    domain_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::nport_p", "sec::ncen", "sec::filing"]
+    domain_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::nport_p", "sec::ncen", "sec::form_d", "sec::filing"]
     passive: true
 
   - name: "filing_date"
@@ -642,7 +650,7 @@ properties:
     description: "Date the filing was submitted to the SEC (YYYY-MM-DD)"
     display_name: "Filing Date"
     mergeability: not_mergeable
-    domain_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::nport_p", "sec::ncen", "sec::filing"]
+    domain_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::nport_p", "sec::ncen", "sec::form_d", "sec::filing"]
     passive: true
 
   - name: "report_date"
@@ -650,7 +658,7 @@ properties:
     description: "End date of the primary reporting period (YYYY-MM-DD)"
     display_name: "Report Date"
     mergeability: not_mergeable
-    domain_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::nport_p", "sec::ncen", "sec::filing"]
+    domain_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::nport_p", "sec::ncen", "sec::form_d", "sec::filing"]
     passive: true
 
   # ── XBRL Financial Facts (key concepts) ──
@@ -2098,6 +2106,158 @@ properties:
     domain_flavors: ["financial_instrument"]
     passive: true
 
+  # ── Form D: Issuer Attributes (on organization) ──
+
+  # Form-D-specific issuer attributes are scoped with form_d_ prefixes when
+  # they overlap conceptually with broader properties (industry_group →
+  # form_d_industry_group disambiguates from sic_code and the 'industry'
+  # flavor). Truly Form-D-only attributes (legal_entity_form,
+  # private_fund_type, year_of_inc) keep simple names. Fields that change
+  # over time relative to the filing date (e.g. "incorporated within the
+  # last 5 years") are deliberately not stored: they're derivable from
+  # year_of_inc + filing_date and would otherwise accumulate conflicting
+  # answers across filings.
+
+  - name: "legal_entity_form"
+    type: string
+    description: "Legal entity structure as reported in Form D: e.g. Limited Partnership, Limited Liability Company, Corporation, Business Trust"
+    display_name: "Legal Entity Form"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["Limited Partnership", "Limited Liability Company", "Corporation"]
+    passive: true
+
+  - name: "form_d_industry_group"
+    type: string
+    description: "Form D's coarse industry classification (e.g. Pooled Investment Fund, Technology, Real Estate, Banking). Distinct from the SIC taxonomy carried by sic_code/sic_description and the 'industry' flavor — Form D's enum is much coarser and self-reported by the issuer."
+    display_name: "Form D Industry Group"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["Pooled Investment Fund", "Technology", "Real Estate"]
+    passive: true
+
+  - name: "private_fund_type"
+    type: string
+    description: "Fund type for pooled investment fund issuers in Form D: Venture Capital Fund, Hedge Fund, Private Equity Fund, Real Estate Fund, etc."
+    display_name: "Private Fund Type"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["Venture Capital Fund", "Hedge Fund", "Private Equity Fund"]
+    passive: true
+
+  - name: "year_of_inc"
+    type: string
+    description: "Year the issuer was incorporated or formed (from Form D)"
+    display_name: "Year of Incorporation"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["2024", "1985"]
+    passive: true
+
+  # ── Form D: Offering Attributes (on sec::form_d) ──
+  #
+  # Offering-level facts use the `offering_` prefix to scope them clearly
+  # to the offering record (sec::form_d) and avoid collisions with future
+  # broader concepts of "amount" or "investors" on other filing types.
+  # Booleans derivable from other properties (e.g. is_amendment, recoverable
+  # from form_type ending in "/A") are intentionally omitted — see the
+  # Form D handler for the derivation contract.
+
+  - name: "date_of_first_sale"
+    type: string
+    description: "Date on which the first securities were sold in this offering (from Form D)"
+    display_name: "Date of First Sale"
+    mergeability: not_mergeable
+    domain_flavors: ["sec::form_d"]
+    examples: ["2026-02-26"]
+    passive: true
+
+  - name: "offering_total_amount"
+    type: float
+    description: "Total target offering size in USD (from Form D). Empty when the offering amount is Indefinite — see offering_amount_indefinite."
+    display_name: "Offering Total Amount"
+    mergeability: not_mergeable
+    domain_flavors: ["sec::form_d"]
+    passive: true
+
+  - name: "offering_amount_sold"
+    type: float
+    description: "Total amount already sold/raised from investors in USD (from Form D)"
+    display_name: "Offering Amount Sold"
+    mergeability: not_mergeable
+    domain_flavors: ["sec::form_d"]
+    passive: true
+
+  - name: "offering_total_investors"
+    type: float
+    description: "Number of investors who have already participated in this offering (from Form D). Typed as float to match the schema-wide convention for numeric counts (entity_number_of_employees, board_size, us_gaap:number_of_segments)."
+    display_name: "Offering Total Investors"
+    mergeability: not_mergeable
+    domain_flavors: ["sec::form_d"]
+    passive: true
+
+  - name: "offering_min_investment"
+    type: float
+    description: "Minimum investment accepted from a single investor in USD (from Form D)"
+    display_name: "Offering Min Investment"
+    mergeability: not_mergeable
+    domain_flavors: ["sec::form_d"]
+    passive: true
+
+  - name: "federal_exemption"
+    type: string
+    description: "Primary Reg D federal exemption claimed: 06b (Rule 506(b) accredited), 06c (Rule 506(c) general solicitation), 04a5, 04a6, etc."
+    display_name: "Federal Exemption"
+    mergeability: not_mergeable
+    domain_flavors: ["sec::form_d"]
+    examples: ["06b", "06c", "04a5"]
+    passive: true
+
+  - name: "offering_amount_indefinite"
+    type: string
+    description: "Whether the total offering amount is Indefinite (open-ended offering with no fixed cap): Y or N"
+    display_name: "Indefinite Offering"
+    mergeability: not_mergeable
+    domain_flavors: ["sec::form_d"]
+    examples: ["Y", "N"]
+    passive: true
+
+  - name: "issuer_size_range"
+    type: string
+    description: "Verbal size range of the issuer from Form D: aggregateNetAssetValueRange for funds or revenueRange for operating companies"
+    display_name: "Issuer Size Range"
+    mergeability: not_mergeable
+    domain_flavors: ["sec::form_d"]
+    examples: ["$1 - $5,000,000", "Over $1,000,000,000", "Decline to Disclose"]
+    passive: true
+
+  - name: "more_than_one_year"
+    type: string
+    description: "Whether the offering is expected to last more than one year: true or false (from Form D durationOfOffering)"
+    display_name: "Multi-Year Offering"
+    mergeability: not_mergeable
+    domain_flavors: ["sec::form_d"]
+    examples: ["true", "false"]
+    passive: true
+
+  - name: "has_non_accredited_investors"
+    type: string
+    description: "Whether the offering has sold securities to any non-accredited investors: true or false (from Form D)"
+    display_name: "Non-Accredited Investors"
+    mergeability: not_mergeable
+    domain_flavors: ["sec::form_d"]
+    examples: ["true", "false"]
+    passive: true
+
+  - name: "is_40_act_fund"
+    type: string
+    description: "Whether the issuer is a fund registered under the Investment Company Act of 1940: true or false. Registered funds are subject to stricter regulation than exempt funds under 3(c)(1) or 3(c)(7). This is the issuer's own assertion at Form D filing time; the canonical durable registrant attribute for the same concept is investment_company_type on organization (a non-empty value there implies 1940 Act registration)."
+    display_name: "40 Act Registered"
+    mergeability: not_mergeable
+    domain_flavors: ["sec::form_d"]
+    examples: ["true", "false"]
+    passive: true
+
   # ── Financial Instrument: N-PORT Fund Financials ──
 
   - name: "fund_total_assets"
@@ -2375,8 +2535,8 @@ relationships:
     description: "Link from a company or person to an SEC filing document they filed, or from a sub-record (event, transaction, holding) to its parent filing"
     display_name: "Filed"
     mergeability: not_mergeable
-    domain_flavors: ["organization", "person", "sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::nport_p", "sec::ncen", "sec::filing"]
-    target_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::nport_p", "sec::ncen", "sec::filing"]
+    domain_flavors: ["organization", "person", "sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::nport_p", "sec::ncen", "sec::form_d", "sec::filing"]
+    target_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::nport_p", "sec::ncen", "sec::form_d", "sec::filing"]
     passive: true
 
   - name: "is_issuer_of"
@@ -2392,7 +2552,7 @@ relationships:
     display_name: "Filing Reference"
     mergeability: not_mergeable
     domain_flavors: ["organization", "person", "financial_instrument"]
-    target_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::nport_p", "sec::ncen"]
+    target_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::nport_p", "sec::ncen", "sec::form_d"]
     passive: true
 
   # ── Filing → Organization ──
@@ -2401,7 +2561,7 @@ relationships:
     description: "Link from a filing or financial instrument to the company it pertains to (the filer for most forms; the issuer for ownership forms and 13F holdings)"
     display_name: "Issued By"
     mergeability: not_mergeable
-    domain_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::nport_p", "sec::ncen", "sec::filing", "financial_instrument"]
+    domain_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::nport_p", "sec::ncen", "sec::form_d", "sec::filing", "financial_instrument"]
     target_flavors: ["organization"]
     passive: true
 
@@ -2417,7 +2577,23 @@ relationships:
     description: "Link from a filing to the entity (person or organization) who filed it"
     display_name: "Filer"
     mergeability: not_mergeable
-    domain_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::nport_p", "sec::ncen", "sec::filing"]
+    domain_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::nport_p", "sec::ncen", "sec::form_d", "sec::filing"]
+    target_flavors: ["organization", "person"]
+    passive: true
+
+  # placed_offering is a per-offering transactional edge from the Form D
+  # filing to a sales compensation recipient — distinct from the N-CEN
+  # service-provider edges (audited_by, advised_by, has_principal_underwriter,
+  # has_transfer_agent, custodied_by, sub_advised_by, has_securities_lending_
+  # agent), which are durable registrant-↔-provider relationships that live
+  # on the organization or financial_instrument. A single broker-dealer may
+  # appear as `placed_offering` from many Form D filings while never
+  # appearing on an N-CEN service-provider edge for those same issuers.
+  - name: "placed_offering"
+    description: "Link from a Form D filing to a broker-dealer, investment adviser, or registered representative receiving sales compensation for placing the Reg D offering"
+    display_name: "Placed Offering"
+    mergeability: not_mergeable
+    domain_flavors: ["sec::form_d"]
     target_flavors: ["organization", "person"]
     passive: true