@pear-protocol/utils 0.0.23 → 0.2.0

package/dist/math/decimal.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Centralized signed-decimal helpers. Everything that parses, formats, signs,
+ * compares, or does arithmetic on decimal strings/BigNumbers lives here — call
+ * sites never construct `new BigNumber(...)` directly.
+ */
+import type { Side, SignedDecimalString } from '@pear-protocol/types';
+import BigNumber from 'bignumber.js';
+/**
+ * Either representation of a decimal value; helpers parse internally.
+ * Deliberately no `number` — floats stay out of decimal math.
+ */
+export type DecimalLike = BigNumber | string;
+/** Central constructor: parse a decimal string, or pass a BigNumber through. */
+export declare function parse(value: DecimalLike): BigNumber;
+/** Plain decimal string, never exponent notation (BigNumber `toFixed`). */
+export declare function toDecimalString(value: DecimalLike): string;
+/** Canonical signed-string wire format: `+…` / `-…`; zero is always `+0`. */
+export declare function signed(value: DecimalLike): SignedDecimalString;
+/** a + b */
+export declare function add(a: DecimalLike, b: DecimalLike): BigNumber;
+/** a - b */
+export declare function subtract(a: DecimalLike, b: DecimalLike): BigNumber;
+/** a × b */
+export declare function multiply(a: DecimalLike, b: DecimalLike): BigNumber;
+/** a ÷ b */
+export declare function divide(a: DecimalLike, b: DecimalLike): BigNumber;
+/** -a */
+export declare function negate(value: DecimalLike): BigNumber;
+/** |a| */
+export declare function abs(value: DecimalLike): BigNumber;
+/** The smaller of a and b. */
+export declare function min(a: DecimalLike, b: DecimalLike): BigNumber;
+/** True when the value equals zero. */
+export declare function isZero(value: DecimalLike): boolean;
+/**
+ * Sign-based like BigNumber: `+0` counts as positive. Call sites where zero
+ * matters must guard with {@link isZero} first.
+ */
+export declare function isPositive(value: DecimalLike): boolean;
+/** Sign-based like BigNumber: `-0` counts as negative (see {@link isPositive}). */
+export declare function isNegative(value: DecimalLike): boolean;
+/** True for a real, finite decimal (rejects NaN and ±Infinity). */
+export declare function isFiniteDecimal(value: DecimalLike): boolean;
+/** a == b (numeric equality, not string equality). */
+export declare function isEqualTo(a: DecimalLike, b: DecimalLike): boolean;
+/** a > b */
+export declare function isGreaterThan(a: DecimalLike, b: DecimalLike): boolean;
+/** a >= b */
+export declare function isGreaterThanOrEqual(a: DecimalLike, b: DecimalLike): boolean;
+/** a < b */
+export declare function isLessThan(a: DecimalLike, b: DecimalLike): boolean;
+/** a <= b */
+export declare function isLessThanOrEqual(a: DecimalLike, b: DecimalLike): boolean;
+/** The numeric sign of a trade side: BUY is +1, SELL is -1. */
+export declare function sideSign(side: Side): 1 | -1;
+/** Sign a quantity by its side: BUY positive, SELL negative. */
+export declare function signedBySide(value: DecimalLike, side: Side): BigNumber;

package/dist/math/decimal.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/math/index.d.ts

@@ -22,3 +22,4 @@ export declare function sign(value: BigNumber): 1 | -1 | 0;
  */
 export declare function countDecimals(value: string): number;
 export declare function compareValue(track: 'PEAK' | 'TROUGH', value: BigNumber, threshold: number): boolean;
+export * from './decimal';

package/dist/position/compute.d.ts

@@ -19,4 +19,20 @@ export declare function computeUnrealizedPositionState(exposureMap: ExposureMap,
  * @returns The realized position state.
  */
 export declare function computeRealizedPositionState(fills: Fill[]): RealizedPositionState;
+/**
+ * Weighted-average entry (cost-basis) price per instrument in a position, derived purely from
+ * fills — no mark price needed. This is the authoritative source for a position's entry price;
+ * callers that already have it (e.g. from a position API response) should NOT re-derive it a
+ * second time by replaying fills themselves.
+ *
+ * Formula (per instrument): cost-basis average via computeEntryPriceForAsset.
+ */
+export declare function computePositionEntryPrices(exposureMap: ExposureMap, fills: Fill[]): Record<InstrumentId, string>;
+/**
+ * Unrealized position state derived from ALREADY-KNOWN entry prices (e.g. the entryPrices field
+ * on a position API response) instead of replaying the fills ledger. Prefer this over
+ * computeUnrealizedPositionState whenever the caller already has entry prices — it needs no
+ * fills fetch at all, only a live mark-price map.
+ */
+export declare function computeUnrealizedPositionStateFromEntryPrices(exposureMap: ExposureMap, entryPrices: Record<InstrumentId, string>, priceMap: PriceMap): UnrealizedPositionState;
 export {};

package/dist/position/compute.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/position/index.d.ts

@@ -1,2 +1,3 @@
 export * from './compute';
+export * from './key';
 export type { RealizedPositionState, UnrealizedPositionState } from './position.types';

package/dist/position/key.d.ts

@@ -0,0 +1,15 @@
+type PositionKeyInput = {
+    tradeAccountId: string;
+    symbols: string[];
+};
+/**
+ * Canonical deterministic position key, reused for both PEAR and EXTERNAL
+ * positions and on both the client (sync compute) and the server (apply step).
+ *
+ * sha256 over { tradeAccountId.toLowerCase(), symbols.sort() }. No connector,
+ * no side — same-asset positions therefore produce the SAME key, which is
+ * exactly what the active-position unique index relies on and what makes the
+ * apply UPSERT find-or-create the single correct target.
+ */
+export declare function generateDeterministicPositionKey(input: PositionKeyInput): string;
+export {};

package/dist/precise-price.d.ts

@@ -1,3 +1,8 @@
 import type { Connector, InstrumentPrecision, Side } from '@pear-protocol/types';
 import BigNumber from 'bignumber.js';
+/**
+ * Round a raw price to an exchange-valid string for the given connector,
+ * biased so the order stays marketable (BUY rounds down, SELL rounds up),
+ * optionally padded with slippage tolerance first.
+ */
 export declare function precisePrice(connector: Connector, raw: BigNumber.Value, precision: InstrumentPrecision, side?: Side, slippageToleranceBps?: number): string;

package/dist/precise-quantity.d.ts

@@ -1,3 +1,7 @@
 import type { Connector, InstrumentPrecision, Side } from '@pear-protocol/types';
 import BigNumber from 'bignumber.js';
+/**
+ * Round a raw quantity to an exchange-valid string for the given connector
+ * (BUY rounds down, SELL rounds up).
+ */
 export declare function preciseQuantity(connector: Connector, raw: BigNumber.Value, precision: InstrumentPrecision, side: Side): string;

package/dist/proxy.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Optional forward-proxy for outbound SDK HTTP calls.
+ *
+ * When enabled, every request is re-pointed at the proxy's origin with the original destination
+ * carried in the `X-Proxy-Target` header. The proxy restores method, path, query, body, and headers
+ * before forwarding upstream (see pear-proxy). Off by default — a transparent passthrough to the
+ * global `fetch`.
+ *
+ * Config is INJECTED by the caller via the SDK constructors (`configureProxy`), never read from the
+ * environment: the SDKs also run in the browser, where `process.env` does not exist.
+ *
+ * Fallback: the proxy is best-effort. If the proxied call fails for any reason other than a genuine
+ * 4xx response — a network/transport error, or a proxy-side 5xx such as the load-shed 503 or the
+ * request-timeout 504 — the request is retried once directly against the original target, un-proxied.
+ * A 4xx passes straight through, since that is the upstream's own answer and a direct retry would
+ * only repeat it.
+ */
+export type ProxyConfig = {
+    /** Master switch. When false (or the URL is missing), `proxyFetch` is a transparent passthrough. */
+    enabled: boolean;
+    /** Proxy base URL; only its origin (scheme + host + port) is used. */
+    url?: string;
+};
+/**
+ * Set (or clear) the forward-proxy used by every `proxyFetch` call. Called from the SDK
+ * constructors with the caller-supplied config. Passing a disabled/absent config turns it off.
+ */
+export declare function configureProxy(config: ProxyConfig | null | undefined): void;
+/**
+ * `fetch` for a string/URL request that routes through the configured proxy when enabled (with a
+ * direct-call fallback); otherwise calls the global `fetch` unchanged. All SDK call sites pass a
+ * URL + init, so a `Request`-object input is intentionally not supported.
+ */
+export declare function proxyFetch(input: string | URL, init?: RequestInit): Promise<Response>;

package/dist/proxy.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sync/applicables/basket.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Detecting baskets — grouping raw external fills into the orders they were
+ * placed as, each combined into per-symbol legs with FIFO queues for splitting
+ * across positions.
+ */
+import type { HttpTypes, Side } from '@pear-protocol/types';
+import type { FillPart } from './types';
+/**
+ * A detected order: its legs combined by symbol+side. Legs carry per-source FIFO
+ * queues, so {@link CombinedLeg.take} can split a single exchange fill across
+ * several positions.
+ */
+export declare class Basket {
+    readonly legs: CombinedLeg[];
+    private constructor();
+    /** Detect baskets from a fill stream, returned in ascending time order. */
+    static detect(fills: HttpTypes.UnknownExternalFill[]): Basket[];
+    /** Active long symbol set the matcher compares against open positions. */
+    get longs(): Set<string>;
+    /** Active short symbol set the matcher compares against open positions. */
+    get shorts(): Set<string>;
+}
+/**
+ * One combined symbol+side leg of a basket. Owns the per-source FIFO queue, so
+ * taking quantity from the leg (splitting fills across positions) is a method on
+ * its own state instead of an outside helper mutating a plain object.
+ */
+export declare class CombinedLeg {
+    readonly symbol: string;
+    readonly side: Side;
+    private _totalSize;
+    private readonly queue;
+    constructor(symbol: string, side: Side);
+    get totalSize(): BigNumber;
+    /** Append a fill to this leg's queue and grow the total size. */
+    addFill(fill: HttpTypes.UnknownExternalFill): void;
+    /**
+     * Take `qty` of fill slices from this leg (FIFO across source fills, consumes the queue).
+     * Returns the parts taken, which are consumed from the queue.
+     */
+    take(qty: BigNumber): FillPart[];
+}

package/dist/sync/applicables/basket.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sync/applicables/constants.d.ts

@@ -0,0 +1,19 @@
+import type { HttpTypes } from '@pear-protocol/types';
+import type { BasketRule } from './types';
+/**
+ * Float-precision dust floor. Exchange quantities are exact decimal strings and the
+ * whole matcher is BigNumber, so a real full close nets to exact zero. This floor only
+ * absorbs sub-1e-8 dust that a stray float (anywhere upstream) could leave behind —
+ * without it, that dust keeps a position "open", so a later reopen of the same pair
+ * merges in and every lifecycle collapses onto one position. NOT a per-instrument
+ * tolerance: a genuine partial close (>= 1e-8) stays open, as it should.
+ */
+export declare const DUST: BigNumber;
+export declare const MISSED_HISTORY_FILL_PREFIX = "opening-synthetic-";
+export declare const BASKET_RULES: BasketRule[];
+/**
+ * True when `cloid` is a Pear-originated cloid for the given connector.
+ * A missing or empty cloid is always false; connector-specific prefix rules
+ * are applied via the `PEAR_CLOID_CHECK` table.
+ */
+export declare function isPearCloid(connector: HttpTypes.Connector, cloid: string | null | undefined): boolean;

package/dist/sync/applicables/exposure.d.ts

@@ -0,0 +1,47 @@
+import type { Side, SignedDecimalString } from '@pear-protocol/types';
+import type { FillPart } from './types';
+/**
+ * Signed per-asset exposure of a position — the running `symbol -> quantity` book
+ * (BUY positive, SELL negative). Wraps the raw map so the signed-quantity math, the
+ * DUST rule, and the leg-set queries live in one place instead of scattered helpers.
+ *
+ * Mutable by design: the matcher mutates a working position's exposure in place while
+ * replaying fills. Use {@link clone} when a caller needs an independent copy.
+ */
+export declare class Exposure {
+    private readonly legs;
+    private constructor();
+    /** Create an exposure with no legs — the starting state for a new position. */
+    static empty(): Exposure;
+    /** Build from a wire `Record<symbol, quantity>` (existing DB position exposure). */
+    static fromRecord(record: Record<string, string>): Exposure;
+    /** Net signed exposure a set of fill parts contributes for `symbol` (BUY +, SELL −). */
+    static netFromParts(parts: FillPart[], symbol: string): BigNumber;
+    /** Return an independent copy of this exposure so mutations do not alias. */
+    clone(): Exposure;
+    /** Signed exposure for `symbol` (0 when absent). */
+    get(symbol: string): BigNumber;
+    /** Apply a signed `delta` to `symbol`, creating the leg if it does not exist. */
+    addDelta(symbol: string, delta: BigNumber): void;
+    /** Convert a side+quantity pair to a signed delta and forward to `addDelta`. */
+    addSigned(symbol: string, quantity: string, side: Side): void;
+    /** Active (non-zero) long and short leg sets. */
+    activeLegs(): {
+        longs: Set<string>;
+        shorts: Set<string>;
+    };
+    /** True once every leg sits within DUST of zero (effectively closed). */
+    isFlat(): boolean;
+    /** True when every leg is exactly zero (a fully CLOSED position). */
+    isAllZero(): boolean;
+    /**
+     * Snap every non-zero leg to exactly zero. Called once a position is flat so it
+     * reads CLOSED (all-zero exposure) and never lingers in the open list with stray
+     * dust that a later reopen of the same pair could merge into.
+     */
+    snapToZero(): void;
+    /** All symbols with a leg, including zeroed ones (a closed leg still carries cost basis). */
+    symbols(): string[];
+    /** Canonical signed-string view for the wire (`+0` for zero). */
+    toSigned(): Record<string, SignedDecimalString>;
+}

package/dist/sync/applicables/exposure.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sync/applicables/fills.d.ts

@@ -0,0 +1,16 @@
+import type { HttpTypes } from '@pear-protocol/types';
+import type { FillPart, MatchedPosition, PartId } from './types';
+/**
+ * A source fill may be split into multiple slices (different positions). Build a
+ * stable id per slice: unsplit slices keep the native id; split slices get a
+ * deterministic `-pN` suffix plus an `original` pointer to the source.
+ * Returns an accessor; every part of every given position has an id by construction.
+ */
+export declare function assignPartIds(positions: MatchedPosition[]): (part: FillPart) => PartId;
+/**
+ * Convert a matched fill slice into the wire-shape ApplicableFill the server persists.
+ * Three shapes emerge: a real external fill, a real Pear fill (cloid we minted), or a
+ * missed-history synthetic (external, priced to reconcile with the exchange entry).
+ * Fees are quantity-prorated when the source fill was split across positions.
+ */
+export declare function partToApplicableFill(part: FillPart, id: PartId, connector: HttpTypes.Connector): HttpTypes.ApplicableFill;

package/dist/sync/applicables/fills.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sync/applicables/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Turn a batch of external fills into `applicables` — fill baskets the server
+ * find-or-creates into positions.
+ *
+ * Each fill is processed against the currently open positions, oldest first:
+ *   1. close out an exact-match inverse position (same active legs),
+ *   2. else reduce any other positions partially holding that leg,
+ *   3. else merge the leftover into an open position already holding those legs, or open a new one.
+ * A fill can be split across several positions when it closes more than one.
+ *
+ * Once fills are assigned, one synthetic per asset covers any remaining gap to the
+ * exchange snapshot (the source of truth). Position exposure is NOT computed here —
+ * the server sums the assigned fills; the opening cost basis (initialExposureUSD) is
+ * derived per position from its own real fills and carried in `metadata`.
+ *
+ * Pipeline: snapshot → add missed-history fills → match → align with exchange → assemble.
+ * Diff outcomes: discover (new fill), gap (residual vs snapshot), gone (netted to zero)
+ */
+import type { HttpTypes } from '@pear-protocol/types';
+/**
+ * Build the `applicables` bucket: baskets of fills (real + synthetic) keyed by a
+ * deterministic positionKey, plus creation metadata. Positions are derived by
+ * replaying fills through dynamic matching (exact active-set match, cross-
+ * position close, subset-merge of leftover opens), so same-asset exposure
+ * consolidates instead of fragmenting per basket symbol-set.
+ */
+export declare function buildApplicables(args: {
+    tradeAccountId: string;
+    connector: HttpTypes.Connector;
+    orphanFills: HttpTypes.UnknownExternalFill[];
+    openPositions: HttpTypes.OpenPositionLite[];
+    entryBySymbol: Record<string, string>;
+    exchangePositions: HttpTypes.ExternalPosition[];
+}): HttpTypes.ApplicablePosition[];

package/dist/sync/applicables/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sync/applicables/matching.d.ts

@@ -0,0 +1,17 @@
+import type { HttpTypes } from '@pear-protocol/types';
+import type { PearHoldings } from './snapshot';
+import type { MatchedPosition } from './types';
+/**
+ * Replay external fills to decide which position each fill slice belongs to. Flow :
+ *   - findExactCloseTarget picks the open position whose ACTIVE legs mirror the
+ *     basket (dead legs ignored) — the basket closes that position first,
+ *   - applyCloses reduces holders (the mirrored target first, then any other),
+ *   - resolveLeftoverTarget subset-merges into a compatible position, else opens
+ *     new (same-shape ADDs consolidate here).
+ * The asset SET of a position never grows, so positionKey == key(opening symbols).
+ */
+export declare function matchPositions(args: {
+    tradeAccountId: string;
+    orphanFills: HttpTypes.UnknownExternalFill[];
+    pear: PearHoldings;
+}): MatchedPosition[];

package/dist/sync/applicables/matching.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sync/applicables/position.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Builds the final `ApplicablePosition` output — folds assigned synthetics into
+ * exposure, derives status/origin/metadata.
+ */
+import type { HttpTypes } from '@pear-protocol/types';
+import type { MatchedPosition, NeededSynthetic } from './types';
+/**
+ * Assemble the final ApplicablePosition records: resolve stable per-slice fill
+ * ids once across all positions, then build each applicable (dropping unchanged
+ * positions that produced no fills).
+ */
+export declare function assembleApplicables(args: {
+    positions: MatchedPosition[];
+    connector: HttpTypes.Connector;
+    synthByPosition: Map<MatchedPosition, NeededSynthetic[]>;
+    now: number;
+}): HttpTypes.ApplicablePosition[];

package/dist/sync/applicables/position.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sync/applicables/snapshot.d.ts

@@ -0,0 +1,41 @@
+import type { HttpTypes } from '@pear-protocol/types';
+/**
+ * The exchange position snapshot — the enforced source of truth for exposure. Wraps the
+ * per-symbol lookup so callers ask `snapshot.signedSize(symbol)` instead of threading a
+ * raw map plus a sign helper.
+ */
+export declare class ExchangeSnapshot {
+    private readonly bySymbol;
+    private constructor();
+    /** Index `positions` by symbol for O(1) lookup. */
+    static from(positions: HttpTypes.ExternalPosition[]): ExchangeSnapshot;
+    /** Raw exchange position for `symbol`, or `undefined` when the exchange holds nothing. */
+    get(symbol: string): HttpTypes.ExternalPosition | undefined;
+    /** Signed exchange exposure for `symbol` (0 when the exchange has no position). */
+    signedSize(symbol: string): BigNumber;
+    /** All symbols the exchange currently reports a position for. */
+    symbols(): string[];
+}
+/**
+ * What Pear's DB currently holds for one connector — the open positions, filtered
+ * once, plus the per-symbol views the synthetic steps need.
+ */
+export declare class PearHoldings {
+    private readonly filtered;
+    private constructor();
+    /** Filter `openPositions` to the given connector and wrap. */
+    static from(args: {
+        openPositions: HttpTypes.OpenPositionLite[];
+        connector: HttpTypes.Connector;
+    }): PearHoldings;
+    /** The open Pear positions for this connector. */
+    positions(): HttpTypes.OpenPositionLite[];
+    /** Sum existing open Pear exposure per symbol. */
+    totalBySymbol(): Map<string, BigNumber>;
+    /**
+     * Which open DB position holds each active asset — the fallback target for a
+     * synthetic when no matched position already carries that asset. First open
+     * position with a non-zero leg wins per symbol.
+     */
+    positionBySymbol(): Map<string, HttpTypes.OpenPositionLite>;
+}

package/dist/sync/applicables/synthetics.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Everything synthetic lives here — the missed-history fills added before matching,
+ * the per-asset check against the exchange afterwards, and the assignment of each
+ * needed synthetic to one position.
+ */
+import type { HttpTypes, Side } from '@pear-protocol/types';
+import type { ExchangeSnapshot, PearHoldings } from './snapshot';
+import type { MatchedPosition, NeededSynthetic } from './types';
+/** True when an external fill was minted by the missed-history pass (its id carries the prefix). */
+export declare function isMissedHistoryFill(fill: HttpTypes.UnknownExternalFill): boolean;
+/**
+ * The exchange only returns recent fills — anything older is invisible to us.
+ * This adds stand-in (synthetic) fills covering that missed history, so the
+ * matcher replays the correct running exposure from the start. Returns the
+ * complete fill list, oldest first.
+ */
+export declare function addFillsForMissedHistory(args: {
+    orphanFills: HttpTypes.UnknownExternalFill[];
+    pear: PearHoldings;
+    connector: HttpTypes.Connector;
+    entryBySymbol: Record<string, string>;
+    snapshot: ExchangeSnapshot;
+}): HttpTypes.UnknownExternalFill[];
+/**
+ * Compare what we now hold per asset with what the exchange says, and create one
+ * correcting synthetic per asset that is off — assigned to exactly one position
+ * (creating the position if none holds that asset). This is the safety net for
+ * residual drift, the only discovery path when no fills were fetched at all
+ * (e.g. first sync of an account whose fill history is beyond the fetch window),
+ * and the only close path for positions the exchange dropped without any fill
+ * activity this cycle. Returns the position list (extended with any created
+ * positions) plus the synthetics per position — the input array is never mutated.
+ */
+export declare function alignPositionsWithExchange(args: {
+    positions: MatchedPosition[];
+    pear: PearHoldings;
+    snapshot: ExchangeSnapshot;
+    tradeAccountId: string;
+}): {
+    positions: MatchedPosition[];
+    synthByPosition: Map<MatchedPosition, NeededSynthetic[]>;
+};
+/** Build the content-addressed synthetic fill for a position/asset/side triple. */
+export declare function buildSyntheticFill(args: {
+    positionKey: string;
+    connector: HttpTypes.Connector;
+    symbol: string;
+    side: Side;
+    quantity: string;
+    timestamp: number;
+    closedReason?: HttpTypes.PositionClosedReason;
+}): HttpTypes.ApplicableFill;

package/dist/sync/applicables/synthetics.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sync/applicables/types.d.ts

@@ -0,0 +1,77 @@
+import type { HttpTypes, Side } from '@pear-protocol/types';
+import type { CombinedLeg } from './basket';
+import type { Exposure } from './exposure';
+/**
+ * A basket-detection rule. Fills for which `matches` is true AND that produce the same
+ * `key` are grouped into one basket. Rules are tried in order; the first match wins. A
+ * fill matching no rule falls back to the default (its own exchangeFillId), so it never
+ * groups with anything else.
+ */
+export type BasketRule = {
+    matches: (fill: HttpTypes.UnknownExternalFill) => boolean;
+    key: (fill: HttpTypes.UnknownExternalFill) => string;
+};
+/**
+ * A slice of a source external fill assigned to one virtual position. A single
+ * external fill can be split across positions (e.g. a SELL that closes two open
+ * longs), so each slice tracks its source for fill-id and fee derivation.
+ */
+export type FillPart = {
+    source: HttpTypes.UnknownExternalFill;
+    quantity: string;
+};
+/**
+ * A working position the matcher builds while replaying fills.
+ * Mutable mid-replay — its `exposure` is updated in place as fills land.
+ */
+export type WorkingPosition = {
+    positionKey: string;
+    exposure: Exposure;
+    parts: FillPart[];
+    closed: boolean;
+    /** Origin of the seeded existing position; undefined for positions opened mid-replay. */
+    existingOrigin?: HttpTypes.PositionOrigin;
+};
+/** A matched position that received fill slices, ready to become an applicable. */
+export type MatchedPosition = {
+    positionKey: string;
+    parts: FillPart[];
+    /** Lifecycle ended within this batch (exposure returned to zero). */
+    closed: boolean;
+    /**
+     * Exposure after replaying real fills (existing position + applied part deltas).
+     * Does NOT yet include the correcting synthetics from the align step — assembly
+     * folds those in to get the final exposure.
+     */
+    exposure: Exposure;
+    /** Origin of the seeded existing position; undefined when this applicable creates a position. */
+    existingOrigin?: HttpTypes.PositionOrigin;
+};
+/** One combined leg that could not be closed against existing exposure — an open. */
+export type Leftover = {
+    side: Side;
+    qty: BigNumber;
+    leg: CombinedLeg;
+};
+/** A per-asset difference vs the exchange: 'gone' = exchange no longer has the asset, 'gap' = quantities differ. */
+export type ExposureGap = {
+    kind: 'gone' | 'gap';
+    symbol: string;
+    side: Side;
+    quantity: string;
+};
+/** A synthetic fill the server needs to mint for an asset, plus where to attach it. */
+export type NeededSynthetic = {
+    symbol: string;
+    side: Side;
+    quantity: string;
+    closedReason?: HttpTypes.PositionClosedReason;
+};
+/** Per-slice id + `original` pointer, resolved once across ALL positions so split slices stay unique. */
+export type PartId = {
+    exchangeFillId: string;
+    original?: {
+        exchangeFillId: string;
+        quantity: string;
+    };
+};

package/dist/sync/compute.d.ts

@@ -1,19 +1,33 @@
 import type { HttpTypes } from '@pear-protocol/types';
-import type { ComputeSyncPayloadArgs, ComputeSyncPayloadResult, GroupedCreatables, GroupedCreatablesMap, OrphanCreatableExternalFill } from './types';
+import type { ComputeSyncPayloadArgs, ComputeSyncPayloadResult } from './types';
+/**
+ * Derive the full sync payload from raw exchange data and local state.
+ *
+ * Async without internal awaits — the Promise signature is part of the public
+ * API consumed by exchanges-sdk, so it stays.
+ */
 export declare function computeSyncPayload(args: ComputeSyncPayloadArgs): Promise<ComputeSyncPayloadResult | null>;
+/**
+ * Validate, normalise, deduplicate, and filter raw external fills.
+ * Fills with invalid ids/quantities/timestamps or already-confirmed ids are dropped.
+ * Duplicates (same exchangeFillId) keep the earliest timestamp; result is ascending-sorted.
+ */
 export declare function _prepareExternalFills(externalFills: HttpTypes.UnknownExternalFill[], confirmedExchangeFillIdsInput: string[]): HttpTypes.UnknownExternalFill[];
-export declare function _groupCreatablesBySymbol(orphanCreatables: OrphanCreatableExternalFill[], openPositions: HttpTypes.OpenPositionLite[]): GroupedCreatablesMap;
-export declare function _splitMaybeCompositeFillAcrossPositions(fill: OrphanCreatableExternalFill, positionCandidates: [HttpTypes.OpenPositionLite, ...HttpTypes.OpenPositionLite[]]): Array<{
-    position: HttpTypes.OpenPositionLite;
-    maybeModifiedFill: OrphanCreatableExternalFill;
-}>;
-export declare function _walkBackwardsToFindLastZeroCrossing(group: GroupedCreatables): HttpTypes.CreatableExternalFill[];
-export declare function _seggregateExternalFills(provisionalFills: HttpTypes.ProvisionalFill[], externalFills: HttpTypes.UnknownExternalFill[]): {
+/**
+ * Partition external fills into reconcilables, confirmables, and orphans.
+ * Fills whose cloid matches a provisional fill we own go to confirm or reconcile;
+ * everything else (no cloid, or cloid we do not own) becomes an orphan.
+ */
+export declare function _segregateExternalFills(provisionalFills: HttpTypes.ProvisionalFill[], externalFills: HttpTypes.UnknownExternalFill[]): {
     reconcilables: HttpTypes.ReconcileFillsRequest;
     confirmables: HttpTypes.ConfirmableExternalFill[];
-    orphanCreatables: OrphanCreatableExternalFill[];
+    orphans: HttpTypes.UnknownExternalFill[];
 };
+/** Trim a cloid; empty or whitespace-only collapses to undefined. */
 export declare function _normalizeCloid(cloid?: string | null): string | undefined;
+/** Normalise an exchange fill id: trim + lowercase; absent or blank → undefined. */
 export declare function _normalizeExchangeFillId(exchangeFillId?: string | null): string | undefined;
+/** Rejects scientific-notation quantities (e.g. 1e-8) that cannot be safely parsed as fills. */
 export declare function _isValidExternalQuantity(quantity: string): boolean;
+/** Returns true only when the timestamp is a non-negative finite number. */
 export declare function _isValidExternalTimestamp(timestamp: number): boolean;

package/dist/sync/cutoff.d.ts

@@ -0,0 +1,35 @@
+/**
+ * First-sync history cutoff selection.
+ *
+ * An account's first sync fetches a fill history that can reach back through many
+ * finished lifecycles; replaying all of it would resurrect long-closed positions.
+ * This module replays the history BACKWARD from the exchange snapshot (the source
+ * of truth for current exposure) and picks the most recent boundary where the
+ * account was EXACTLY flat, so everything before it can be dropped. Seeding from
+ * the snapshot means a truncated history — a position opened before the fetched
+ * window — leaves a residual at every boundary and never produces a fake cutoff.
+ */
+import type { HttpTypes } from '@pear-protocol/types';
+/** Trim decision: keep `fills.slice(keepFromIndex)`; `fills.length` trims everything. */
+export type FirstSyncCutoff = {
+    keepFromIndex: number;
+};
+/**
+ * Selects the first-sync cutoff boundary from an ascending-sorted, prepared fill
+ * history and the current exchange snapshot.
+ *
+ * Boundary i is the account state BEFORE fills[i] (boundary fills.length is the
+ * snapshot itself). A boundary qualifies when every leg of the backward-replayed
+ * book is exactly zero (BigNumber-exact — the DUST tolerance does NOT apply) and
+ * the boundary is not inside a same-millisecond fill group (Hyperliquid merges
+ * feeds whose same-ms order is not execution order). On Hyperliquid the cutoff is
+ * additionally capped at the first Pear-placed fill so it is always kept.
+ *
+ * Returns null to keep everything: empty history, no qualifying boundary, or the
+ * qualifying boundary is 0 (a cutoff of 0 trims nothing, so it canonicalizes to null).
+ */
+export declare function selectFirstSyncCutoff(args: {
+    fills: HttpTypes.UnknownExternalFill[];
+    exchangePositions: HttpTypes.ExternalPosition[];
+    connector: HttpTypes.Connector;
+}): FirstSyncCutoff | null;