@yottagraph-app/data-model-skill 0.0.5 → 0.0.7

package/package.json

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

package/skill/edgar/DATA_DICTIONARY.md

@@ -52,7 +52,32 @@ Each SEC form type is a separate flavor, namespaced under `sec`. All share the s
 | `sec::13f_hr` | 13F-HR | Institutional investment manager holdings |
 | `sec::def_14a` | DEF 14A | Definitive proxy statement |
 
-Sub-records (8-K events, Form 4 transactions, Form 3 holdings) use their parent filing's flavor.
+### Sub-Records (8-K Events, Form 4 Transactions, Form 3 Holdings)
+
+Sub-records are **separate graph entities**, not nested properties on the parent filing. Each sub-record has its own NEID and can be queried independently. They use the same flavor as their parent filing (e.g., `sec::8_k` for 8-K events, `sec::form_4` for Form 4 transactions).
+
+**Entity naming pattern:**
+- 8-K events: `{accession_number}_evt_{n}` (e.g., `0000320193-24-000067_evt_1`)
+- Form 4 transactions: `{accession_number}_trx_{n}` (e.g., `0000320193-24-000067_trx_1`)
+- Form 3 holdings: `{accession_number}_holding_{n}`
+
+**Relationships on sub-records:**
+- `filed` — points to the parent filing's accession number
+- `issued_by` — points to the company
+
+**Critical querying note:** Properties like `form_8k_event`, `form_8k_item_code`, `transaction_type`, `shares_transacted`, and other sub-record-specific properties do NOT appear on the parent filing entity or the organization entity. You must traverse the graph to the sub-record entities to access them.
+
+**Traversal path:**
+```
+organization --[filed]--> 8-K filing --[linked, distance 1]--> event sub-records
+```
+
+**Example: Finding 8-K event sub-records for a company:**
+1. Get filing NEIDs from the organization's `filed` property
+2. Filter to 8-K filings by checking `form_type == "8-K"`
+3. For each 8-K filing, use a `linked` expression (distance 1, direction both) to find connected entities
+4. Exclude the organization and the filing itself from results — the remaining entities are the event sub-records
+5. Query those sub-record NEIDs for `form_8k_event` and `form_8k_item_code`
 
 ### `person`
 
@@ -161,12 +186,34 @@ The six core financial properties appear on both the **organization** and its **
 
 #### 8-K Corporate Events (source: `edgar_8k`)
 
-Data source: 8-K current report filings. Properties on document sub-records.
+Data source: 8-K current report filings.
+
+> **Important:** These properties are on **event sub-record entities**, not on the parent 8-K filing or the organization. See the [Sub-Records section](#sub-records-8-k-events-form-4-transactions-form-3-holdings) above for how to find them.
 
+**Core event properties:**
 * `form_8k_event` — Snake_case event identifier. Examples: `"material_agreement"`, `"officer_director_change"`
 * `form_8k_item_code` — Raw SEC item number. Examples: `"1.01"`, `"5.02"`
+* `event_severity` — Event importance classification. Values: `"critical"`, `"high"`, `"medium"`, `"low"`
 * `category` — Sub-classification of Item 8.01 Other Events. Examples: `"cybersecurity_incident"`
 
+**Sub-record identity and relationships:**
+* `accession_number` — Synthetic sub-record identifier. Example: `"0000320193-24-000067_evt_1"`
+* `filed` — Relationship: event sub-record → parent 8-K filing
+* `issued_by` — Relationship: event sub-record → company
+
+**Item 8.01 keyword flags** (set to `"true"` when matched):
+* `8k_cybersecurity_keyword` — Cybersecurity-related disclosure detected
+* `8k_litigation_keyword` — Litigation-related disclosure detected
+* `8k_regulatory_keyword` — Regulatory-related disclosure detected
+* `8k_operational_keyword` — Operational issue disclosure detected
+
+**ABS event flags** (Items 6.01–6.05, set to `"true"` when applicable):
+* `abs_servicing_event` — Item 6.01: ABS servicing event
+* `abs_servicer_change` — Item 6.02: ABS servicer change
+* `abs_credit_enhancement_change` — Item 6.03: ABS credit enhancement change
+* `abs_failure_event` — Item 6.04: ABS failure to make distribution
+* `abs_securities_act` — Item 6.05: ABS Securities Act updating disclosure
+
 #### Beneficial Ownership (source: `edgar_sc_13d`, `edgar_sc_13g`)
 
 Data source: SC 13D/G XML filings. Properties on the filer organization.
@@ -240,8 +287,14 @@ Data source: Form 3/4 XML.
 
 #### Form 4 Transactions (source: `edgar_4`)
 
-Properties on document sub-records, one per transaction.
+> **Important:** These properties are on **transaction sub-record entities**, not on the parent Form 4 filing. See the [Sub-Records section](#sub-records-8-k-events-form-4-transactions-form-3-holdings) above for how to find them.
+
+**Sub-record identity and relationships:**
+* `accession_number` — Synthetic sub-record identifier. Example: `"0000320193-24-000067_trx_1"`
+* `filed` — Relationship: transaction sub-record → parent Form 4 filing
+* `issued_by` — Relationship: transaction sub-record → issuer company
 
+**Transaction properties:**
 * `transaction_type` — Human-readable code description. Examples: `"Open market or private purchase"`, `"Grant, award, or other acquisition"`
 * `transaction_date` — Transaction date (YYYY-MM-DD)
 * `acquired_disposed_code` — `"A"` (acquired) or `"D"` (disposed)
@@ -284,6 +337,8 @@ Data source: 13F-HR XML information table.
 
 ## Entity Relationships
 
+> **Sub-record traversal:** Sub-records (8-K events, Form 4 transactions, Form 3 holdings) are separate document entities. To find them, traverse from the parent filing using a `linked` expression (distance 1). The sub-record's `filed` property points back to the parent filing, and `issued_by` points to the company.
+
 ```
 organization         ──[filed]────────────────────→ document
 organization         ──[filing_reference]─────────→ document
@@ -296,7 +351,8 @@ document             ──[refers_to]──────────────
 document             ──[filer]────────────────────→ organization    (SC 13D/G)
 document             ──[group_member]─────────────→ organization    (SC 13D)
 document             ──[compares_to]──────────────→ organization    (DEF 14A)
-document             ──[filed]────────────────────→ document        (sub-record → parent)
+document (sub-record)──[filed]────────────────────→ document        (8-K event → parent 8-K filing)
+document (sub-record)──[issued_by]────────────────→ organization    (8-K event / Form 4 txn → company)
 person               ──[is_officer]───────────────→ organization
 person               ──[is_director]──────────────→ organization
 person               ──[is_ten_percent_owner]─────→ organization

package/skill/edgar/schema.yaml

@@ -126,6 +126,14 @@ flavors:
     strong_id_properties: ["accession_number"]
     passive: true
 
+  - name: "filing"
+    namespace: "sec"
+    description: "SEC filing (generic, for form types without a specific modeled flavor)"
+    display_name: "SEC Filing"
+    mergeability: not_mergeable
+    strong_id_properties: ["accession_number"]
+    passive: true
+
   - name: "person"
     description: "A real person as opposed to a fictional character, such as a CEO, politician, or public figure"
     display_name: "Person"
@@ -574,7 +582,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"]
+    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::filing"]
     passive: true
 
   - name: "form_type"
@@ -582,7 +590,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"]
+    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::filing"]
     passive: true
 
   - name: "filing_date"
@@ -590,7 +598,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"]
+    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::filing"]
     passive: true
 
   - name: "report_date"
@@ -598,7 +606,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"]
+    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::filing"]
     passive: true
 
   # ── XBRL Financial Facts (key concepts) ──
@@ -1720,8 +1728,16 @@ relationships:
     description: "Link from a company to an SEC filing document it filed, or from a sub-record (event, transaction, holding) to its parent filing"
     display_name: "Filed"
     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"]
-    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"]
+    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::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::filing"]
+    passive: true
+
+  - name: "is_issuer_of"
+    description: "Link from an issuer organization to a Section 16 ownership filing (Forms 3/4) where the CIK is the issuer, not the filer. The actual filer (insider) is resolved from the raw document header."
+    display_name: "Is Issuer Of"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    target_flavors: ["sec::form_3", "sec::form_4", "sec::filing"]
     passive: true
 
   - name: "filing_reference"
@@ -1738,7 +1754,7 @@ relationships:
     description: "Link from a filing to the company it pertains to (the filer for most forms; the issuer for ownership forms)"
     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"]
+    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::filing"]
     target_flavors: ["organization"]
     passive: true