Share-Class Relationship Mapping

Same Issuer Does Not Mean Same Security

Install and import

bash

npm install fintech-algorithms

import { calculate } from "fintech-algorithms/corporate-actions-and-security-master-data/identity-continuity/share-class-relationship-mapping";

Signature

calculate(data)

Worked example

executed Captured by running this function on the input its own test provides. Real output of real code — but not asserted against a published figure.

Input

data

{
  "query": {
    "rootEntityId": "SYN-CLASS-FOUNDER",
    "validAt": "2026-03-01T12:00:00Z",
    "knownAt": "2026-03-05T12:00:00Z",
    "compareShareClassIds": ["SYN-CLASS-FOUNDER", "SYN-CLASS-PUBLIC"]
  },
  "entities": [
    {
      "entityId": "SYN-ISSUER-ALPHA",
      "entityType": "ISSUER",
      "label": "Synthetic Alpha Holdings"
    },
    {
      "entityId": "SYN-INSTRUMENT-COMMON",
      "entityType": "LEGAL_INSTRUMENT",
      "label": "Synthetic Alpha Common Equity"
    },
    {
      "entityId": "SYN-INSTRUMENT-PREFERRED",
      "entityType": "LEGAL_INSTRUMENT",
      "label": "Synthetic Alpha Preferred Equity"
    }
  ],
  "relationships": [
    {
      "assertionId": "R-ISSUE-COMMON",
      "revisionNumber": 1,
      "status": "ACTIVE",
      "relationshipType": "ISSUED_BY",
      "sourceEntityId": "SYN-INSTRUMENT-COMMON",
      "targetEntityId": "SYN-ISSUER-ALPHA",
      "effectiveFrom": "2026-01-01T00:00:00Z",
      "effectiveTo": null,
      "observedAt": "2025-12-15T09:00:00Z",
      "availableAt": "2025-12-15T10:00:00Z",
      "source": {
        "sourceId": "SYN-CHARTER-1",
        "sourceType": "synthetic_charter",
        "documentDate": "2025-12-15",
        "locator": "Article IV"
      },
      "terms": {
        "basis": "legal-issuer"
      },
      "unsupportedTerms": []
    },
    {
      "assertionId": "R-ISSUE-PREF",
      "revisionNumber": 1,
      "status": "ACTIVE",
      "relationshipType": "ISSUED_BY",
      "sourceEntityId": "SYN-INSTRUMENT-PREFERRED",
      "targetEntityId": "SYN-ISSUER-ALPHA",
      "effectiveFrom": "2026-01-01T00:00:00Z",
      "effectiveTo": null,
      "observedAt": "2025-12-15T09:00:00Z",
      "availableAt": "2025-12-15T10:00:00Z",
      "source": {
        "sourceId": "SYN-CHARTER-1",
        "sourceType": "synthetic_charter",
        "documentDate": "2025-12-15",
        "locator": "Article IV"
      },
      "terms": {
        "basis": "legal-issuer"
      },
      "unsupportedTerms": []
    },
    {
      "assertionId": "R-CLASS-FOUNDER",
      "revisionNumber": 1,
      "status": "ACTIVE",
      "relationshipType": "CLASS_OF",
      "sourceEntityId": "SYN-CLASS-FOUNDER",
      "targetEntityId": "SYN-INSTRUMENT-COMMON",
      "effectiveFrom": "2026-01-01T00:00:00Z",
      "effectiveTo": null,
      "observedAt": "2025-12-15T09:00:00Z",
      "availableAt": "2025-12-15T10:00:00Z",
      "source": {
        "sourceId": "SYN-CHARTER-1",
        "sourceType": "synthetic_charter",
        "documentDate": "2025-12-15",
        "locator": "Article IV.1"
      },
      "terms": {
        "classCode": "F"
      },
      "unsupportedTerms": []
    }
  ]
}

Call

calculate(data)

Returns

object with 7 fields: query, root, state, sameIssuerShareClassIds, comparison, resolvedRelationships, diagnostics

{
  "query": {
    "rootEntityId": "SYN-CLASS-FOUNDER",
    "validAt": "2026-03-01T12:00:00Z",
    "knownAt": "2026-03-05T12:00:00Z"
  },
  "root": {
    "entityId": "SYN-CLASS-FOUNDER",
    "entityType": "SHARE_CLASS"
  },
  "state": "RESOLVED",
  "sameIssuerShareClassIds": ["SYN-CLASS-FOUNDER", "SYN-CLASS-PREFERRED", "SYN-CLASS-PUBLIC"],
  "comparison": {
    "leftShareClassId": "SYN-CLASS-FOUNDER",
    "rightShareClassId": "SYN-CLASS-PUBLIC",
    "votingRightsRatioLeftToRight": {
      "status": "ESTABLISHED",
      "numerator": 10,
      "denominator": 1,
      "unit": "votes_per_share"
    },
    "economicRightsRatioLeftToRight": {
      "status": "ESTABLISHED",
      "numerator": 1,
      "denominator": 1,
      "unit": "distribution_units_per_share"
    },
    "equalEconomics": true,
    "conversion": {
      "status": "ESTABLISHED",
      "direction": "SYN-CLASS-FOUNDER->SYN-CLASS-PUBLIC",
      "relationshipType": "CONVERTS_TO",
      "ratio": {
        "numerator": 1,
        "denominator": 1
      },
      "unit": "target_shares_per_source_share",
      "conditions": ["qualifying_transfer"]
    },
    "fungibility": {
      "status": "NOT_ESTABLISHED"
    },
    "priceConvertibility": "NOT_ESTABLISHED"
  },
  "resolvedRelationships": [
    {
      "assertionId": "R-CLASS-FOUNDER",
      "revisionNumber": 1,
      "relationshipType": "CLASS_OF",
      "sourceEntityId": "SYN-CLASS-FOUNDER",
      "targetEntityId": "SYN-INSTRUMENT-COMMON",
      "effectiveFrom": "2026-01-01T00:00:00Z",
      "effectiveTo": null,
      "observedAt": "2025-12-15T09:00:00Z",
      "availableAt": "2025-12-15T10:00:00Z",
      "source": {
        "sourceId": "SYN-CHARTER-1",
        "sourceType": "synthetic_charter",
        "documentDate": "2025-12-15",
        "locator": "Article IV.1"
      },
      "terms": {
        "classCode": "F"
      },
      "unsupportedTerms": []
    },
    {
      "assertionId": "R-CLASS-PREF",
      "revisionNumber": 1,
      "relationshipType": "CLASS_OF",
      "sourceEntityId": "SYN-CLASS-PREFERRED",
      "targetEntityId": "SYN-INSTRUMENT-PREFERRED",
      "effectiveFrom": "2026-01-01T00:00:00Z",
      "effectiveTo": null,
      "observedAt": "2025-12-15T09:00:00Z",
      "availableAt": "2025-12-15T10:00:00Z",
      "source": {
        "sourceId": "SYN-CHARTER-1",
        "sourceType": "synthetic_charter",
        "documentDate": "2025-12-15",
        "locator": "Article IV.3"
      },
      "terms": {
        "classCode": "PR"
      },
      "unsupportedTerms": []
    },
    {
      "assertionId": "R-CLASS-PUBLIC",
      "revisionNumber": 1,
      "relationshipType": "CLASS_OF",
      "sourceEntityId": "SYN-CLASS-PUBLIC",
      "targetEntityId": "SYN-INSTRUMENT-COMMON",
      "effectiveFrom": "2026-01-01T00:00:00Z",
      "effectiveTo": null,
      "observedAt": "2025-12-15T09:00:00Z",
      "availableAt": "2025-12-15T10:00:00Z",
      "source": {
        "sourceId": "SYN-CHARTER-1",
        "sourceType": "synthetic_charter",
        "documentDate": "2025-12-15",
        "locator": "Article IV.2"
      },
      "terms": {
        "classCode": "P"
      },
      "unsupportedTerms": []
    }
  ],
  "diagnostics": {
    "selectedRevisionByAssertion": {
      "R-CLASS-FOUNDER": 1,
      "R-CLASS-PREF": 1,
      "R-CLASS-PUBLIC": 1,
      "R-CONVERT-FOUNDER": 1,
      "R-DIV-PREF": 1,
      "R-ECON-FOUNDER": 1,
      "R-ECON-PUBLIC": 1,
      "R-FUNGIBLE-LINES": 1,
      "R-ISSUE-COMMON": 1,
      "R-ISSUE-PREF": 1,
      "R-LINE-EU": 1,
      "R-LINE-US": 1,
      "R-LIST-EU": 1,
      "R-LIST-OLD": 1
    },
    "excludedFutureRevisionCount": 1,
    "cancelledAssertionIds": ["R-LIST-OLD"],
    "conflicts": [],
    "unsupportedTerms": []
  }
}

Diagrams

Calculation flow

Bitemporal relationship resolution

flowchart TD
    A[Typed entities and relationship revisions] --> B{Contract valid?}
    B -->|No| X[Reject input]
    B -->|Yes| C[Group by stable assertion ID]
    C --> D[Keep revisions available by knownAt]
    D --> E[Select highest available revision]
    E --> F{Cancelled?}
    F -->|Yes| G[Record cancellation]
    F -->|No| H{Interval contains validAt?}
    H -->|No| I[Exclude from resolved graph]
    H -->|Yes| J[Add typed edge with source and terms]
    J --> K{Conflicts or unsupported terms?}
    K -->|Conflict| L[Resolver result is CONFLICT]
    K -->|Unsupported| M[Resolver result is INCOMPLETE]
    K -->|No| N[Resolver result is RESOLVED]
    N --> O[Compare explicit unit-compatible rights]
    O --> P[Return graph and diagnostics]

Assertion and resolution lifecycle

stateDiagram-v2
    [*] --> Observed
    Observed --> Available: source enters system
    Available --> Effective: valid interval contains validAt
    Available --> Future: effectiveFrom after validAt
    Available --> Expired: effectiveTo at or before validAt
    Available --> Cancelled: latest available revision cancels assertion
    Effective --> Resolved: terms supported and consistent
    Effective --> Incomplete: unsupported contract term
    Effective --> Conflict: incompatible active assertions
    Future --> [*]
    Expired --> [*]
    Cancelled --> [*]
    Resolved --> [*]
    Incomplete --> [*]
    Conflict --> [*]

How it works

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References

Alphabet Inc. 2025 Annual Report on Form 10-K — Alphabet Inc.; filed with the U.S. Securities and Exchange Commission
Financial Instrument Global Identifier Specification, version 1.2 — Object Management Group
ISO 6166:2021, Financial services — International securities identification number — International Organization for Standardization
Alphabet Inc. Amended and Restated Certificate of Incorporation — Alphabet Inc.
Evidence classification