Advance/Decline Volume Line

The hidden decision

A cumulative breadth line can rise for several different reasons; the audit trail must show exactly which daily volume increments built it.

Advance/Decline Volume Line answers one bounded question: how has the running balance of volume in advancing versus declining issues evolved from a declared seed? Its value is not a prediction. Its value is an auditable state whose inputs, time, units, and failure conditions are visible.

By the end, you will be able to calculate the method, reproduce its synthetic case, inspect its implementation trace, and decide when the output must be withheld.

Build the mental model

Subtract declining from advancing volume each session, then add that signed increment to an explicitly named seed in chronological order.

The volume line preserves share scale and path memory. Upside/Downside Volume Ratio discards both by normalizing one session's two volume legs.

The highlighted family card is a scope boundary. Count breadth, volume composition, recursive pressure, intraday sampling, and causal divergence can all produce lines, but their units and state memories are not interchangeable.

Freeze the contract before calculating

The selected formulation is:

Accumulate net advancing share volume from an explicit zero seed and retain the series identity. Publication invariant: A different start date changes the level but not the increments; missing or negative volume withholds the recursive tail.

The input table in the canonical README defines row fields and units. The parameter table distinguishes a sourced method from package choices such as equality behavior, seed, zero policy, sampling grid, normalized breadth scale, and event timestamp.

Advance-Decline Volume Line supports this bounded source role: net advancing volume is advancing minus declining volume, and the line recursively adds it to the previous value. It does not override the limitations recorded in REFERENCES.md, and it does not establish historical performance.

Reproduce the synthetic result

Every observation below is synthetic. The arithmetic is author-derived:

The four subtotals bridge the declared zero seed to 96,000,000 shares. Replacing the seed with 10,000,000 would shift every running level by 10,000,000 without changing any subtotal.

The expected output is:

{
  "status": "resolved",
  "value": 96000000
}

The SVG is not a decorative output card. It isolates the algorithm's actual learning obstacle: the final level hides the signed daily increments and the seed-dependent path. Notice the labels and dashed or branched boundaries; color is supplementary.

Calculation flow

The Mermaid diagram renders from visuals/mermaid/calculation-flow.md and follows this pseudocode:

validate a nonempty ordered volume-breadth tail
level = declared seed
for each session:
    net = advancing_volume - declining_volume
    level = level + net
    append net and level to trace
return final level and full trace

Validation comes first so bad evidence cannot mutate later state. That rule is especially important for recursive lines, timestamp grids, arming clocks, and right-side pivot confirmation.

Read the implementation

Python and TypeScript both:

1. validate finite inputs and the topic's identity/clock rules;
2. compute the named intermediate values;
3. preserve the trace needed to audit the result; and
4. return a numeric value or typed event only when the publication boundary passes.

They share datasets/canonical-fixture.json, including expected output and parameters. The code avoids provider SDKs and hidden network calls so the teaching arithmetic is fully inspectable.

Use the guided lab

Open visuals/animated/playground.html. Its objective is to step through positive and negative net volume, then change seed and missing-tail scenarios.

The initial screen is the completed canonical state. Back and Step reveal one observation at a time; Play uses the same transition function; Pause stops it; Reset restores the scenario and parameter. Comparison isolates a nearby outcome, while Failure / boundary demonstrates a reason code rather than a persuasive fake value. Reduced-motion Play advances one deterministic step without starting a timer.

The diagnostic panel and audit table should be read together. A smooth chart alone cannot prove denominator topology, chronological completeness, sampling continuity, or causal confirmation.

Operational interpretation

Audit the increment separately from the cumulative level so corrections and seed changes can be traced to the exact affected tail.

Do not misuse it: Do not compare absolute levels from different seed dates as though they shared one origin, and never skip a missing recursive member.

Passing the implementation checks proves definition fidelity. It does not prove reversal prediction, causal market explanation, trading profitability, transferability to another universe, or performance after costs.

Edge cases worth testing

• A different seed shifts every level by a constant but leaves each net-volume increment unchanged.
• A missing or unready session invalidates that point and the later recursive tail.
• Duplicate or decreasing session dates are invalid even if the arithmetic sum is unchanged.
• A provider correction requires replay from the corrected session, not a one-point patch.

Provider corrections require recomputing the affected tail or event set. A corrected observation that becomes available later must not leak into an earlier point-in-time result.

Evidence and historical boundary

A named historical reconstruction remains deferred. Publication would require a licensed point-in-time universe, exact classification rules, synchronized observations, session and sampling policy, correction lineage, the selected calculation convention, a knowledge cutoff, and redistribution rights.

Using a famous chart without that bundle would make the story stronger and the evidence weaker. The labelled synthetic fixture is therefore the responsible public example.

Summary and handoff

You can now calculate ADVL_t = ADVL_{t-1} + (V^+_t - V^-_t), interpret shares, audit the method-specific boundary, and reproduce matching Python and TypeScript behavior. Review Net Advances for the immediate input concept. Continue with Upside/Downside Volume Ratio in the dependency path.