---
name: piker-fsp-expert
description: Piker financial signal processing expertise. Apply when changing or debugging FSP definitions, Cascade execution, derived shared-memory arrays, history/realtime handoff, backfill synchronization, FSP graph composition, online financial algorithms, or FSP chart lifecycle and scaling.
---

# Piker FSP Expertise

Treat financial signal processing as causal, revision-aware processing of
event-time market data, not as generic batch array manipulation.

## Start Here

1. Identify the source `Flume`, timeframe, event clock, and writer actor.
2. State whether the operation is historical bootstrap, backfill revision,
   current-sample mutation, or sample-step append.
3. Record source and destination absolute SHM bounds before reasoning from
   lengths or `ShmArray.index`.
4. Separate compute, SHM publication, IPC wakeup, and graphics costs before
   optimizing.
5. Preserve causality, warm-up behavior, missing-data semantics, and output
   schema in every implementation and test.

Read [architecture.md](architecture.md) before modifying runtime code. Read
[signal-processing.md](signal-processing.md) before adding an algorithm. Use
[roadmap-and-research.md](roadmap-and-research.md) for design and dependency
work, and [test-map.md](test-map.md) for verification.

## Core Contracts

- `piker.data` owns provider ingestion, source `Flume`s, history publication,
  quote fan-out, OHLC mutation, and `samplerd` step events.
- `piker.fsp` owns operator declarations, historical computation, realtime
  state updates, and destination SHM publication.
- `piker.ui._fsp.FspAdmin` currently owns FSP worker selection, destination
  allocation, cascade lifetime, and chart attachment.
- One logical writer owns each destination FSP array.
- Output event time and absolute indices derive from the source series, not
  task scheduling or quote arrival order.
- A source prepend changes historical provenance even when the current sample
  index is unchanged. Recompute or patch the affected destination range.
- One-step destination lag is normal between source sampling and destination
  append. A destination lead or unexplained bound shift is not.
- Backfill notifications are source and timeframe specific even though the
  current sampler transport broadcasts them globally.
- Only graphics backed by a rebuilt destination should refresh. Never use an
  FSP update as an unconditional whole-chart redraw request.

## Editing Workflow

1. Trace the operator from `@fsp` declaration through `cascade()`,
   `connect_streams()`, destination SHM, `FspAdmin`, and every consuming
   `Viz`.
2. Write an event-order table covering source writes, bound publication,
   notifications, cancellation, recomputation, and destination publication.
3. Add deterministic tests for history and realtime phases independently.
4. Add a controlled interleaving test for every race fix.
5. Profile representative visible ranges and feed rates before adding a
   dependency or native boundary.

## Companion Skills

- Use `piker-conc-expert` for Tractor contexts, actor topology, cancellation,
  service ownership, and cross-actor state.
- Use `timeseries-optimization` for NumPy/Polars lookup and vectorization.
- Use `piker-profiling` for distributed performance measurements.
- Use `pyqtgraph-optimization` for renderer and graphics batching work.
- Use `piker-clearing-expert` when a derived signal reaches EMS or accounting.

## Do Not

- Do not hide a historical mismatch merely to stop a resync log.
- Do not infer a complete synchronization state from array length alone.
- Do not run Python loops over historical numeric arrays without evidence.
- Do not apply regular-grid DSP blindly to irregular tick arrival times.
- Do not introduce an external stream runtime that duplicates Tractor before
  measuring an isolated protocol or kernel prototype.
- Do not route strategy signals directly around EMS order-state, risk, or
  accounting contracts.