@stockheartbeat/core

Shared tick to bucket engine, Phase 1 feature engineering, source adapters and ETL CLI for the StockHeartbeat ecosystem.

core is the single source of truth for the dollar-notional bucket definition used by:

• the live micro server (live WebSocket UI),
• @stockheartbeat/mcp (agent-facing MCP server),
• offline ETL pipelines on local machines (M2 Mac, etc.),
• future on-chain attestation tooling.

If two systems disagree about what a bucket means, they disagree about the truth. This package exists so they cannot.

Install

npm install @stockheartbeat/core

Published on npm: https://www.npmjs.com/package/@stockheartbeat/core

If your default registry is a mirror that does not mirror scoped packages, add to the consuming project:

# .npmrc
@stockheartbeat:registry=https://registry.npmjs.org/

Node >= 20. Pure ESM. Runtime dependency: zod ^4.

Public API

import {
  // schema (Zod)
  TradeSchema, BucketSchema, WindowSummarySchema, ManifestSchema,
  SCHEMA_VERSION, FEATURE_SET,

  // engine
  createBucket, pushTrade, finalizeBucket, flushBucket,
  replayTrades, replayTradesAsync,

  // features
  logReturn, rangeAbs, rangePct, direction, intensity, imbalance,
  summarizeWindow,

  // adapters
  parseBinanceVisionCsv, parseBinanceVisionTradeLine,
  parseAlpacaTrades, parseAlpacaTradeRow,
  fromMicroWireTrade, fromMicroWireTrades,
} from "@stockheartbeat/core";

Sub-path imports also work and tree-shake better:

import { BucketSchema } from "@stockheartbeat/core/schema";
import { replayTrades } from "@stockheartbeat/core/engine";
import { parseBinanceVisionCsv } from "@stockheartbeat/core/adapters";
import { resolveChallenge } from "@stockheartbeat/core/benchmark";

Bucket engine

import { replayTrades } from "@stockheartbeat/core/engine";

const buckets = replayTrades(trades, {
  symbol: "BTCUSDT",
  threshold_usd: 1_000_000,
  stream: "standard",
});

Trades must be normalized (TradeSchema) and in chronological order. Out-of-order trades break VWAP / OHLC monotonicity by design - use the adapter to normalize first.

Benchmark protocol (@stockheartbeat/core/benchmark)

If you build or employ a market-judgment agent, this subpath is the deterministic core of the StockHeartbeat Benchmark: a neutral, verifiable track record. The hosted API + @stockheartbeat/mcp tools are how your agent answers; this package is how anyone recomputes the score - so the leaderboard is trustless, not a screenshot.

import {
  poseChallenges, resolveChallenge,        // standardized questions + deterministic outcomes
  brierScore, logScore, skillScore,        // proper scoring rules + skill vs baseline
  climatologyProbs, persistenceProbs,      // naive baselines to beat
  rulesetHash, canonicalHash,              // content-addressed, versioned rules
  merkleLeaf, buildMerkleTree, verifyMerkleProof, // O(1) anchor + inclusion proofs
  outcomeSpaceFor,                         // fixed outcome space per challenge type
} from "@stockheartbeat/core/benchmark";

Challenge types include buyer-relevant, tradeable decisions: direction_next (up/down) and vol_regime_next (high/low), alongside regime_next and hbpm_below_median_next.

Independently verify any published record from its frozen bundle:

import { resolveChallenge, merkleLeaf, buildMerkleTree } from "@stockheartbeat/core/benchmark";

const root = buildMerkleTree(frozen.resolve_buckets.map(merkleLeaf)).root;
const out = resolveChallenge({
  challenge: frozen.challenge,
  resolveBuckets: frozen.resolve_buckets,
  lookbackBuckets: frozen.lookback_buckets,
});
const verified = root === frozen.data_root && out.outcome === frozen.resolved_outcome;

Everything here is pure and dependency-free (only zod + node crypto): same frozen inputs => identical challenges, outcomes, scores and Merkle roots, now or years later.

CLI: heartbeat-etl

After npm install, the bin is available locally:

npx heartbeat-etl replay \
  --input ./BTCUSDT-trades-2026-04.csv \
  --feed binance-vision \
  --symbol BTCUSDT \
  --threshold 1000000 \
  --stream standard \
  --out ./out

Supported feeds:

• binance-vision - Binance public Spot trades CSV (data.binance.vision)
• alpaca-trades-jsonl - One Alpaca trades row per line
• micro-wire-jsonl - Legacy micro upstream frames per line

Outputs:

• out/buckets.jsonl - one canonical Bucket per line
• out/manifest.json - engine + schema versions, time range, source kind

The manifest is what makes cross-machine workflows safe: producers stamp versions, consumers refuse mismatched files.

Versioning

• engine_version follows semver of this package.
• SCHEMA_VERSION is an integer that bumps on any breaking BucketSchema change.
• FEATURE_SET is a free-form label of the feature engineering vintage (currently phase1).

Manifests carry all three; consumers should refuse to ingest a file that disagrees with their compiled-in versions.

License

Apache-2.0. See LICENSE and NOTICE.