Portfolio weight calculation

1 · Principles check

Verify this design respects every principle in v0.1.0. Any violation requires either a principles amendment or a deliberate exception logged below.

These are the load-bearing principles this slice turns on. The full P-1…P-20 register applies unchanged; platform-wide conformance is tracked in the umbrella design (001).

2 · Technical context

Language(s)

Java 21 (Temurin 21.0.9).

Frameworks

Quarkus 3.37.3, Maven. Extensions: quarkus-rest, quarkus-rest-jackson, quarkus-arc, quarkus-micrometer-registry-prometheus, quarkus-smallrye-openapi; test quarkus-junit5, rest-assured.

Architecture

Vertical-slice module io.spectastic.portfolio.weights — a derived read view over the event-sourced position snapshot (fold TradeEvent + PriceTick) owned by 003; this slice owns weights only.

Storage

None of its own. Reads the in-memory position snapshot from 003 at a ledger sequence; the TradeLedger log is owned upstream.

Testing

JUnit5 unit tests plus one @QuarkusTest (rest-assured over /q/openapi); jacoco.

Coverage

Diff-aware: a patch target on changed lines, and a change never lowers coverage of what it touches. No universal project percentage.

Perf targets

Reweight p99 < 500 µs full-book at N=5000 (SLO-reweight); |Σweights − 1| ≤ 1e-9 on every gross recompute (SLO-normalization); freshness p99 < 2 ms from originating tick (SLO-freshness).

Constraints

Exact integer fixed-point on the money path (PRICE_SCALE=10_000, whole-long quantities). double appears in exactly one place — the final display ratio mtm/denominator; the market values it divides are exact integers. Ship dark: portfolio.analytics.enabled default false.

3 · Grounding & evidence

Every design-bearing fact this design rests on, and how it was confirmed — read this before the approach: it separates what the design knows from what it assumes (per REQ-LIFECYCLE-006). Status is verified (opened the source this turn), spike (decidable only by a time-boxed investigation — run it, record the finding), or assumed (taken as true without verification). A must-tier decision may not rest on an assumed/unresolved-spike fact unless accepted as a <spec-risk> (see §8).

4 · Approach

The slice is a single derived view. On read it folds the current 003 position snapshot into a WeightBook: it accumulates the denominator under the selected WeightBasis (gross Σ|MV| or net ΣMV), then emits each instrument's weight as the exact integer market value divided by that denominator. The division is the sole floating-point step; every value feeding it stays an exact integer, and the gross invariant |Σweights − 1| ≤ 1e-9 is asserted on each recompute. Empty books yield empty weights (no divide-by-zero), and the net basis carries a near-zero-denominator guard that flags instability instead of emitting exploding weights.

For the spike we compute O(N) on read, which is trivially reconcilable against a full replay; the running-denominator incremental maintainer that lands the p99 SLO at N=5000 is noted and deferred (§9). Concentration rollups — top-N holdings and a Herfindahl index Σ weight² — derive from the same weights. A weight whose underlying price is older than the freshness bound is marked stale rather than silently served.

5 · Alternatives considered

Gross Σ|MV| is the default because it is the only basis that is well-defined with shorts and sums to one; net ΣMV is still offered (guarded near zero) for the desk that wants signed exposure. Orthogonally, on compute strategy we weighed O(N)-on-read against a running-denominator maintainer on the same latency-fit criterion: O(N)-on-read is chosen for the spike for its simplicity and reversibility (P-2), and the running-denominator maintainer is the noted optimization that lands p99 < 500 µs at N=5000, deferred within the slice (D-003, §9).

6 · Decisions

7 · Project structure

Only the new or changed paths, grouped by the vertical-slice boundary the §6 decisions draw.

src/
  main/java/io/spectastic/portfolio/weights/
    PortfolioWeights.java   # fold snapshot → WeightBook; ratios, guard, staleness, Herfindahl
    WeightBasis.java        # GROSS (default) | NET enum
  test/java/io/spectastic/portfolio/
    PortfolioWeightsTest.java   # sum-to-one, reweight-on-tick, shorts + guard + staleness

8 · Risks & mitigations

9 · Complexity tracking

Anywhere this design introduces complexity not strictly required by the spec, justify it here. A reviewer should be able to point at any non-trivial choice and find its rationale in this section.

10 · Open questions

11 · Change log