Permanent Security Identifier Mapping: Scoped, Effective-Dated Crosswalks

A price table arrives with ticker ALP. Which security does that row describe?

There is no safe answer until the key includes its assignment scheme, identity layer, venue context, business-validity time, and evidence cutoff. A ticker is not a company. A Legal Entity Identifier (LEI) is not a security. An International Securities Identification Number (ISIN) is generally not a venue listing. Even an internal “permanent” key is only durable if its owners never recycle it or silently move it to another entity.

This tutorial builds a crosswalk that makes those boundaries visible. It does not promise one magical universal identifier. It gives you an auditable answer—or an explicit unmapped or ambiguous state.

The useful outcome

At the end, you can resolve this question:

Given source key K, economic instant t, and knowledge cutoff k, which same-layer canonical entity was supported by the evidence available then?

That distinction matters in holdings, price history, filings, corporate actions, tax lots, indices, and backtests. A wrong identity join can fabricate a return, duplicate a position, attach a filing to the wrong issuer, or let a later correction leak into an earlier simulation.

The visual’s central lesson is simple: ALP alone is not a key. TICKER / ALP / XNAS / trading_line, with two timestamps, is a resolvable question.

“Permanent” needs a boundary

The catalog title uses “Permanent Security Identifier Mapping.” Keep the title as a learning signpost, but read it precisely:

• Permanent is not universal. An identifier’s persistence comes from its assignment authority and lifecycle rules.
• Security is one layer. Issuers, legal entities, listings, trading lines, venues, and symbols are distinct.
• Mapping is historical evidence. It can be revised or cancelled, and the correction itself has an availability time.

The package-owned canonical ID is intended to be stable within one declared layer. It is not evidence that two different instruments are economically continuous.

Build the identity ladder first

The most common symbology error is not a bad string. It is joining two correct strings that name different kinds of thing.

This is a relationship graph, not a chain of aliases.

Legal entity

A legal entity is an organization recognized in a legal jurisdiction. GLEIF’s official FAQ describes an LEI as a 20-character code linked to reference data for identifying legal entities in financial transactions. It does not identify every security that entity issues.

Issuer

Issuer is a role in an issuance. An obligor, guarantor, parent, depositor, trust, or fund sponsor may be related but not identical. This package keeps issuer as its own internal layer; it does not force an LEI-to-instrument shortcut.

Instrument or security

An instrument is a legal/economic set of rights. ISO 6166:2021 supplies the ISIN framework for financial and referential instruments. ANNA’s version 24 guidelines say the allocation generally identifies the financial instrument rather than the market where it trades. Corporate-action and fungibility rules determine whether an ISIN remains active, becomes inactive, or another code is assigned.

A nine-character CUSIP combines issuer, issue, and check-digit components according to CUSIP Global Services. The full identifier is issue/instrument-level; its first six characters having issuer meaning does not make the full identifier a legal-entity code.

Share class

A share class identifies one set of rights within an equity structure. Two classes may differ in votes, dividends, conversion, or transfer rights. A share class may have several listings.

Listing and trading line

A listing is an admission to a market. A trading line is a more specific tradable representation, potentially tied to venue, currency, session, settlement, or pricing source. FIGI 1.2 distinguishes a basic venue-context identifier, a composite identifier, and a share-class identifier. The same specification says a ticker need not be unique to one identifier.

Venue and quote symbol

ISO 10383 defines Market Identifier Codes for venues and reporting facilities. A quote symbol is assigned in a market context and can change. FINRA’s corporate-action guidance includes trading-symbol and name changes. Therefore this package requires venueMic for every TICKER source.

Match schemes to layers

The teaching adapter enforces this matrix:

This matrix is intentionally conservative. If a production provider defines a different level, build a named adapter from its current specification. Do not weaken the model to make mismatched data join.

Two clocks, not one date

A mapping assertion has a business-validity interval and an evidence-availability timestamp.

• validAt asks when the mapping applies.
• knowledgeAt asks which revision the system could have known.

Suppose revision 1 says ALP / XNAS maps to line Alpha. A correction published on June 25 says it should have mapped to line Beta. A June 20 historical replay must still select revision 1, even when today’s database already contains revision 2.

For assertion a, select the latest revision available at cutoff k:

Then apply the selected revision at validity time t only when it is active and:

A null validTo means open-ended. The interval is half-open so two consecutive assignments can meet at one exact boundary without both matching.

Three valid outcomes

Let C(t,k) be the distinct canonical targets supported by known, active, source-matching assertions at those two clocks.

Those states are not error synonyms:

• unmapped means the evidence has no applicable assertion. Do not substitute the raw symbol.
• resolved means every applicable assertion supports one target.
• ambiguous means known assertions support different targets. Do not let sort order decide.

Malformed timestamps, invalid check-digit status, reversed intervals, cross-layer targets, or broken revision order are contract errors and raise immediately.

The complete assertion record

Every revision carries:

• the source scheme, value, entity level, and venue context;
• a same-layer canonical target;
• [validFrom, validTo);
• observedAt and availableAt;
• active or cancelled status;
• authoritative, corroborated, or inferred confidence;
• check-digit status;
• assignment authority and source-document ID.

Confidence is evidence classification, not a probability. An authoritative source does not get permission to cross identity layers. An inferred mapping does not get to defeat a conflicting candidate.

Check digits do less than many systems assume

ANNA’s guidelines describe an ISIN as 12 characters with a terminal check digit. CGS describes a CUSIP’s final character as a mathematical check of the previous eight. But a passing digit only supports syntactic integrity. It does not prove:

• the assignment exists;
• the assignment authority issued it;
• the descriptive record is current;
• it belongs to this entity;
• your license permits redistribution.

The implementation therefore consumes checkDigitStatus from a scheme-specific ingestion adapter. It does not compute every scheme’s checksum. invalid rejects the batch, while not_verified remains visible as a limitation.

A worked synthetic replay

The fixture asks:

source       = TICKER / ALP / trading_line / XNAS
validAt      = 2024-06-15T14:30:00Z
knowledgeAt  = 2024-06-20T12:00:00Z

Four facts matter:

1. SYN-MAP-001 revision 1 supports SYN-LINE-ALPHA-XNAS-USD and was available in December.
2. Revision 2 corrects the target to Beta but is unavailable until June 25.
3. A Gamma assignment is already known but begins July 1.
4. ALP / XLON is a different source key.

The June 20 replay resolves Alpha. Moving only knowledgeAt beyond June 25 resolves Beta for the same economic instant. Moving validAt to the exact July boundary resolves Gamma. Adding an independent assertion to a different target returns ambiguous.

No string, authority, or date in this example is a real mapping.

Implement the resolver

The core steps in both languages are:

validate query and every assertion revision
group revisions by assertionId
select latest revision available by knowledgeAt
match scheme + value + entity level + venue
apply active status and half-open validity at validAt
collect distinct canonical targets
return unmapped, resolved, or ambiguous with evidence

The Python and TypeScript implementations consume the same JSON fixture. They also agree that public scheme values are uppercased by this teaching adapter while INTERNAL values remain case-sensitive.

Open the guided identifier lab to step through the two clocks. Reset always returns to the canonical June 20 replay; Step advances exactly one evidence decision.

Test the failure modes, not just the happy join

Each language has 20 tests covering:

• exact fixture parity and no input mutation;
• half-open validity boundary;
• future correction hidden until available;
• same ticker on different venues;
• explicit unmapped and ambiguous results;
• same-target corroboration;
• cancellation;
• case-sensitive internal keys;
• invalid dates, intervals, revisions, checks, source context, and cross-layer targets;
• rejection of LEI as an instrument identifier.

Passing these tests proves the declared package rules. It does not prove completeness against a real provider.

Lifecycle rules belong to the source scheme

“Permanent” still requires lifecycle data.

• ANNA says ISINs should not be reused, while its corporate-action tables determine when codes remain, become inactive, or change.
• GLEIF’s LEI data model distinguishes issued, duplicate, lapsed, retired, annulled, and cancelled records and can identify successors.
• The MIC register supports creation, modification, and deactivation.
• Trading symbols can change with corporate actions.

Do not overwrite an old crosswalk because the source calls its identifier persistent. Keep validity, availability, status, and revision history. A merger or share-class conversion should add predecessor/successor relationships, not silently repoint an old canonical ID.

Where implementations fail

Watch for these production traps:

• joining ticker without venue, currency, or time;
• using LEI as if it named the issued security;
• using an ISIN as if it named one market listing;
• confusing CUSIP’s issuer prefix with the full issue identifier;
• treating a share-class FIGI as a venue-specific line;
• choosing the “highest confidence” target when assertions conflict;
• applying today’s correction inside yesterday’s backtest;
• treating delisting as instrument termination;
• treating a valid checksum as proof of assignment;
• lowercasing or uppercasing an opaque case-sensitive vendor key;
• publishing licensed symbology in an open fixture.

Evidence limitation

This article intentionally contains no named real-company crosswalk. A credible historical example would need authoritative evidence for every identifier, identity layer, venue context, validity boundary, publication/availability time, revision, and redistribution right. The public sources establish scheme behavior, but they do not provide one complete, freely redistributable mapping record for this package’s full contract. Synthetic data is more honest than filling those gaps with assumptions.

Summary

A reliable security master does not ask which ID is “most permanent.” It asks which authority names which layer, in what context, during which interval, and according to what evidence available at the time.

Keep the two clocks. Keep the layers separate. Preserve ambiguity instead of guessing. Then continue with Ticker-Change Chain Resolution, where successive symbol assignments become an auditable history rather than an overwrite.

Asset map

Versions, access dates, source roles, and limitations are recorded in ../REFERENCES.md.