@gearbox-protocol/sdk 14.12.0-next.81 → 14.12.0-next.82

package/dist/types/new-sdk/errors/everyChainFailed.d.ts

@@ -0,0 +1,10 @@
+import { ResponseMetadata } from "../../model/response.js";
+import "../../model/index.js";
+//#region src/new-sdk/errors/everyChainFailed.d.ts
+/**
+ * Whether a merged envelope covered chains and lost every one of them, which is
+ * what makes a read a failure rather than a partial result.
+ **/
+declare function everyChainFailed(meta: ResponseMetadata): boolean;
+//#endregion
+export { everyChainFailed };

package/dist/types/new-sdk/errors/index.d.ts

@@ -0,0 +1,8 @@
+import { AllSourcesFailedError } from "./AllSourcesFailedError.js";
+import { MissingSourceError } from "./MissingSourceError.js";
+import { NoSourceServedError } from "./NoSourceServedError.js";
+import { ChainRef, SourceChainMismatchError } from "./SourceChainMismatchError.js";
+import { SourceUnavailableError } from "./SourceUnavailableError.js";
+import { assertSameChains } from "./assertSameChains.js";
+import { everyChainFailed } from "./everyChainFailed.js";
+export { AllSourcesFailedError, ChainRef, MissingSourceError, NoSourceServedError, SourceChainMismatchError, SourceUnavailableError, assertSameChains, everyChainFailed };

package/dist/types/new-sdk/index.d.ts

@@ -1,12 +1,23 @@
-import { AllSourcesFailedError, GearboxSDKOptions, Mode, OffchainByMode, OffchainSource, OffchainSourceStatus, OnchainByMode, OnchainSource, PlainMultichainSDKOptions, ReadResult, SourceMeta } from "./types.js";
-import { AbstractNamespace, CombineSources, OffchainContribution, OnchainContribution } from "./AbstractNamespace.js";
-import { Chart, ChartMetadata, HistoryReader } from "./utils/history.js";
+import { GearboxSDKOptions, Mode, NamespaceOptions, OffchainByMode, OffchainSource, OnchainByMode, OnchainSource, PlainMultichainSDKOptions } from "./types.js";
+import { filterResponse } from "./utils/filterResponse.js";
+import { HistoryReader } from "./utils/history.js";
+import { DEFAULT_MAX_OFFCHAIN_LAG, mergeChainList, mergeChainOne } from "./utils/mergeChains.js";
+import { SourceMerger } from "./utils/types.js";
 import "./utils/index.js";
-import { Opportunities, OpportunitiesBase, OpportunitiesByMode, OpportunitiesOffchainOnly, OpportunitiesOnchainOnly } from "./opportunities/types.js";
+import { AbstractNamespace, MergedQuery } from "./AbstractNamespace.js";
+import { Opportunities, OpportunitiesBase, OpportunitiesByMode, OpportunitiesMerged, OpportunitiesOffchainBranch, OpportunitiesOffchainOnly, OpportunitiesOnchainBranch, OpportunitiesOnchainOnly, OpportunityMergers } from "./opportunities/types.js";
 import { OpportunitiesNamespace } from "./opportunities/OpportunitiesNamespace.js";
 import "./opportunities/index.js";
-import { Positions, PositionsBase, PositionsByMode, PositionsOffchainOnly, PositionsOnchainOnly } from "./positions/types.js";
+import { PositionMergers, Positions, PositionsBase, PositionsByMode, PositionsMerged, PositionsOffchainBranch, PositionsOffchainOnly, PositionsOnchainBranch, PositionsOnchainOnly } from "./positions/types.js";
 import { PositionsNamespace } from "./positions/PositionsNamespace.js";
 import "./positions/index.js";
 import { GearboxSDK } from "./GearboxSDK.js";
-export { AbstractNamespace, AllSourcesFailedError, Chart, ChartMetadata, CombineSources, GearboxSDK, GearboxSDKOptions, HistoryReader, Mode, OffchainByMode, OffchainContribution, OffchainSource, OffchainSourceStatus, OnchainByMode, OnchainContribution, OnchainSource, Opportunities, OpportunitiesBase, OpportunitiesByMode, OpportunitiesNamespace, OpportunitiesOffchainOnly, OpportunitiesOnchainOnly, PlainMultichainSDKOptions, Positions, PositionsBase, PositionsByMode, PositionsNamespace, PositionsOffchainOnly, PositionsOnchainOnly, ReadResult, SourceMeta };
+import { AllSourcesFailedError } from "./errors/AllSourcesFailedError.js";
+import { MissingSourceError } from "./errors/MissingSourceError.js";
+import { NoSourceServedError } from "./errors/NoSourceServedError.js";
+import { ChainRef, SourceChainMismatchError } from "./errors/SourceChainMismatchError.js";
+import { SourceUnavailableError } from "./errors/SourceUnavailableError.js";
+import { assertSameChains } from "./errors/assertSameChains.js";
+import { everyChainFailed } from "./errors/everyChainFailed.js";
+import "./errors/index.js";
+export { AbstractNamespace, AllSourcesFailedError, ChainRef, DEFAULT_MAX_OFFCHAIN_LAG, GearboxSDK, GearboxSDKOptions, HistoryReader, MergedQuery, MissingSourceError, Mode, NamespaceOptions, NoSourceServedError, OffchainByMode, OffchainSource, OnchainByMode, OnchainSource, Opportunities, OpportunitiesBase, OpportunitiesByMode, OpportunitiesMerged, OpportunitiesNamespace, OpportunitiesOffchainBranch, OpportunitiesOffchainOnly, OpportunitiesOnchainBranch, OpportunitiesOnchainOnly, OpportunityMergers, PlainMultichainSDKOptions, PositionMergers, Positions, PositionsBase, PositionsByMode, PositionsMerged, PositionsNamespace, PositionsOffchainBranch, PositionsOffchainOnly, PositionsOnchainBranch, PositionsOnchainOnly, SourceChainMismatchError, type SourceMerger, SourceUnavailableError, assertSameChains, everyChainFailed, filterResponse, mergeChainList, mergeChainOne };

package/dist/types/new-sdk/opportunities/OpportunitiesNamespace.d.ts

@@ -1,69 +1,48 @@
-import { ILogger } from "../../sdk/types/logger.js";
 import { Opportunity, OpportunityFilter, PoolOpportunityDetail, PoolOpportunityKey, PoolOpportunityRef, StrategyOpportunityDetail, StrategyOpportunityKey, StrategyOpportunityRef } from "../../model/opportunities.js";
 import { PoolHistoryMetric, StrategyHistoryMetric } from "../../model/history.js";
+import { DataResponse } from "../../model/response.js";
 import "../../model/index.js";
 import { MultichainSDK } from "../../sdk/MultichainSDK.js";
 import "../../sdk/index.js";
 import { GearboxAPI } from "../../offchain/GearboxAPI.js";
 import "../../offchain/index.js";
-import { ReadResult } from "../types.js";
-import { AbstractNamespace } from "../AbstractNamespace.js";
+import { NamespaceOptions } from "../types.js";
 import { HistoryReader } from "../utils/history.js";
 import "../utils/index.js";
-import { OpportunitiesBase, OpportunitiesOffchainOnly } from "./types.js";
+import { AbstractNamespace } from "../AbstractNamespace.js";
+import { OpportunitiesBase, OpportunitiesOffchainOnly, OpportunityMergers } from "./types.js";
 //#region src/new-sdk/opportunities/OpportunitiesNamespace.d.ts
 /**
- * The `opportunities` namespace of the combined SDK.
- *
- * A stateless router over the two sources, see {@link AbstractNamespace} for
- * the routing itself. What is specific to opportunities is the reads below and
- * the merge policy at the bottom of the class.
- *
- * The class implements the methods of every mode; {@link GearboxSDK} exposes it
- * as its mode's slice of {@link OpportunitiesByMode}, so calling a method the
- * mode does not have is a compile error rather than a runtime one.
+ * The `opportunities` namespace of a {@link GearboxSDK}, see
+ * {@link OpportunitiesByMode} for what each mode offers.
  **/
-declare class OpportunitiesNamespace extends AbstractNamespace<Opportunity> implements OpportunitiesBase, OpportunitiesOffchainOnly {
-  #private;
-  constructor(onchain: MultichainSDK | undefined, offchain: GearboxAPI | undefined, logger?: ILogger);
+declare class OpportunitiesNamespace extends AbstractNamespace<MultichainSDK["opportunities"], GearboxAPI["opportunities"]> implements OpportunitiesBase, OpportunitiesOffchainOnly {
+  /**
+   * {@inheritDoc OpportunitiesBase.merge}
+   **/
+  readonly merge: OpportunityMergers;
+  constructor(onchain: MultichainSDK | undefined, offchain: GearboxAPI | undefined, options: NamespaceOptions);
   /**
    * {@inheritDoc OpportunitiesBase.list}
    **/
-  list(filter?: OpportunityFilter): Promise<ReadResult<Opportunity[]>>;
+  list(filter?: OpportunityFilter): Promise<DataResponse<Opportunity[]>>;
   /**
    * {@inheritDoc OpportunitiesBase.getPool}
    **/
-  getPool(key: PoolOpportunityKey): Promise<ReadResult<PoolOpportunityDetail>>;
+  getPool(key: PoolOpportunityKey): Promise<DataResponse<PoolOpportunityDetail>>;
   /**
    * {@inheritDoc OpportunitiesBase.getStrategy}
    **/
-  getStrategy(key: StrategyOpportunityKey): Promise<ReadResult<StrategyOpportunityDetail>>;
+  getStrategy(key: StrategyOpportunityKey): Promise<DataResponse<StrategyOpportunityDetail>>;
+  /**
+   * {@inheritDoc OpportunitiesBase.filter}
+   **/
+  filter(response: DataResponse<Opportunity[]> | undefined, filter?: OpportunityFilter): DataResponse<Opportunity[]> | undefined;
   /**
    * {@inheritDoc OpportunitiesOffchainOnly.history}
    **/
   history(key: PoolOpportunityRef): HistoryReader<PoolHistoryMetric>;
   history(key: StrategyOpportunityRef): HistoryReader<StrategyHistoryMetric>;
-  /**
-   * Merges the two versions of one opportunity.
-   *
-   * The chain wins every field it fills; the backend fills the rest and owns
-   * {@link OFFCHAIN_OWNED_FIELDS}.
-   *
-   * The rule is onchain-first, field-wise, and never deeper than one level: a
-   * group like `totalSupply` or `supplyApy` is taken whole from one source, so
-   * a row never mixes an on-chain token amount with a backend dollar value
-   * derived from a different block.
-   **/
-  protected mergeOne<T extends object>(onchain: T, offchain: T): T;
-  /**
-   * Unions the two lists by canonical opportunity id.
-   *
-   * Rows present in both are merged by {@link OpportunitiesNamespace.mergeOne}.
-   * Rows only the backend knows are appended: a chain the SDK does not cover,
-   * or a market it has not loaded, is a reason to show more rather than fewer
-   * opportunities.
-   **/
-  protected mergeList(onchain: Opportunity[], offchain: Opportunity[]): Opportunity[];
 }
 //#endregion
 export { OpportunitiesNamespace };

package/dist/types/new-sdk/opportunities/index.d.ts

@@ -1,3 +1,3 @@
-import { Opportunities, OpportunitiesBase, OpportunitiesByMode, OpportunitiesOffchainOnly, OpportunitiesOnchainOnly } from "./types.js";
+import { Opportunities, OpportunitiesBase, OpportunitiesByMode, OpportunitiesMerged, OpportunitiesOffchainBranch, OpportunitiesOffchainOnly, OpportunitiesOnchainBranch, OpportunitiesOnchainOnly, OpportunityMergers } from "./types.js";
 import { OpportunitiesNamespace } from "./OpportunitiesNamespace.js";
-export { Opportunities, OpportunitiesBase, OpportunitiesByMode, OpportunitiesNamespace, OpportunitiesOffchainOnly, OpportunitiesOnchainOnly };
+export { Opportunities, OpportunitiesBase, OpportunitiesByMode, OpportunitiesMerged, OpportunitiesNamespace, OpportunitiesOffchainBranch, OpportunitiesOffchainOnly, OpportunitiesOnchainBranch, OpportunitiesOnchainOnly, OpportunityMergers };

package/dist/types/new-sdk/opportunities/types.d.ts

@@ -1,28 +1,54 @@
 import { Opportunity, OpportunityFilter, PoolOpportunityDetail, PoolOpportunityKey, PoolOpportunityRef, StrategyOpportunityDetail, StrategyOpportunityKey, StrategyOpportunityRef } from "../../model/opportunities.js";
 import { PoolHistoryMetric, StrategyHistoryMetric } from "../../model/history.js";
+import { DataResponse } from "../../model/response.js";
 import "../../model/index.js";
-import { Mode, ReadResult } from "../types.js";
+import { MultichainOpportunitiesService } from "../../sdk/opportunities/MultichainOpportunitiesService.js";
+import "../../sdk/index.js";
+import { OffchainOpportunities } from "../../offchain/opportunities/OffchainOpportunities.js";
+import "../../offchain/index.js";
+import { Mode } from "../types.js";
 import { HistoryReader } from "../utils/history.js";
+import { SourceMerger } from "../utils/types.js";
+import "../utils/index.js";
 //#region src/new-sdk/opportunities/types.d.ts
 /**
- * Reads every mode supports, because either source alone can answer them.
+ * What the `opportunities` namespace offers in every mode.
  **/
 interface OpportunitiesBase {
   /**
-   * All pool and strategy opportunities, optionally narrowed.
-   *
-   * In `both` mode the two lists are unioned by canonical opportunity id and
-   * merged field-wise, with the chain winning any field both sources fill.
+   * All pool and strategy opportunities, optionally narrowed. In `both` mode
+   * each chain is served by whichever source is fresh enough, see
+   * {@link OpportunityMergers}.
    **/
-  list(filter?: OpportunityFilter): Promise<ReadResult<Opportunity[]>>;
+  list(filter?: OpportunityFilter): Promise<DataResponse<Opportunity[]>>;
   /**
    * Detailed view of one pool opportunity.
    **/
-  getPool(key: PoolOpportunityKey): Promise<ReadResult<PoolOpportunityDetail>>;
+  getPool(key: PoolOpportunityKey): Promise<DataResponse<PoolOpportunityDetail>>;
   /**
    * Detailed view of one strategy opportunity.
    **/
-  getStrategy(key: StrategyOpportunityKey): Promise<ReadResult<StrategyOpportunityDetail>>;
+  getStrategy(key: StrategyOpportunityKey): Promise<DataResponse<StrategyOpportunityDetail>>;
+  /**
+   * Narrows an already-read list, rows and metadata alike. `undefined` passes
+   * through, so a read still in flight stays that way.
+   **/
+  filter(response: DataResponse<Opportunity[]> | undefined, filter?: OpportunityFilter): DataResponse<Opportunity[]> | undefined;
+  /**
+   * The chain on its own, for a consumer that shows each source as it arrives.
+   * Throws in `offchain` mode.
+   **/
+  readonly onchain: MultichainOpportunitiesService;
+  /**
+   * The backend on its own, see {@link OpportunitiesBase.onchain}. Throws in
+   * `onchain` mode.
+   **/
+  readonly offchain: OffchainOpportunities;
+  /**
+   * Merge policy of each read, for a consumer combining the two branches
+   * itself, see {@link OpportunityMergers}.
+   **/
+  readonly merge: OpportunityMergers;
 }
 /**
  * Reads only a backend can answer.
@@ -30,37 +56,65 @@ interface OpportunitiesBase {
 interface OpportunitiesOffchainOnly {
   /**
    * Historical charts of one opportunity, one metric and one range at a time:
-   * `history(key).chart("depositApy", "1m")`.
-   *
-   * The key's kind decides which metrics exist, so asking a pool for a
-   * strategy series does not compile.
-   *
-   * Absent in `onchain` mode: the chain serves the present, and rebuilding a
-   * series from it would mean an archive read per point.
+   * `history(key).chart("depositApy", "1m")`. The key's kind decides which
+   * metrics exist, so asking a pool for a strategy series does not compile.
    **/
   history(key: PoolOpportunityRef): HistoryReader<PoolHistoryMetric>;
   history(key: StrategyOpportunityRef): HistoryReader<StrategyHistoryMetric>;
 }
 /**
- * Reads only the chain can answer. Empty for now — every on-chain read the
- * namespace exposes has a backend counterpart.
+ * Reads only the chain can answer. Empty for now.
  **/
 interface OpportunitiesOnchainOnly {}
+/**
+ * How each read combines what the two sources returned: a chain is served by
+ * the backend when it is fresh enough, and by the chain otherwise.
+ **/
+interface OpportunityMergers {
+  list: SourceMerger<Opportunity[]>;
+  pool: SourceMerger<PoolOpportunityDetail>;
+  strategy: SourceMerger<StrategyOpportunityDetail>;
+}
+/**
+ * Which reads the `opportunities` namespace has in each mode. A widened mode
+ * offers what every mode has, i.e. {@link OpportunitiesBase} alone.
+ **/
+interface OpportunitiesOnchainBranch {
+  readonly onchain: MultichainOpportunitiesService;
+}
+/**
+ * The backend on its own, see {@link OpportunitiesOnchainBranch}.
+ **/
+interface OpportunitiesOffchainBranch {
+  readonly offchain: OffchainOpportunities;
+}
+/**
+ * Merge policy of each read, exposed so that a consumer reading the two
+ * branches itself combines them exactly as `both` mode would: a chain is served
+ * by the backend when it is fresh enough, and by the chain otherwise.
+ **/
+interface OpportunityMergers {
+  list: SourceMerger<Opportunity[]>;
+  pool: SourceMerger<PoolOpportunityDetail>;
+  strategy: SourceMerger<StrategyOpportunityDetail>;
+}
+/**
+ * Merging, which only exists where there are two sources to merge.
+ **/
+interface OpportunitiesMerged {
+  readonly merge: OpportunityMergers;
+}
 /**
  * Which methods the `opportunities` namespace has in each mode.
- *
- * A lookup map rather than a conditional type: `both` is spelled out instead of
- * being inferred, and a widened mode degrades to the intersection of what all
- * modes offer rather than silently distributing into a union of everything.
  **/
 interface OpportunitiesByMode {
-  onchain: OpportunitiesBase & OpportunitiesOnchainOnly;
-  offchain: OpportunitiesBase & OpportunitiesOffchainOnly;
-  both: OpportunitiesBase & OpportunitiesOffchainOnly & OpportunitiesOnchainOnly;
+  onchain: OpportunitiesBase & OpportunitiesOnchainOnly & OpportunitiesOnchainBranch;
+  offchain: OpportunitiesBase & OpportunitiesOffchainOnly & OpportunitiesOffchainBranch;
+  both: OpportunitiesBase & OpportunitiesOnchainOnly & OpportunitiesOffchainOnly;
 }
 /**
  * The `opportunities` namespace of a {@link GearboxSDK} in mode `M`.
  **/
 type Opportunities<M extends Mode = Mode> = OpportunitiesByMode[M];
 //#endregion
-export { Opportunities, OpportunitiesBase, OpportunitiesByMode, OpportunitiesOffchainOnly, OpportunitiesOnchainOnly };
+export { Opportunities, OpportunitiesBase, OpportunitiesByMode, OpportunitiesMerged, OpportunitiesOffchainBranch, OpportunitiesOffchainOnly, OpportunitiesOnchainBranch, OpportunitiesOnchainOnly, OpportunityMergers };

package/dist/types/new-sdk/positions/PositionsNamespace.d.ts

@@ -1,62 +1,41 @@
-import { ILogger } from "../../sdk/types/logger.js";
 import { PoolPositionRef, Position, PositionFilter, StrategyPositionRef } from "../../model/positions.js";
 import { PoolPositionHistoryMetric, StrategyPositionHistoryMetric } from "../../model/history.js";
+import { DataResponse } from "../../model/response.js";
 import "../../model/index.js";
 import { MultichainSDK } from "../../sdk/MultichainSDK.js";
 import "../../sdk/index.js";
 import { GearboxAPI } from "../../offchain/GearboxAPI.js";
 import "../../offchain/index.js";
-import { ReadResult } from "../types.js";
-import { AbstractNamespace } from "../AbstractNamespace.js";
+import { NamespaceOptions } from "../types.js";
 import { HistoryReader } from "../utils/history.js";
 import "../utils/index.js";
-import { PositionsBase, PositionsOffchainOnly } from "./types.js";
+import { AbstractNamespace } from "../AbstractNamespace.js";
+import { PositionMergers, PositionsBase, PositionsOffchainOnly } from "./types.js";
 import { Address } from "viem";
 //#region src/new-sdk/positions/PositionsNamespace.d.ts
 /**
- * The `positions` namespace of the combined SDK.
- *
- * A stateless router over the two sources, see {@link AbstractNamespace} for the
- * routing itself. What is specific to positions is the reads below and the merge
- * policy at the bottom of the class.
- *
- * The class implements the methods of every mode; {@link GearboxSDK} exposes it
- * as its mode's slice of {@link PositionsByMode}, so calling a method the mode
- * does not have is a compile error rather than a runtime one.
+ * The `positions` namespace of a {@link GearboxSDK}, see
+ * {@link PositionsByMode} for what each mode offers.
  **/
-declare class PositionsNamespace extends AbstractNamespace<Position> implements PositionsBase, PositionsOffchainOnly {
-  #private;
-  constructor(onchain: MultichainSDK | undefined, offchain: GearboxAPI | undefined, logger?: ILogger);
+declare class PositionsNamespace extends AbstractNamespace<MultichainSDK["positions"], GearboxAPI["positions"]> implements PositionsBase, PositionsOffchainOnly {
   /**
-   * {@inheritDoc PositionsBase.list}
+   * {@inheritDoc PositionsBase.merge}
    **/
-  list(wallet: Address, filter?: PositionFilter): Promise<ReadResult<Position[]>>;
+  readonly merge: PositionMergers;
+  constructor(onchain: MultichainSDK | undefined, offchain: GearboxAPI | undefined, options: NamespaceOptions);
   /**
-   * {@inheritDoc PositionsOffchainOnly.history}
+   * {@inheritDoc PositionsBase.list}
    **/
-  history(key: PoolPositionRef): HistoryReader<PoolPositionHistoryMetric>;
-  history(key: StrategyPositionRef): HistoryReader<StrategyPositionHistoryMetric>;
+  list(wallet: Address, filter?: PositionFilter): Promise<DataResponse<Position[]>>;
   /**
-   * Merges the two versions of one position.
-   *
-   * The chain wins every field it fills; the backend fills the rest and owns
-   * {@link OFFCHAIN_OWNED_FIELDS}.
-   *
-   * The rule is onchain-first, field-wise, and never deeper than one level: a
-   * group like `totalValue` or `apy` is taken whole from one source, so a row
-   * never mixes an on-chain token amount with a backend dollar value derived
-   * from a different block.
+   * {@inheritDoc PositionsBase.filter}
    **/
-  protected mergeOne<T extends object>(onchain: T, offchain: T): T;
+  filter(response: DataResponse<Position[]> | undefined, filter?: PositionFilter): DataResponse<Position[]> | undefined;
   /**
-   * Unions the two lists by canonical position id.
-   *
-   * Rows present in both are merged by {@link PositionsNamespace.mergeOne}.
-   * Rows only the backend knows are appended: a chain the SDK does not cover,
-   * or a market it has not loaded, must not hide a position the wallet actually
-   * holds.
+   * {@inheritDoc PositionsOffchainOnly.history}
    **/
-  protected mergeList(onchain: Position[], offchain: Position[]): Position[];
+  history(key: PoolPositionRef): HistoryReader<PoolPositionHistoryMetric>;
+  history(key: StrategyPositionRef): HistoryReader<StrategyPositionHistoryMetric>;
 }
 //#endregion
 export { PositionsNamespace };

package/dist/types/new-sdk/positions/index.d.ts

@@ -1,3 +1,3 @@
-import { Positions, PositionsBase, PositionsByMode, PositionsOffchainOnly, PositionsOnchainOnly } from "./types.js";
+import { PositionMergers, Positions, PositionsBase, PositionsByMode, PositionsMerged, PositionsOffchainBranch, PositionsOffchainOnly, PositionsOnchainBranch, PositionsOnchainOnly } from "./types.js";
 import { PositionsNamespace } from "./PositionsNamespace.js";
-export { Positions, PositionsBase, PositionsByMode, PositionsNamespace, PositionsOffchainOnly, PositionsOnchainOnly };
+export { PositionMergers, Positions, PositionsBase, PositionsByMode, PositionsMerged, PositionsNamespace, PositionsOffchainBranch, PositionsOffchainOnly, PositionsOnchainBranch, PositionsOnchainOnly };

package/dist/types/new-sdk/positions/types.d.ts

@@ -1,22 +1,48 @@
 import { PoolPositionRef, Position, PositionFilter, StrategyPositionRef } from "../../model/positions.js";
 import { PoolPositionHistoryMetric, StrategyPositionHistoryMetric } from "../../model/history.js";
+import { DataResponse } from "../../model/response.js";
 import "../../model/index.js";
-import { Mode, ReadResult } from "../types.js";
+import { MultichainPositionsService } from "../../sdk/positions/MultichainPositionsService.js";
+import "../../sdk/index.js";
+import { OffchainPositions } from "../../offchain/positions/OffchainPositions.js";
+import "../../offchain/index.js";
+import { Mode } from "../types.js";
 import { HistoryReader } from "../utils/history.js";
+import { SourceMerger } from "../utils/types.js";
+import "../utils/index.js";
 import { Address } from "viem";
 //#region src/new-sdk/positions/types.d.ts
 /**
- * Reads every mode supports, because either source alone can answer them.
+ * What the `positions` namespace offers in every mode.
  **/
 interface PositionsBase {
   /**
    * Everything a wallet holds: its pool shares, its credit accounts and the
-   * delayed withdrawals it took over by liquidating, optionally narrowed.
-   *
-   * In `both` mode the two lists are unioned by canonical position id and
-   * merged field-wise, with the chain winning any field both sources fill.
+   * delayed withdrawals it took over by liquidating, optionally narrowed. In
+   * `both` mode each chain is served by whichever source is fresh enough, see
+   * {@link PositionMergers}.
    **/
-  list(wallet: Address, filter?: PositionFilter): Promise<ReadResult<Position[]>>;
+  list(wallet: Address, filter?: PositionFilter): Promise<DataResponse<Position[]>>;
+  /**
+   * Narrows an already-read list, rows and metadata alike. `undefined` passes
+   * through, so a read still in flight stays that way.
+   **/
+  filter(response: DataResponse<Position[]> | undefined, filter?: PositionFilter): DataResponse<Position[]> | undefined;
+  /**
+   * The chain on its own, for a consumer that shows each source as it arrives.
+   * Throws in `offchain` mode.
+   **/
+  readonly onchain: MultichainPositionsService;
+  /**
+   * The backend on its own, see {@link PositionsBase.onchain}. Throws in
+   * `onchain` mode.
+   **/
+  readonly offchain: OffchainPositions;
+  /**
+   * Merge policy of each read, for a consumer combining the two branches
+   * itself, see {@link PositionMergers}.
+   **/
+  readonly merge: PositionMergers;
 }
 /**
  * Reads only a backend can answer.
@@ -24,39 +50,63 @@ interface PositionsBase {
 interface PositionsOffchainOnly {
   /**
    * Historical charts of one position, one metric and one range at a time:
-   * `history(key).chart("netApy", "1m")`.
-   *
-   * The key's kind decides which metrics exist, so asking a pool position for a
-   * strategy series does not compile. Liquidation positions have no history at
-   * all: a delayed withdrawal is a single event rather than a series, which is
-   * why no key names one.
-   *
-   * Absent in `onchain` mode: the chain serves the present, and rebuilding a
-   * series from it would mean an archive read per point.
+   * `history(key).chart("netApy", "1m")`. The key's kind decides which metrics
+   * exist, so asking a pool position for a strategy series does not compile.
+   * Liquidation positions have no charts: a delayed withdrawal is a single
+   * event rather than a series.
    **/
   history(key: PoolPositionRef): HistoryReader<PoolPositionHistoryMetric>;
   history(key: StrategyPositionRef): HistoryReader<StrategyPositionHistoryMetric>;
 }
 /**
- * Reads only the chain can answer. Empty for now — every on-chain read the
- * namespace exposes has a backend counterpart.
+ * Reads only the chain can answer. Empty for now.
  **/
 interface PositionsOnchainOnly {}
+/**
+ * How each read combines what the two sources returned: a chain is served by
+ * the backend when it is fresh enough, and by the chain otherwise.
+ **/
+interface PositionMergers {
+  list: SourceMerger<Position[]>;
+}
+/**
+ * Which reads the `positions` namespace has in each mode. A widened mode offers
+ * what every mode has, i.e. {@link PositionsBase} alone.
+ **/
+interface PositionsOnchainBranch {
+  readonly onchain: MultichainPositionsService;
+}
+/**
+ * The backend on its own, see {@link PositionsOnchainBranch}.
+ **/
+interface PositionsOffchainBranch {
+  readonly offchain: OffchainPositions;
+}
+/**
+ * Merge policy of each read, exposed so that a consumer reading the two
+ * branches itself combines them exactly as `both` mode would: a chain is served
+ * by the backend when it is fresh enough, and by the chain otherwise.
+ **/
+interface PositionMergers {
+  list: SourceMerger<Position[]>;
+}
+/**
+ * Merging, which only exists where there are two sources to merge.
+ **/
+interface PositionsMerged {
+  readonly merge: PositionMergers;
+}
 /**
  * Which methods the `positions` namespace has in each mode.
- *
- * A lookup map rather than a conditional type: `both` is spelled out instead of
- * being inferred, and a widened mode degrades to the intersection of what all
- * modes offer rather than silently distributing into a union of everything.
  **/
 interface PositionsByMode {
   onchain: PositionsBase & PositionsOnchainOnly;
   offchain: PositionsBase & PositionsOffchainOnly;
-  both: PositionsBase & PositionsOffchainOnly & PositionsOnchainOnly;
+  both: PositionsBase & PositionsOnchainOnly & PositionsOffchainOnly;
 }
 /**
  * The `positions` namespace of a {@link GearboxSDK} in mode `M`.
  **/
 type Positions<M extends Mode = Mode> = PositionsByMode[M];
 //#endregion
-export { Positions, PositionsBase, PositionsByMode, PositionsOffchainOnly, PositionsOnchainOnly };
+export { PositionMergers, Positions, PositionsBase, PositionsByMode, PositionsMerged, PositionsOffchainBranch, PositionsOffchainOnly, PositionsOnchainBranch, PositionsOnchainOnly };