# Base-Date/Base-Value Initialization

        **Catalog ID:** `D03-F01-A01`  
        **Domain:** Index and Benchmark Engineering  
        **Family:** Index Initialization and Continuity  
        **Difficulty:** 2/5  
        **Status:** Video-ready

        ## Executive summary

        Base-Date/Base-Value Initialization lets a benchmark engineer anchor a transparent index series to a declared base date and level. The package implements one transparent educational convention with explicit inputs, timing, diagnostics, and failure behavior. It does not reproduce a proprietary provider index or guarantee investability.

        ## Problem and financial relevance

        An index level is the output of a dated methodology, not a raw market fact. A small mistake in the divisor, free-float factor, tax assumption, FX quote, rebalance weight, or eligibility timestamp can create a false return that propagates into products, performance reports, and research. This topic makes the decision rule inspectable from input record to published output.

        ## Learning objectives

        After completing this topic, a reader can:

        - explain the economic purpose of Base-Date/Base-Value Initialization;
        - calculate its canonical example and audit every intermediate state;
        - implement the rule in Python and TypeScript from a shared fixture;
        - distinguish sourced provider policy from this package's implementation choices;
        - detect the central failure condition: freeze the base universe, prices, FX rates, and index shares at one timestamp.

        ## Prerequisites

        Understand finite numeric data, returns, weights that sum to one, effective dates, and point-in-time constituent records. **Historical Constituent Reconstruction**, **Corporate-Action Divisor Bridge**, and **Point-in-Time Availability Guard** provide the upstream security-master and timing foundations.

        ## Scope and variants

        This package teaches the named calculation at one reproducible level. Production benchmarks additionally require a complete rulebook covering calendars, pricing sources, corporate actions, review schedules, corrections, governance, licensing, and disruption handling. Provider-specific conventions are labeled as such rather than treated as universal mathematics.

        ## Input data contract

        - Numeric values must be finite and use the units declared in the shared fixture.
        - Weights, factors, tax rates, participation rates, and caps use decimal fractions, not percentages.
        - Prices, shares, FX rates, constituent membership, and divisor state share one effective timestamp.
        - FX quotes declare direction; return variants declare dividend and tax treatment.
        - Cross-sectional inputs are point-in-time snapshots; time-series inputs are causally ordered.
        - Missing required inputs, invalid constraints, and ambiguous states are rejected.
        - All distributed data are deterministic synthetic teaching fixtures.

        The exact canonical input is in [`tests/shared_fixture.json`](tests/shared_fixture.json). The extended dataset in [`datasets/synthetic-series.csv`](datasets/synthetic-series.csv) contains enough observations or entities to reveal drift, constraints, and failure boundaries.

        ## Output contract

        The reference implementation returns JSON-compatible values rounded to six decimals at the public boundary. It never mutates input. Weight outputs sum to one within numerical tolerance; index levels remain positive; constraint algorithms expose iteration counts or rejection.

        ## Mathematical formulation

        $$
        D_0 = M_0 / I_0, where M_0 is the eligible basket market value
        $$

        Symbols inherit their units from the fixture: $I$ is an index level, $D$ a divisor, $M$ a methodology-defined numerator, $P$ price, $Q$ index shares, $F$ float or adjustment factor, $X$ FX conversion, $w$ weight, and $r$ return. Topic-specific symbols are named in the fixture and worked example. The formula is followed by implementation diagnostics rather than being treated as sufficient on its own.

        ## Algorithm

        1. Freeze the point-in-time inputs and methodology version.
        2. Validate dimensions, finiteness, units, bounds, and feasibility.
        3. Calculate `base_init` without using future observations.
        4. Recompute invariants: continuity, positive level, weight sum, or constraint satisfaction.
        5. Emit the result with diagnostics needed to reproduce the decision.
        6. Reject the calculation when the declared contract cannot be satisfied.

        ## Canonical worked example

        The shared fixture produces:

        ```json
        {
  "marketValue": 119200,
  "divisor": 119.2,
  "indexLevel": 1000
}
        ```

        Python and TypeScript must return this exact public result. The light guided lab extends the fixture with canonical, boundary, and rejection scenarios and begins in an informative pre-populated state.

        ## Implementation guide

        - Python: [`implementations/python/base_date_base_value_initialization.py`](implementations/python/base_date_base_value_initialization.py)
        - TypeScript: [`implementations/typescript/base_date_base_value_initialization.ts`](implementations/typescript/base_date_base_value_initialization.ts)
        - Shared engine contract: [`../../shared/python/index_engine.py`](../../shared/python/index_engine.py)
        - Pseudocode: [`examples/PSEUDOCODE.md`](examples/PSEUDOCODE.md)
        - Shared fixture: [`tests/shared_fixture.json`](tests/shared_fixture.json)

        The topic files expose one small `calculate` function while the domain-level engines centralize validated arithmetic shared across all D03 packages. This avoids forty drifting implementations of divisor, rounding, matrix, and capping primitives.

        ## Testing and validation

        Tests cover the canonical fixture, input immutability, invalid input, JSON finiteness, and Python/TypeScript parity. Domain validation additionally checks catalog parity, package completeness, dataset density, SVG bounds, Mermaid rendering, lab controls, reduced motion, responsive layouts, article embeds, and production builds.

        Definition-level tests prove that the implementation matches the declared convention. They do not prove that the methodology has desirable investment performance, low tracking error, legal benchmark status, or provider parity.

        ## Edge cases and limitations

        - stale prices, FX rates, shares, factors, or divisor state;
        - infeasible caps, singular covariance, or non-convergent iteration;
        - zero denominators, non-positive levels, and extreme returns;
        - missing dividends, tax assumptions, financing rates, or forward rolls;
        - review data revised after the selection cutoff;
        - rounding drift across many constituents or sessions;
        - exceptional market closures and provider discretion.

        The central guard is to freeze the base universe, prices, FX rates, and index shares at one timestamp. A plausible chart is not evidence that the operational methodology was followed.

        ## Evidence and limitations

        The [S&P DJI Index Mathematics Methodology](https://www.spglobal.com/spdji/en/documents/methodologies/methodology-index-math.pdf) defines the divisor as the continuity mechanism; corporate-event treatment must then follow the applicable provider policy. Full source roles, versions, access dates, and limitations are recorded in [`REFERENCES.md`](REFERENCES.md). All datasets are synthetic. This is educational material, not investment, legal, tax, or benchmark-administration advice.

        ## Visual explanations

        - [`visuals/mermaid/calculation-flow.md`](visuals/mermaid/calculation-flow.md) maps inputs to audited output.
        - [`visuals/mermaid/methodology-state.md`](visuals/mermaid/methodology-state.md) shows the decision lifecycle.
        - [`visuals/static/article-hero.svg`](visuals/static/article-hero.svg) separates methodology state from market movement.
        - [`visuals/static/worked-example.svg`](visuals/static/worked-example.svg) annotates the canonical numbers.
        - [`visuals/static/failure-guard.svg`](visuals/static/failure-guard.svg) explains the rejection boundary.
        - [`visuals/animated/playground.html`](visuals/animated/playground.html) is the guided light lab.

        ## Publication derivatives

        - [Publication-ready article](article/ARTICLE.md)
        - [Scene-based video script](video/VIDEO-SCRIPT.md)
        - [Visual asset and validation plan](visuals/VISUAL-PLAN.md)

        ## Related catalog topics

        - Upstream: Historical Constituent Reconstruction and Corporate-Action Divisor Bridge
        - Current family: Index Initialization and Continuity
        - Continue with: **Index Divisor Initialization**

        ## References

        Primary and authoritative sources are documented in [`REFERENCES.md`](REFERENCES.md).