piker/.agents/skills/piker-fsp-expert/SKILL.md

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 before modifying runtime code. Read signal-processing.md before adding an algorithm. Use roadmap-and-research.md for design and dependency work, and test-map.md for verification.

Core Contracts

• piker.data owns provider ingestion, source Flumes, 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.