@yottagraph-app/data-model-skill 0.0.38 → 0.0.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottagraph-app/data-model-skill",
-  "version": "0.0.38",
+  "version": "0.0.40",
   "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

@@ -51,6 +51,7 @@ Each SEC form type is a separate flavor, namespaced under `sec`. All share the s
 | `sec::sc_13g` | SC 13G | Beneficial ownership report (passive) |
 | `sec::13f_hr` | 13F-HR | Institutional investment manager holdings |
 | `sec::def_14a` | DEF 14A | Definitive proxy statement |
+| `sec::s_4` | S-4 | Registration statement for securities issued in business combinations (mergers, acquisitions, exchange offers). Heuristic extraction of acquisition target, target legal counsel, and M&A classification. |
 | `sec::6_k` | 6-K | Foreign private issuer current report (XBRL only, no form download) |
 | `sec::40_f` | 40-F | Canadian cross-border annual report (XBRL only, no form download) |
 | `sec::filing` | SEC Filing | Generic filing — defined in `schema.yaml` but **never produced**: `SecFormFlavor()` returns `""` for unmodeled forms, causing them to be skipped in `AtomizeFilingsV2` |

package/skill/edgar/schema.yaml

@@ -157,6 +157,14 @@ flavors:
     strong_id_properties: ["accession_number"]
     passive: true
 
+  - name: "s_4"
+    namespace: "sec"
+    description: "Registration statement (Form S-4) filed to register securities issued in connection with a business combination, merger, or acquisition."
+    display_name: "S-4"
+    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."
@@ -212,7 +220,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", "sec::form_d"]
+    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", "sec::s_4"]
     passive: true
 
   - name: "ticker"
@@ -634,7 +642,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::form_d", "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::s_4", "sec::filing"]
     passive: true
 
   - name: "form_type"
@@ -642,7 +650,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::form_d", "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::s_4", "sec::filing"]
     passive: true
 
   - name: "filing_date"
@@ -650,7 +658,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::form_d", "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::s_4", "sec::filing"]
     passive: true
 
   - name: "report_date"
@@ -658,8 +666,280 @@ 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::form_d", "sec::filing"]
-    passive: true
+    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::s_4", "sec::filing"]
+    passive: true
+
+  # ── S-4 M&A Metadata ──
+
+  - name: "mna_classification"
+    type: string
+    description: "High-level classification of the S-4 transaction type. merger / exchange_offer are real third-party transactions (target extraction applies); no_acquisition_target marks spin-offs, redomestications, internal restructurings, and shelf S-4s where the filing has no real third-party target (target extraction is skipped to avoid hallucinated emissions)."
+    display_name: "M&A Classification"
+    mergeability: not_mergeable
+    domain_flavors: ["sec::s_4"]
+    classification:
+      values:
+        - name: "merger"
+          description: "Statutory merger or acquisition via merger agreement"
+        - name: "exchange_offer"
+          description: "Securities exchange offer (one company offers its shares for shares of another)"
+        - name: "no_acquisition_target"
+          description: "Non-acquisition transaction — spin-off / separation, redomestication / change-of-jurisdiction, internal corporate restructuring, or business-combination shelf S-4. No third-party target."
+    passive: true
+
+  - name: "mna_filing_state"
+    type: string
+    description: |
+      State of the M&A transaction at the time of this filing. Derived
+      deterministically from the form_type — no LLM extraction:
+        - "registered"  — initial registration or amendment, deal pending.
+                          S-4, S-4/A, S-4EF, S-4POS, F-4, F-4/A, F-4EF, F-4POS.
+        - "effective"   — merger has closed at filing time. S-4MEF, F-4MEF
+                          (Merger Effective registrations are filed at or
+                          immediately after the effective date).
+      Use this to distinguish pending acquisitions from completed ones when
+      querying the s_4 document set. The graph also carries this distinction
+      via the has_acquisition_target (pending) vs has_acquired (closed)
+      relationships.
+    display_name: "M&A Filing State"
+    mergeability: not_mergeable
+    domain_flavors: ["sec::s_4"]
+    passive: true
+
+  - name: "mna_deal_type"
+    type: string
+    description: |
+      How the consideration paid to target shareholders is structured. Look at the "Merger Consideration" or "Consideration" section of the merger agreement / Q&A — focus on what target shareholders RECEIVE at closing in exchange for each share they hold.
+
+      Reasoning steps:
+      1. Find the merger-consideration clause (typically "Each share of [target] common stock ... shall be converted into the right to receive ...").
+      2. Categorize what they receive: cash only, acquirer-stock only, or a mix.
+      3. If shareholders may ELECT between cash and stock (with proration), that is cash_and_stock.
+      4. asset_purchase is rare in S-4 filings and applies ONLY when the acquirer is purchasing specific assets and leaving the target entity intact — NOT a stock-for-stock merger of the whole company, NOT an acquisition of all outstanding shares.
+
+      Worked examples:
+      - "each share ... converted into 0.123 shares of Acquirer common stock" → stock
+      - "each share ... converted into $X.XX in cash" → cash
+      - "each share ... converted into $X.XX in cash AND 0.123 shares of Acquirer common stock" → cash_and_stock
+      - "each share ... shall be converted into, at the holder's election, either $X.XX cash or 0.123 shares (subject to proration)" → cash_and_stock
+      - Debt-for-debt exchange offer (registering new notes for old notes) → not_disclosed
+
+      Negative examples (do NOT classify as asset_purchase):
+      - "Acquirer will acquire all outstanding shares of Target" → this is stock or cash, NOT asset_purchase
+      - "purchase of the Company" without an explicit asset list → stock or cash, NOT asset_purchase
+    display_name: "M&A Deal Type"
+    mergeability: not_mergeable
+    domain_flavors: ["sec::s_4"]
+    extraction_config:
+      level: document
+      classification:
+        include_snippet: true
+        values:
+          - name: "cash"
+            description: "Target shareholders receive cash only"
+          - name: "stock"
+            description: "Target shareholders receive acquirer shares only (including stock-for-stock mergers with fractional cash)"
+          - name: "cash_and_stock"
+            description: "Target shareholders receive a mix of cash and acquirer shares, or may elect between them"
+          - name: "asset_purchase"
+            description: "Acquirer purchases specific assets of the target rather than acquiring the target's equity. Rare in S-4 filings."
+          - name: "not_disclosed"
+            description: "Consideration structure is not specified in the filing (e.g., debt-only exchange offers and notes-for-notes registrations)"
+
+  - name: "mna_deal_value_usd"
+    type: float
+    description: |
+      Aggregate transaction value in USD — the total consideration the acquirer is paying for the target as an enterprise. Return as a plain integer dollar amount with no symbols, units, commas, or words — e.g., 2300000000 for $2.3 billion, 850000000 for $850 million.
+
+      What qualifies (return ONE of these if explicitly stated):
+        - "aggregate transaction value of $X"
+        - "total enterprise value of $X"
+        - "total equity value of $X"
+        - "aggregate consideration of $X" (when X is the deal total, not per share)
+        - "valuing [target] at $X" (when X is total, not per share)
+
+      What does NOT qualify — return 'not stated' rather than guessing from these:
+        - Per-share price ("$13.00 per share", "$X.XX per share in cash") — even though the math would yield an aggregate, do NOT compute it; the prompt asks for a stated aggregate.
+        - Termination/breakup fees (these are typically 2-5% of deal size and appear in the agreement's termination article).
+        - Advisor / banker / financial-advisor / fairness-opinion fees (e.g., "Goldman Sachs received $23M").
+        - SPAC trust amounts ("$300M held in trust", "$19.4M remaining after redemptions") — those are SPAC cash, not deal value.
+        - Top-up consideration caps, contingent value rights (CVRs), earn-outs, or any conditional figure.
+        - The acquirer's market cap or the target's market cap (those are not the transaction value).
+
+      Worked examples (from real S-4 audit failures):
+        - "Goldman Sachs ... financial advisor ... aggregate fee of $23 million" → 'not stated' (advisor fee, not deal value).
+        - "termination fee of $296 million payable to [Acquirer]" → 'not stated' (termination fee).
+        - "$415 million election cap" → 'not stated' (per-share election cap, not aggregate).
+        - "remaining $19.4 million in the Trust Account" → 'not stated' (SPAC trust balance).
+        - "merger consideration of $6.50 per share" → 'not stated' (per-share, do not multiply).
+        - "transaction values the company at approximately $2.3 billion" → 2300000000.
+
+      Return 'not stated' if no aggregate transaction value is disclosed in the document.
+    display_name: "M&A Deal Value (USD)"
+    mergeability: not_mergeable
+    domain_flavors: ["sec::s_4"]
+    extraction_config:
+      level: document
+      literal:
+        include_snippet: true
+
+  - name: "mna_tax_treatment"
+    type: string
+    description: |
+      U.S. federal income tax treatment of the transaction. Look in the "Material U.S. Federal Income Tax Consequences" section — this is where tax treatment is characterized. If that section is not present in the provided text, return not_disclosed.
+
+      Decision rule:
+        - tax_free: ONLY when the filing explicitly says the transaction is intended to qualify as a "reorganization within the meaning of Section 368(a)" of the Internal Revenue Code (or equivalent tax-free reorganization language — Section 351, Section 332, etc.). The phrase "Section 368(a)" or "reorganization" is the canonical signal. The snippet you return MUST contain this language verbatim.
+        - taxable: when the filing explicitly states target shareholders will recognize taxable gain/loss on the entire consideration. Common in all-cash deals.
+        - partially_taxable: when the filing states the transaction has both taxable and tax-free components (e.g., cash boot in an otherwise tax-free reorganization).
+        - not_disclosed: when the filing does not characterize tax treatment in the text you are reading. This is the correct default for debt exchange offers, redomestications, and any filing missing a tax-consequences section. Do NOT guess from deal structure (all-stock does not automatically mean tax_free).
+
+      Worked examples (from real S-4 audit failures):
+        - Filing says "intended to qualify as a reorganization within the meaning of Section 368(a)" → tax_free (this is the canonical formula — never classify this as taxable).
+        - Filing says "the Merger will be a taxable transaction for U.S. federal income tax purposes" → taxable.
+        - Debt exchange offer with no tax section in the text → not_disclosed (do NOT commit to tax_free just because it's an exchange).
+        - All-stock merger with no Section 368 language anywhere in the document → not_disclosed.
+    display_name: "M&A Tax Treatment"
+    mergeability: not_mergeable
+    domain_flavors: ["sec::s_4"]
+    extraction_config:
+      level: document
+      classification:
+        include_snippet: true
+        values:
+          - name: "tax_free"
+            description: "Filing explicitly states the transaction is intended to qualify as a reorganization under Section 368(a) (or similar tax-free reorganization provision). The snippet MUST contain Section 368(a) / reorganization language verbatim."
+          - name: "taxable"
+            description: "Filing explicitly states the transaction is fully taxable to target shareholders on the entire consideration"
+          - name: "partially_taxable"
+            description: "Filing states the transaction has both taxable and tax-free components (e.g., cash boot in an otherwise tax-free reorganization)"
+          - name: "not_disclosed"
+            description: "Filing does not characterize tax treatment in the reviewed text. Default for debt exchange offers, redomestications, and any filing missing a Material U.S. Federal Income Tax Consequences section."
+
+  - name: "mna_termination_fee_usd"
+    type: float
+    description: |
+      Termination or break-up fee in USD — the amount one party must pay the other if the merger agreement is terminated under specified conditions (e.g., target accepts a superior offer). The termination fee lives in the "Termination" article of the merger agreement, NOT in the consideration section. Return as a plain integer dollar amount with no symbols, units, commas, or words — e.g., 85000000 for $85 million.
+
+      What qualifies:
+        - "termination fee of $X" or "breakup fee of $X" payable by one party to the other on specified termination events.
+        - Reciprocal fees: if there are two different figures (one payable by target, one by acquirer), return the LARGER one (typically the target-payable fee).
+
+      What does NOT qualify — return 'not stated' rather than guessing:
+        - The aggregate deal value (typically 20-50x larger).
+        - Per-share consideration.
+        - SPAC trust amounts or sponsor forfeiture amounts.
+        - Advisor/banker fees (e.g., "Goldman Sachs received $23M").
+        - Expense reimbursement caps (those are NOT the termination fee — they are typically much smaller, like $5-15M for documented expenses).
+
+      Worked examples (from real S-4 audit failures):
+        - "in the event of termination ... [Target] shall pay [Acquirer] a termination fee equal to $85,000,000" → 85000000.
+        - "Goldman Sachs ... $23 million fee" → 'not stated' (advisor fee, not termination fee).
+        - "$10 million expense reimbursement" → 'not stated' (expense cap, not termination fee).
+        - No "Termination" article in the provided text → 'not stated'.
+
+      Return 'not stated' if no termination fee is disclosed in the provided text. NEVER return 0 — use 'not stated'.
+    display_name: "M&A Termination Fee (USD)"
+    mergeability: not_mergeable
+    domain_flavors: ["sec::s_4"]
+    extraction_config:
+      level: document
+      literal:
+        include_snippet: true
+
+  - name: "mna_acquisition_target_name"
+    type: string
+    # The property description is wrapped into the LLM's system instruction
+    # by the extraction library. It needs to carry the role definitions,
+    # identification strategy, and anti-hedge guidance — the library's own
+    # boilerplate is "Extract the exact value as stated in the text. Be
+    # precise — return the value exactly as it appears, without
+    # interpretation", which primes the model to return "not stated" when
+    # it can't find a single self-contained verbatim phrase. The May-22
+    # diagnostic run showed 10/16 filings hit that hedge path even on
+    # obvious deals (Getty/Shutterstock, Quanterix/Akoya, etc.), so the
+    # description must override "verbatim only" with explicit
+    # "synthesize from context" framing.
+    description: |
+      Identify the operating company being acquired in this SEC Form S-4 transaction.
+
+      An S-4 is filed for a business combination (merger, exchange offer, reverse merger, or de-SPAC). The document has three roles:
+
+      1. REGISTRANT (legal acquirer): the public company filing this S-4. It is named in the EXTRACTION CONTEXT block at the start of the filing text.
+
+      2. TRANSITORY MERGER SUBSIDIARY: a wholly-owned shell the registrant creates solely to merge with the target. Names typically contain "Merger Sub", "Acquisition Sub", "Acquisition Corp", or numbered variants. Dissolves at closing — never the target.
+
+      3. TARGET: the operating company being acquired. Its shares are converted or cancelled at the Effective Time; its shareholders receive the registrant's shares or cash consideration. This is what you must return.
+
+      The most reliable text anchor for the target is the Merger Consideration clause: "Each share of [TARGET] common stock outstanding immediately prior to the Effective Time shall be converted into the right to receive [consideration]." The company whose stock is being converted is the target.
+
+      Identifying the target requires INFERENCE across the document — the target's name is rarely stated in a single self-contained "the target is X" sentence. Synthesize from the Merger Consideration clause, the merger agreement parties list ("by and among ..."), the Q&A section ("Who is merging?", "What will [target] stockholders receive?"), and the "Information About the Companies" subsection of the Summary.
+
+      For reverse mergers and de-SPAC transactions, the operating company being acquired is the target — even when it is designated as the "accounting acquirer" under ASC 805. Follow legal structure, not accounting treatment.
+
+      Return the target's full legal name with corporate suffix (Inc., LLC, Corp., Ltd., LP, plc) exactly as it appears in the filing.
+
+      Return "not stated" ONLY when there is no acquisition target at all — debt-for-debt exchange offers, redomestications, jurisdiction redomiciliations, holdco reorganizations, or spin-offs. Do NOT return "not stated" because the target's name doesn't appear in a single self-contained verbatim phrase. The target is essentially always identifiable from the Merger Consideration clause and the merger agreement parties list.
+
+      Snippet: the verbatim Merger Consideration clause, or any single sentence from the filing that names the target.
+    display_name: "M&A Acquisition Target Name"
+    mergeability: not_mergeable
+    domain_flavors: ["sec::s_4"]
+    extraction_config:
+      level: document
+      literal:
+        include_snippet: true
+
+  - name: "mna_transitory_merger_sub"
+    type: string
+    description: |
+      Identify the transitory merger subsidiary used in this S-4 transaction, if one is named.
+
+      A transitory merger subsidiary is a wholly-owned shell entity created by the registrant solely to merge with the target. It dissolves at closing. Names typically contain "Merger Sub", "Acquisition Sub", "Acquisition Corp", "Merger Co", or numbered variants (e.g., "Merger Sub I", "Polar Merger Sub, Inc.").
+
+      The merger sub is NEVER the target — it is a separate role.
+
+      Return the full legal name of the merger subsidiary with corporate suffix, exactly as it appears in the filing.
+
+      Return "not stated" only if no transitory merger subsidiary is named (common in direct mergers, exchange offers, and asset purchases where no shell vehicle is interposed).
+    display_name: "M&A Transitory Merger Sub"
+    mergeability: not_mergeable
+    domain_flavors: ["sec::s_4"]
+    extraction_config:
+      level: document
+      literal: {}
+
+  - name: "mna_target_legal_counsel_name"
+    type: string
+    description: |
+      Name of the law firm representing the acquisition target (the non-registrant party). Found on the S-4 cover page, typically in a "Copies to:" block.
+
+      Reasoning steps:
+      1. The cover page lists two law firms: one for the registrant (filer), one for the target. Look for a "Copies to:" or "Copies of all communications to:" block.
+      2. The firm whose contact line names an officer of the TARGET (CEO, General Counsel, etc. of the company being acquired) is the target's counsel.
+      3. If the cover-page contact block names two firms side-by-side, the second firm or the one paired with the target-officer contact is target counsel.
+
+      What qualifies — return the full firm name with suffix:
+        - "Sullivan & Cromwell LLP"
+        - "Wachtell, Lipton, Rosen & Katz"
+        - "Skadden, Arps, Slate, Meagher & Flom LLP"
+        - "Dentons US LLP"
+        - "Stevens & Lee, P.C."
+
+      What does NOT qualify — return 'not stated' rather than guess:
+        - Advisor / financial advisor names (Goldman Sachs, JPMorgan, Centerview) — those are bankers, not legal counsel.
+        - Auditor / accountant names (Deloitte, PwC, KPMG, EY).
+        - The acquirer's counsel (only target counsel is wanted here).
+        - Generic placeholders like "Legal Counsel" or "Outside Counsel".
+
+      If only the acquirer's counsel is identified and no separate target counsel block is present, return 'not stated'. Return the full firm name including suffix (LLP, PC, P.C., PLLC, LLC). Snippet should be the cover-page contact block text where you found the firm.
+    display_name: "M&A Target Legal Counsel Name"
+    mergeability: not_mergeable
+    domain_flavors: ["sec::s_4"]
+    extraction_config:
+      level: document
+      literal:
+        include_snippet: true
 
   # ── XBRL Financial Facts (key concepts) ──
 
@@ -2535,8 +2815,8 @@ relationships:
     description: "Link from a company or person to a regulatory filing document they filed, or from a sub-record 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::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"]
+    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::s_4", "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::s_4", "sec::filing"]
     passive: true
 
   - name: "is_issuer_of"
@@ -2552,7 +2832,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", "sec::form_d"]
+    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::s_4"]
     passive: true
 
   # ── Filing → Organization ──
@@ -2561,7 +2841,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::form_d", "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::s_4", "sec::filing", "financial_instrument"]
     target_flavors: ["organization"]
     passive: true
 
@@ -2569,7 +2849,7 @@ relationships:
     description: "Link from a filing or counterparty to the company the document is principally about"
     display_name: "Refers To"
     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", "organization"]
+    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::s_4", "organization"]
     target_flavors: ["organization"]
     passive: true
 
@@ -2577,7 +2857,7 @@ 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::form_d", "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::s_4", "sec::filing"]
     target_flavors: ["organization", "person"]
     passive: true
 
@@ -2860,6 +3140,56 @@ relationships:
     target_flavors: ["financial_instrument"]
     passive: true
 
+  # ── S-4 M&A Relationships ──
+
+  - name: "has_acquisition_target"
+    description: "Link from an acquiring organization to the company being acquired in a merger or acquisition disclosed via Form S-4."
+    display_name: "Has Acquisition Target"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    target_flavors: ["organization"]
+    passive: true
+
+  - name: "is_acquisition_target_of"
+    description: "Inverse of has_acquisition_target. Link from the target company to the acquirer in a merger or acquisition disclosed via Form S-4."
+    display_name: "Is Acquisition Target Of"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    target_flavors: ["organization"]
+    passive: true
+
+  - name: "has_target_legal_counsel"
+    description: "Link from an acquirer to the law firm acting as legal counsel to the target company in an S-4 merger transaction."
+    display_name: "Has Target Legal Counsel"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    target_flavors: ["organization"]
+    passive: true
+
+  - name: "is_target_legal_counsel_of"
+    description: "Link from a law firm to the company it represents as target legal counsel in an S-4 merger transaction."
+    display_name: "Is Target Legal Counsel Of"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    target_flavors: ["organization"]
+    passive: true
+
+  - name: "has_acquired"
+    description: "Link from an acquiring organization to a company it has acquired, where the merger has closed. Distinguishes completed acquisitions from pending ones (see has_acquisition_target). Emitted from S-4MEF and F-4MEF filings — Merger Effective registrations filed at or after the merger's effective date."
+    display_name: "Has Acquired"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    target_flavors: ["organization"]
+    passive: true
+
+  - name: "was_acquired_by"
+    description: "Inverse of has_acquired. Link from a company to the organization that has acquired it, where the merger has closed."
+    display_name: "Was Acquired By"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    target_flavors: ["organization"]
+    passive: true
+
 # =============================================================================
 # ATTRIBUTES
 # =============================================================================

package/skill/finnhubbond/DATA_DICTIONARY.md

@@ -0,0 +1,134 @@
+# Data Dictionary: Finnhub Bonds (ISIN-LEI + Bond Prices)
+
+Last updated: 2026-05-28
+
+## Source Overview
+
+This source combines two upstream datasets:
+
+1. **GLEIF-ANNA ISIN-to-LEI mapping** — daily open-source file linking financial instruments (ISIN) to issuers (LEI). The published ZIP is a **full snapshot** of mappings from participating national numbering agencies (~8.7M pairs as of May 2026), refreshed daily. It is not a delta of only newly issued ISINs from the prior day.
+2. **Finnhub bond prices** — end-of-day close prices from `GET /bond/price` for each ISIN in the mapping file, fetched for **yesterday UTC** each poll cycle.
+
+The streamer uses the **diffing** pipeline (`DiffingStreamer`): each mapping pair and each ISIN price observation is stored as JSON under the raw download store, SHA-256 compared against the previous run, and only changed rows are atomized and published.
+
+| Item | Value |
+|------|--------|
+| Stream source constant | `finnhubbond-source` |
+| `Record.Source` | `finnhubbond` |
+| GLEIF mapping API | `https://mapping.gleif.org/api/v2/isin-lei` |
+| Finnhub price API | `https://finnhub.io/api/v1/bond/price` |
+| Default poll cadence | 1440 min (`pollTimeMin`) |
+
+**Data quality notes**
+
+- GLEIF mapping coverage depends on participating NNAs; legacy ISINs outside the program may be absent.
+- Finnhub `/bond/price` returns BondCandles (`c[]` close, `t[]` unix timestamps, `s` status). Status `no_data` produces no price record.
+- Yield on `/bond/price` is only emitted when Finnhub returns a `y[]` array; TRACE trade-level yield is on `/bond/tick` (not ingested in v1).
+- Many mapped ISINs may have no Finnhub price (non-US, non-TRACE, delisted). Failures are logged and skipped.
+
+---
+
+## Entity Types
+
+### `organization`
+
+A legal entity that **issued** a mapped security, identified by LEI from the GLEIF-ANNA CSV.
+
+- **Subject name:** LEI string (no legal name in mapping file).
+- **Strong id:** `lei` on the organization subject.
+- **Resolver:** Organization flavor `NOT_MERGEABLE`; named entity `MERGEABLE` on LEI for cross-source merge with `gleif-source` entities.
+- **Emitted when:** A `(LEI, ISIN)` mapping row is new or changed in the diffing pass.
+
+### `financial_instrument`
+
+A bond or fixed-income instrument identified by ISIN.
+
+- **Subject name:** ISIN.
+- **Strong id:** `isin`.
+- **Resolver:** `MERGEABLE` on ISIN — aligns with `gleif`, `sanctions`, and EDGAR `holding_isin` resolution.
+- **Emitted when:** (1) mapping rows add `issued_security` target entities, or (2) price rows publish close/yield observations.
+
+---
+
+## Properties
+
+### Organization
+
+* `lei`
+  * Definition: Legal Entity Identifier (ISO 17442) of the issuer.
+  * Examples: `"5493001KJTIIGC8Y1R12"`
+  * Derivation: First CSV column in GLEIF ISIN-LEI mapping.
+
+### Financial instrument
+
+* `isin`
+  * Definition: International Securities Identification Number (ISO 6166).
+  * Examples: `"US0378331005"`, `"US46625HQW33"`
+  * Derivation: Second CSV column in mapping; or Finnhub price query key.
+
+* `close_price`
+  * Definition: Bond close price in USD from Finnhub `/bond/price` field `c[]`.
+  * Derivation: One atom per candle point in the response; timestamp from matching `t[]` entry.
+  * Attribute: `price_date` (YYYY-MM-DD UTC) on each observation atom.
+
+* `yield`
+  * Definition: Bond yield when Finnhub returns field `y[]` alongside price candles.
+  * Derivation: Optional; same indexing as `c[]` / `t[]`. Often absent on `/bond/price`.
+  * Attribute: `price_date` on each observation atom.
+
+---
+
+## Relationships
+
+* `issued_security`
+  * Definition: The organization (issuer LEI) has issued the target financial instrument (ISIN).
+  * Direction: `organization` → `financial_instrument`.
+  * Derivation: Each GLEIF-ANNA mapping row where both LEI and ISIN are non-empty.
+  * Note: Same relationship name and semantics as `gleif-source` ISIN enrichment (`buildISINAtoms`).
+
+---
+
+## Attributes
+
+* `price_date`
+  * Definition: UTC calendar date of the bond price observation.
+  * Examples: `"2026-05-27"`
+  * Derivation: From Finnhub candle timestamp `t[]`, or the configured yesterday date when timestamp missing.
+
+---
+
+## Pipeline Behavior
+
+### FetchRows (single cycle)
+
+1. Download latest GLEIF ISIN-LEI ZIP.
+2. Parse CSV; emit one diffing row per `(LEI, ISIN)` pair (subject to `maxRows`).
+3. Deduplicate ISINs; optionally cap with `maxIsins`.
+4. Parallel Finnhub `/bond/price` for yesterday UTC (`priceWorkers`, `finnhubQPS`).
+5. Emit one diffing price row per ISIN (`price-{ISIN}-{date}.json`).
+
+### Atomization
+
+- **Changed mapping rows:** One record per pair — organization subject + `lei` property + `issued_security` target.
+- **Changed price rows:** One record per ISIN — financial_instrument subject + `isin` + `close_price` / optional `yield` atoms.
+
+### Configuration args
+
+| Arg | Default | Purpose |
+|-----|---------|---------|
+| `finnhubToken` | `$FINNHUB_TOKEN` | Required API token |
+| `priceWorkers` | 16 | Parallel Finnhub workers |
+| `finnhubQPS` | 10 | Client-side rate limit |
+| `maxIsins` | 0 (all) | Cap price fetches for dev |
+| `maxRows` | 0 (all) | Cap mapping rows emitted |
+| `writeWorkers` | 8 | Diffing raw-store parallelism |
+| `batchSize` | 100 | Publish batch size |
+| `pollTimeMin` | 1440 | Poll interval (minutes) |
+
+---
+
+## Cross-Source Resolution
+
+- **`lei`** property matches `gleif.organization.lei` — issuer orgs from this source should merge with GLEIF LEI records when both exist.
+- **`isin`** property matches `financial_instrument.isin` across gleif, sanctions, EDGAR holdings.
+- **`issued_security`** inverse query: find issuer org whose `issued_security` points at an ISIN instrument node.

package/skill/finnhubbond/schema.yaml

@@ -0,0 +1,241 @@
+# Dataset schema for GLEIF ISIN-LEI mapping + Finnhub bond end-of-day prices.
+#
+# The streamer diffs LEI→ISIN mapping rows from the daily GLEIF-ANNA file and
+# fetches Finnhub /bond/price candles for every ISIN in the mapping each cycle.
+name: "finnhubbond"
+description: "GLEIF-ANNA ISIN-to-LEI issuer mappings and Finnhub bond end-of-day close prices for mapped ISINs"
+
+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: ["lei"]
+    passive: true
+
+  - name: "financial_instrument"
+    description: "A specific asset that can be traded, such as a stock, ETF, bond, CD, or fund. Companies are organizations, NOT financial instruments. Specific currency amounts are NOT financial instruments."
+    display_name: "Financial Instrument"
+    mergeability: not_mergeable
+    strong_id_properties: ["isin", "figi"]
+    passive: true
+
+properties:
+  - name: "lei"
+    type: string
+    description: "Legal Entity Identifier — a 20-character alphanumeric code uniquely identifying a legal entity in the global financial system (ISO 17442)"
+    display_name: "LEI"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    passive: true
+
+  - name: "isin"
+    type: string
+    description: "International Securities Identification Number (ISO 6166) uniquely identifying this financial instrument"
+    display_name: "ISIN"
+    mergeability: not_mergeable
+    domain_flavors: ["financial_instrument"]
+    passive: true
+
+  - name: "close_price"
+    type: float
+    description: "Closing price of the trading interval in USD"
+    display_name: "Close Price"
+    mergeability: not_mergeable
+    domain_flavors: ["financial_instrument"]
+    passive: true
+
+  - name: "yield"
+    type: float
+    description: "Yield on the security."
+    display_name: "Yield"
+    mergeability: not_mergeable
+    domain_flavors: ["financial_instrument"]
+    passive: true
+
+  - name: "figi"
+    type: string
+    description: "Financial Instrument Global Identifier (Bloomberg OpenFIGI)"
+    display_name: "FIGI"
+    mergeability: not_mergeable
+    domain_flavors: ["financial_instrument"]
+    passive: true
+
+  - name: "bond_type"
+    type: string
+    description: "Bond type from Finnhub /bond/profile (e.g. Corporate, Government)"
+    display_name: "Bond Type"
+    mergeability: not_mergeable
+    domain_flavors: ["financial_instrument"]
+    passive: true
+
+  - name: "debt_type"
+    type: string
+    description: "Debt type from Finnhub /bond/profile"
+    display_name: "Debt Type"
+    mergeability: not_mergeable
+    domain_flavors: ["financial_instrument"]
+    passive: true
+
+  - name: "coupon"
+    type: float
+    description: "Coupon rate of the security (e.g. 7.000% or Variable)."
+    display_name: "Coupon"
+    mergeability: not_mergeable
+    domain_flavors: ["financial_instrument"]
+    passive: true
+
+  - name: "coupon_type"
+    type: string
+    description: "Coupon type from Finnhub /bond/profile (e.g. Fixed)"
+    display_name: "Coupon Type"
+    mergeability: not_mergeable
+    domain_flavors: ["financial_instrument"]
+    passive: true
+
+  - name: "maturity_date"
+    type: string
+    description: "Maturity date of the security."
+    display_name: "Maturity Date"
+    mergeability: not_mergeable
+    domain_flavors: ["financial_instrument"]
+    passive: true
+
+  - name: "issue_date"
+    type: string
+    description: "Issue date of the bonds."
+    display_name: "Issue Date"
+    mergeability: not_mergeable
+    domain_flavors: ["financial_instrument"]
+    passive: true
+
+  - name: "first_coupon_date"
+    type: string
+    description: "First coupon date from Finnhub /bond/profile"
+    display_name: "First Coupon Date"
+    mergeability: not_mergeable
+    domain_flavors: ["financial_instrument"]
+    passive: true
+
+  - name: "dated_date"
+    type: string
+    description: "Dated date of the bonds."
+    display_name: "Dated Date"
+    mergeability: not_mergeable
+    domain_flavors: ["financial_instrument"]
+    passive: true
+
+  - name: "payment_frequency"
+    type: string
+    description: "Payment frequency from Finnhub /bond/profile"
+    display_name: "Payment Frequency"
+    mergeability: not_mergeable
+    domain_flavors: ["financial_instrument"]
+    passive: true
+
+  - name: "security_level"
+    type: string
+    description: "Security level from Finnhub /bond/profile (e.g. Senior)"
+    display_name: "Security Level"
+    mergeability: not_mergeable
+    domain_flavors: ["financial_instrument"]
+    passive: true
+
+  - name: "amount_outstanding"
+    type: float
+    description: "Amount outstanding from Finnhub /bond/profile"
+    display_name: "Amount Outstanding"
+    mergeability: not_mergeable
+    domain_flavors: ["financial_instrument"]
+    passive: true
+
+  - name: "original_offering"
+    type: float
+    description: "Original offering amount from Finnhub /bond/profile"
+    display_name: "Original Offering"
+    mergeability: not_mergeable
+    domain_flavors: ["financial_instrument"]
+    passive: true
+
+  - name: "offering_price"
+    type: float
+    description: "Offering price from Finnhub /bond/profile"
+    display_name: "Offering Price"
+    mergeability: not_mergeable
+    domain_flavors: ["financial_instrument"]
+    passive: true
+
+  - name: "industry_group"
+    type: string
+    description: "Industry group from Finnhub /bond/profile"
+    display_name: "Industry Group"
+    mergeability: not_mergeable
+    domain_flavors: ["financial_instrument"]
+    passive: true
+
+  - name: "industry_subgroup"
+    type: string
+    description: "Industry subgroup from Finnhub /bond/profile"
+    display_name: "Industry Subgroup"
+    mergeability: not_mergeable
+    domain_flavors: ["financial_instrument"]
+    passive: true
+
+  - name: "asset"
+    type: string
+    description: "Asset from Finnhub /bond/profile"
+    display_name: "Asset"
+    mergeability: not_mergeable
+    domain_flavors: ["financial_instrument"]
+    passive: true
+
+  - name: "asset_type"
+    type: string
+    description: "Asset type from Finnhub /bond/profile"
+    display_name: "Asset Type"
+    mergeability: not_mergeable
+    domain_flavors: ["financial_instrument"]
+    passive: true
+
+  - name: "day_count"
+    type: string
+    description: "Day count convention from Finnhub /bond/profile"
+    display_name: "Day Count"
+    mergeability: not_mergeable
+    domain_flavors: ["financial_instrument"]
+    passive: true
+
+  - name: "security_term"
+    type: string
+    description: "Security term from Finnhub /bond/profile"
+    display_name: "Security Term"
+    mergeability: not_mergeable
+    domain_flavors: ["financial_instrument"]
+    passive: true
+
+relationships:
+  - name: "issued_security"
+    description: "The organization has issued this financial instrument, linked via GLEIF-ANNA ISIN-LEI daily mapping. To find the issuer of a security, query inversely: find the entity whose issued_security points to the instrument."
+    display_name: "Issued Security"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    target_flavors: ["financial_instrument"]
+    passive: true
+
+attributes:
+  - properties:
+      - "close_price"
+      - "yield"
+    name: "price_date"
+    type: string
+    description: "UTC calendar date (YYYY-MM-DD) of the bond price observation from Finnhub timestamp t[]"
+    display_name: "Price Date"
+    mergeability: not_mergeable
+    passive: true

package/skill/stocks/schema.yaml

@@ -106,7 +106,7 @@ properties:
 
   - name: "close_price"
     type: float
-    description: "Closing price of the trading interval in USD, from Alpha Vantage field '4. close'"
+    description: "Closing price of the trading interval in USD"
     display_name: "Close Price"
     mergeability: not_mergeable
     domain_flavors: ["financial_instrument"]