@usherlabs/cex-broker 0.2.45 → 0.2.46

package/dist/handlers/subscribe/handler.d.ts

@@ -2,6 +2,7 @@ import * as grpc from "@grpc/grpc-js";
 import { type BrokerPoolEntry } from "../../helpers/broker";
 import type { BrokerExecutionArchiver } from "../../helpers/broker-execution-archive";
 import type { OtelMetrics } from "../../helpers/otel";
+import { PublicMarketDataFeedSupervisor } from "../../helpers/public-market-data-feed";
 import type { UserDataStreamSupervisor } from "../../helpers/user-data-stream-supervisor";
 import type { SubscribeRequest, SubscribeResponse } from "../types";
 import { SubscribeBrokerLifecycle } from "./broker-lifecycle";
@@ -12,6 +13,7 @@ export type SubscribeDeps = {
     brokerArchiver?: BrokerExecutionArchiver;
     brokerLifecycle?: SubscribeBrokerLifecycle;
     userDataStreamSupervisor?: UserDataStreamSupervisor;
+    publicMarketDataFeedSupervisor?: PublicMarketDataFeedSupervisor;
 };
 type SubscribeCall = grpc.ServerWritableStream<SubscribeRequest, SubscribeResponse>;
 export declare function createSubscribeHandler(deps: SubscribeDeps): (call: SubscribeCall) => Promise<void>;

package/dist/helpers/market-data-archive/capture-contract.d.ts

@@ -2,11 +2,12 @@ import type { MarketCaptureContext, RawCapture, RawCaptureScope } from "./types"
 export declare const MARKET_CAPTURE_SCHEMA_VERSION: "1.0.0";
 export declare const CHECKSUM_ALGORITHM: "sha256-canonical-json-v1";
 export declare const ARCHIVE_SOURCES: readonly ["broker_read", "broker_write"];
+export declare const MARKET_ARCHIVE_SOURCES: readonly ["broker_read", "broker_write", "external_backfill"];
 export declare const CAPTURE_FEEDS: readonly ["ORDERBOOK", "TICKER", "TRADES", "OHLCV"];
-export declare const SOURCE_MODES: readonly ["broker_live_stream_v1", "broker_live_sampling_v1", "broker_current_snapshot_v1", "broker_bootstrap_fetch_v1", "external_ccxt_fallback_v1", "external_hummingbot_fallback_v1", "legacy_migration_v1"];
+export declare const SOURCE_MODES: readonly ["broker_live_stream_v1", "broker_live_sampling_v1", "broker_current_snapshot_v1", "broker_bootstrap_fetch_v1", "external_ccxt_fallback_v1", "external_hummingbot_fallback_v1", "legacy_migration_v1", "historical_vendor_orderbook_v1", "vendor_historical_backfill_v1"];
 export declare const CONSTRUCTION_MODES: readonly ["sampled_top_n_snapshot", "exact_l2_reconstruction"];
 export declare const GAP_POLICIES: readonly ["record_gap", "ohlcv_catch_up", "fail_fast"];
-export declare const RAW_CAPTURE_SCOPES: readonly ["ccxt_normalized_object", "broker_visible_payload", "exchange_wire_frame"];
+export declare const RAW_CAPTURE_SCOPES: readonly ["ccxt_normalized_object", "broker_visible_payload", "exchange_wire_frame", "vendor_normalized_dataset_file"];
 export type CaptureFeed = (typeof CAPTURE_FEEDS)[number];
 export type SourceMode = (typeof SOURCE_MODES)[number];
 export type ConstructionMode = (typeof CONSTRUCTION_MODES)[number];

package/dist/helpers/market-data-archive/types.d.ts

@@ -1,6 +1,7 @@
 import type { BrokerArchiveRow, BrokerArchiveSource } from "../broker-execution-archive/types";
 import type { BrokerMarketType } from "../market-type";
 import type { NormalizedOrderBookSnapshot } from "../order-book";
+export type MarketArchiveSource = BrokerArchiveSource | "external_backfill";
 export type MarketArchiveTable = "market_data.orderbook_snapshots" | "market_data.candles" | "market_data.cex_stream_events" | "market_data.cex_ticker_events" | "market_data.cex_trades" | "market_data.cex_ohlcv" | "market_data.cex_order_book_levels" | "market_data.cex_order_book_depth_summary";
 export type CexStreamType = "BALANCE" | "ORDERS" | "ORDERBOOK" | "TRADES" | "TICKER" | "OHLCV";
 export type ParsedOhlcvBar = {
@@ -27,10 +28,11 @@ export type MarketArchiveContext = {
     deploymentId: string;
 };
 export type CaptureFeed = "ORDERBOOK" | "TICKER" | "TRADES" | "OHLCV";
-export type CaptureSourceMode = "broker_live_stream_v1" | "broker_live_sampling_v1" | "broker_current_snapshot_v1" | "broker_bootstrap_fetch_v1" | "external_ccxt_fallback_v1" | "external_hummingbot_fallback_v1" | "legacy_migration_v1";
-export type RawCaptureScope = "ccxt_normalized_object" | "broker_visible_payload" | "exchange_wire_frame";
-export type MarketCaptureContext = MarketArchiveContext & {
-    source: BrokerArchiveSource;
+export type CaptureSourceMode = "broker_live_stream_v1" | "broker_live_sampling_v1" | "broker_current_snapshot_v1" | "broker_bootstrap_fetch_v1" | "external_ccxt_fallback_v1" | "external_hummingbot_fallback_v1" | "legacy_migration_v1" | "historical_vendor_orderbook_v1" | "vendor_historical_backfill_v1";
+export type CaptureOrigin = "production_capture" | "vendor_historical_backfill";
+export type RawCaptureScope = "ccxt_normalized_object" | "broker_visible_payload" | "exchange_wire_frame" | "vendor_normalized_dataset_file";
+export type MarketCaptureContext = Omit<MarketArchiveContext, "source"> & {
+    source: MarketArchiveSource;
     captureBundleId: string;
     feed: CaptureFeed;
     provider: string;
@@ -38,6 +40,8 @@ export type MarketCaptureContext = MarketArchiveContext & {
     schemaVersion: string;
     checksumAlgorithm: string;
     provenanceComplete: boolean;
+    tradingPair?: string;
+    sourceSymbol?: string;
 };
 export type RawCapture = {
     rawCaptureId: string;

package/dist/helpers/market-data-vendor-backfill/archive-reader.d.ts

@@ -0,0 +1,26 @@
+import type { MarketDataVendorBackfillRequest } from "./contracts";
+import type { ArchivePreflightResolution, CandidateVerification, NormalizedBackfill, QualifiedCoverage } from "./core";
+export type ArchiveQueryValue = string | number | readonly string[];
+export type ArchiveQueryClient = {
+    query(sql: string, parameters?: Readonly<Record<string, ArchiveQueryValue>>): Promise<Record<string, unknown>[]>;
+};
+export type QualifiedArchiveReaderOptions = {
+    nowMs?: () => number;
+};
+export declare class QualifiedOrderBookArchiveReader {
+    private readonly client;
+    private readonly options?;
+    constructor(client: ArchiveQueryClient, options?: QualifiedArchiveReaderOptions | undefined);
+    resolveSelection(request: MarketDataVendorBackfillRequest): Promise<ArchivePreflightResolution>;
+    private readReceipts;
+    coverage(request: MarketDataVendorBackfillRequest): Promise<QualifiedCoverage>;
+    private boundaryRows;
+    verifyCandidate(request: MarketDataVendorBackfillRequest, normalized: NormalizedBackfill, captureBundleId: string, baseline: ArchivePreflightResolution): Promise<CandidateVerification>;
+    private seamIsOrdered;
+}
+export declare function createClickHouseArchiveQueryClient(input: {
+    url: string;
+    username?: string;
+    password?: string;
+    fetch?: typeof fetch;
+}): ArchiveQueryClient;

package/dist/helpers/market-data-vendor-backfill/batching.d.ts

@@ -0,0 +1,10 @@
+import { type BackfillArchiveRow, type ForwarderBatch } from "./contracts";
+export declare const BACKFILL_MAX_BATCH_ROWS = 1000;
+export declare const BACKFILL_MAX_BATCH_BYTES: number;
+export declare function buildForwarderBatches(input: {
+    captureBundleId: string;
+    deploymentId: string;
+    rows: readonly BackfillArchiveRow[];
+    maxRows?: number;
+    maxBytes?: number;
+}): ForwarderBatch[];

package/dist/helpers/market-data-vendor-backfill/conformance-fixtures.d.ts

@@ -0,0 +1,80 @@
+export declare const CONFORMANCE_FIXTURES: Readonly<{
+    fixture_id: "market-data-vendor-backfill-conformance/v1";
+    documents: {
+        required_clock: import("./contracts").RequiredClockWire;
+        archive_selection: import("./contracts").ArchiveSelectionWire;
+        request: {
+            idempotency_key: string;
+            schema_id: string;
+            request_id: string;
+            attempt_id: string;
+            scope: {
+                exchange: string;
+                trading_pair: string;
+                market_type: "spot";
+                feed: "ORDERBOOK";
+            };
+            window: {
+                start_at: string;
+                end_at: string;
+            };
+            depth: number;
+            construction_mode: "sampled_top_n_snapshot";
+            source_policy: "authoritative_window";
+            target: {
+                environment: string;
+                cluster: string;
+            };
+            coverage_policy: {
+                policy_id: "prior-asof-strict/v1";
+                max_asof_lag_ms: number;
+                future_rows: "reject";
+                missing_required_event: "fail";
+            };
+            required_clock: {
+                schema_id: string;
+                clock_id: string;
+                file_name: string;
+                clock_sha256: string;
+                event_count: number;
+            };
+            initial_selection: import("./contracts").ArchiveSelectionWire;
+            expected_canonical_schema: {
+                schema_id: string;
+                schema_sha256: string;
+            };
+            product_pins: {
+                capability_policy: {
+                    policy_id: "market-data-vendor-backfill-capabilities/v1";
+                    policy_sha256: string;
+                };
+                resource_policy: {
+                    policy_id: "market-data-vendor-backfill-resources/v1";
+                    policy_sha256: string;
+                };
+            };
+            production_authorization_id: string;
+        };
+        promotion_receipt: import("./contracts").PromotionReceiptWire;
+        result: import("./contracts").BackfillJobResultWire;
+    };
+    identities: {
+        idempotency_key: string;
+        clock_sha256: string;
+        initial_selection_sha256: string;
+        selection_sha256: string;
+        promotion_identity_sha256: string;
+        receipt_id: string;
+        result_sha256: string;
+        capability_policy_sha256: string;
+        resource_policy_sha256: string;
+    };
+    jcs_edge_vector: {
+        literals: (boolean | null)[];
+        numbers: number[];
+        string: string;
+    };
+    hashes: {
+        jcs_edge_vector_sha256: string;
+    };
+}>;

package/dist/helpers/market-data-vendor-backfill/contracts.d.ts

@@ -0,0 +1,393 @@
+import { z } from "zod";
+export declare const BACKFILL_REQUEST_SCHEMA_ID: string;
+export declare const REQUIRED_CLOCK_SCHEMA_ID: string;
+export declare const ARCHIVE_SELECTION_SCHEMA_ID: string;
+export declare const PROMOTION_RECEIPT_SCHEMA_ID: string;
+export declare const BACKFILL_RESULT_SCHEMA_ID: string;
+export type FixedUtcTimestamp = string;
+export type Sha256Hex = string;
+export type LowercaseUuid = string;
+export type CanonicalScopeWire = {
+    exchange: string;
+    trading_pair: string;
+    market_type: "spot" | "swap" | "future";
+    feed: "ORDERBOOK";
+};
+export type CoveragePolicyWire = {
+    policy_id: "prior-asof-strict/v1";
+    max_asof_lag_ms: number;
+    future_rows: "reject";
+    missing_required_event: "fail";
+};
+export type RequiredClockWire = {
+    schema_id: typeof REQUIRED_CLOCK_SCHEMA_ID;
+    clock_id: LowercaseUuid;
+    clock_sha256: Sha256Hex;
+    created_at: FixedUtcTimestamp;
+    targets: Array<{
+        target_id: LowercaseUuid;
+        target_at: FixedUtcTimestamp;
+    }>;
+};
+export type ArchiveSelectionWire = {
+    schema_id: typeof ARCHIVE_SELECTION_SCHEMA_ID;
+    selection_sha256: Sha256Hex;
+    scope: CanonicalScopeWire;
+    required_clock: {
+        clock_id: LowercaseUuid;
+        clock_sha256: Sha256Hex;
+        event_count: number;
+    };
+    coverage_policy: CoveragePolicyWire;
+    source_policy: "authoritative_window" | "fill_gaps";
+    coverage_class: "complete" | "partial" | "missing";
+    requested_intervals: Array<{
+        start_at: FixedUtcTimestamp;
+        end_at: FixedUtcTimestamp;
+    }>;
+    selected_intervals: Array<{
+        start_at: FixedUtcTimestamp;
+        end_at: FixedUtcTimestamp;
+        capture_bundle_id: Sha256Hex;
+        capture_origin: "production_capture" | "vendor_historical_backfill";
+    }>;
+    precedence: Array<"archive" | "vendor">;
+    bundles: Array<{
+        capture_bundle_id: Sha256Hex;
+        capture_origin: "production_capture" | "vendor_historical_backfill";
+        interval: {
+            start_at: FixedUtcTimestamp;
+            end_at: FixedUtcTimestamp;
+        };
+        qualification: null | {
+            qualification_event_id: LowercaseUuid;
+            state: "qualified";
+            receipt_id: Sha256Hex;
+            promotion_identity_sha256: Sha256Hex;
+        };
+    }>;
+    support_anchors: Array<{
+        capture_bundle_id: Sha256Hex;
+        raw_capture_id: Sha256Hex;
+        snapshot_id: Sha256Hex;
+        source_time: FixedUtcTimestamp;
+        normalized_summary_checksum: Sha256Hex;
+        metadata_ref: {
+            capture_origin: "production_capture" | "vendor_historical_backfill";
+            qualification_event_id: LowercaseUuid | null;
+            receipt_id: Sha256Hex | null;
+        };
+    }>;
+    receipt_ids: Sha256Hex[];
+    qualification_event_ids: LowercaseUuid[];
+    resolved_at: FixedUtcTimestamp;
+};
+export type BackfillRequestWire = {
+    schema_id: typeof BACKFILL_REQUEST_SCHEMA_ID;
+    request_id: LowercaseUuid;
+    attempt_id: LowercaseUuid;
+    idempotency_key: Sha256Hex;
+    scope: CanonicalScopeWire;
+    window: {
+        start_at: FixedUtcTimestamp;
+        end_at: FixedUtcTimestamp;
+    };
+    depth: number;
+    construction_mode: "sampled_top_n_snapshot" | "exact_l2_reconstruction";
+    source_policy: "authoritative_window" | "fill_gaps";
+    target: {
+        environment: string;
+        cluster: string;
+    };
+    coverage_policy: CoveragePolicyWire;
+    required_clock: {
+        schema_id: typeof REQUIRED_CLOCK_SCHEMA_ID;
+        clock_id: LowercaseUuid;
+        file_name: string;
+        clock_sha256: Sha256Hex;
+        event_count: number;
+    };
+    initial_selection: ArchiveSelectionWire;
+    expected_canonical_schema: {
+        schema_id: string;
+        schema_sha256: Sha256Hex;
+    };
+    product_pins: {
+        capability_policy: {
+            policy_id: string;
+            policy_sha256: Sha256Hex;
+        };
+        resource_policy: {
+            policy_id: string;
+            policy_sha256: Sha256Hex;
+        };
+    };
+    production_authorization_id: LowercaseUuid;
+};
+export type PromotionReceiptWire = {
+    schema_id: typeof PROMOTION_RECEIPT_SCHEMA_ID;
+    receipt_id: Sha256Hex;
+    promotion_identity_sha256: Sha256Hex;
+    verified_at: FixedUtcTimestamp;
+    request_id: LowercaseUuid;
+    idempotency_key: Sha256Hex;
+    source: "external_backfill";
+    capture_origin: "vendor_historical_backfill";
+    source_mode: "vendor_historical_backfill_v1";
+    provider: string;
+    adapter_version: string;
+    effective_policies: {
+        capability_policy: {
+            policy_id: string;
+            policy_sha256: Sha256Hex;
+        };
+        resource_policy: {
+            policy_id: string;
+            policy_sha256: Sha256Hex;
+        };
+        adapter_policy: {
+            policy_id: string;
+            policy_sha256: Sha256Hex;
+        };
+        acquisition_policy: {
+            policy_id: string;
+            policy_sha256: Sha256Hex;
+        };
+    };
+    capture_bundle_id: Sha256Hex;
+    scope: CanonicalScopeWire;
+    window: {
+        start_at: FixedUtcTimestamp;
+        end_at: FixedUtcTimestamp;
+    };
+    depth: number;
+    construction_mode: "sampled_top_n_snapshot" | "exact_l2_reconstruction";
+    canonical_schema: {
+        schema_id: string;
+        schema_sha256: Sha256Hex;
+    };
+    coverage_policy: CoveragePolicyWire;
+    selection_sha256: Sha256Hex;
+    vendor_semantic_digest: Sha256Hex;
+    canonical_semantic_digest: Sha256Hex;
+    prefix_digest: Sha256Hex;
+    suffix_digest: Sha256Hex;
+    seam_verified: true;
+    coverage_verified: true;
+    dataset_objects: Array<{
+        identity: string;
+        checksum: Sha256Hex;
+        bytes: number;
+        rows: number;
+    }>;
+};
+export declare const FINAL_BACKFILL_STATUSES: readonly ["request_invalid", "archive_preflight_failed", "already_covered", "promoted", "capability_unsupported", "credentials_missing", "vendor_fetch_failed", "archive_ingest_failed", "promotion_verification_failed"];
+export type FinalBackfillStatus = (typeof FINAL_BACKFILL_STATUSES)[number];
+export type BackfillJobResultWire = {
+    schema_id: typeof BACKFILL_RESULT_SCHEMA_ID;
+    result_sha256: Sha256Hex;
+    job_id: LowercaseUuid;
+    request_file_sha256: Sha256Hex | null;
+    executable_sha256: Sha256Hex;
+    schema_manifest_sha256: Sha256Hex;
+    cex_package: {
+        name: "@usherlabs/cex-broker";
+        version: string;
+        package_sha256: Sha256Hex;
+    };
+    capability_policy: {
+        policy_id: string;
+        policy_sha256: Sha256Hex;
+    };
+    resource_policy: {
+        policy_id: string;
+        policy_sha256: Sha256Hex;
+    };
+    build: {
+        fiet_tee_commit: string;
+        created_at: FixedUtcTimestamp;
+    };
+    started_at: FixedUtcTimestamp;
+    completed_at: FixedUtcTimestamp;
+    outcome: {
+        status: FinalBackfillStatus;
+        reason_code: string;
+        reason_subcode: string | null;
+        request_id: LowercaseUuid | null;
+        idempotency_key: Sha256Hex | null;
+        target: {
+            environment: string;
+            cluster: string;
+        } | null;
+        selection: ArchiveSelectionWire | null;
+        receipt: PromotionReceiptWire | null;
+        diagnostics: Record<string, string | number | boolean>;
+    };
+};
+type Codec<T> = {
+    decode(value: unknown): T;
+    is(value: unknown): value is T;
+};
+export declare const requiredClockCodec: Codec<RequiredClockWire>;
+export declare const archiveSelectionCodec: Codec<ArchiveSelectionWire>;
+export declare function promotionIdentitySha256(receipt: Omit<PromotionReceiptWire, "receipt_id" | "promotion_identity_sha256"> & Partial<Pick<PromotionReceiptWire, "receipt_id" | "promotion_identity_sha256">>): string;
+export declare const promotionReceiptCodec: Codec<PromotionReceiptWire>;
+export declare const backfillResultCodec: Codec<BackfillJobResultWire>;
+export declare const backfillRequestCodec: {
+    decode(value: unknown): {
+        wire: BackfillRequestWire;
+    };
+    is(value: unknown): value is BackfillRequestWire;
+};
+export declare function finalizeRequiredClock(clock: Omit<RequiredClockWire, "clock_sha256">): RequiredClockWire;
+export declare function finalizeArchiveSelection(selection: Omit<ArchiveSelectionWire, "selection_sha256">): ArchiveSelectionWire;
+export declare function finalizeBackfillResult(result: Omit<BackfillJobResultWire, "result_sha256"> & Partial<Pick<BackfillJobResultWire, "result_sha256">>): BackfillJobResultWire;
+export declare const BACKFILL_REQUEST_SCHEMA_VERSION: "market-data-vendor-backfill-request/v1";
+export declare const BACKFILL_RESULT_SCHEMA_VERSION: "market-data-vendor-backfill-result/v1";
+export declare const BACKFILL_PROMOTION_SCHEMA_VERSION: "market-data-vendor-backfill-promotion-receipt/v1";
+export declare const EXTERNAL_BACKFILL_SOURCE: "external_backfill";
+export declare const HISTORICAL_VENDOR_SOURCE_MODE: "vendor_historical_backfill_v1";
+export declare const VENDOR_DATASET_RAW_CAPTURE_SCOPE: "vendor_normalized_dataset_file";
+export declare const backfillRequestSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"market-data-vendor-backfill-request/v1">;
+    requestId: z.ZodString;
+    idempotencyKey: z.ZodString;
+    providerPolicy: z.ZodObject<{
+        provider: z.ZodLiteral<"cryptohftdata">;
+        allowedAdapterVersions: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    scope: z.ZodObject<{
+        exchange: z.ZodString;
+        tradingPair: z.ZodString;
+        sourceSymbol: z.ZodString;
+        marketType: z.ZodEnum<{
+            spot: "spot";
+            swap: "swap";
+            future: "future";
+        }>;
+        feed: z.ZodLiteral<"ORDERBOOK">;
+    }, z.core.$strict>;
+    window: z.ZodObject<{
+        startTimeMs: z.ZodNumber;
+        endTimeMs: z.ZodNumber;
+    }, z.core.$strict>;
+    depth: z.ZodNumber;
+    constructionMode: z.ZodEnum<{
+        sampled_top_n_snapshot: "sampled_top_n_snapshot";
+        exact_l2_reconstruction: "exact_l2_reconstruction";
+    }>;
+    requiredClockTargetsMs: z.ZodArray<z.ZodNumber>;
+    maxPriorAsOfLagMs: z.ZodNumber;
+    sourcePolicy: z.ZodEnum<{
+        authoritative_window: "authoritative_window";
+        fill_gaps: "fill_gaps";
+    }>;
+    budgets: z.ZodObject<{
+        maxFiles: z.ZodNumber;
+        maxBytes: z.ZodNumber;
+        maxRows: z.ZodNumber;
+        maxDurationMs: z.ZodNumber;
+        maxBoundaryLookbackMs: z.ZodNumber;
+    }, z.core.$strict>;
+    expectedProduct: z.ZodObject<{
+        packageName: z.ZodLiteral<"@usherlabs/cex-broker">;
+        packageVersion: z.ZodOptional<z.ZodString>;
+        canonicalSchemaVersion: z.ZodString;
+        checksumAlgorithm: z.ZodLiteral<"sha256-canonical-json-v1">;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+type ProvisionalBackfillDomainRequest = z.infer<typeof backfillRequestSchema>;
+export type MarketDataVendorBackfillRequest = ProvisionalBackfillDomainRequest & {
+    attemptId?: string;
+    target?: {
+        environment: string;
+        cluster: string;
+    };
+    coveragePolicy?: CoveragePolicyWire;
+    requiredClock?: RequiredClockWire;
+    initialSelection?: ArchiveSelectionWire;
+    expectedCanonicalSchema?: BackfillRequestWire["expected_canonical_schema"];
+    productPins?: BackfillRequestWire["product_pins"];
+    productionAuthorizationId?: string;
+    wire?: BackfillRequestWire;
+};
+export declare function decodeBackfillRunDocuments(input: {
+    request: unknown;
+    requiredClock: unknown;
+}): MarketDataVendorBackfillRequest;
+type IdempotencyBusinessFields = Omit<MarketDataVendorBackfillRequest, "requestId" | "idempotencyKey">;
+export declare function backfillBusinessFields(request: Omit<MarketDataVendorBackfillRequest, "idempotencyKey"> & {
+    idempotencyKey?: string;
+}): IdempotencyBusinessFields;
+export declare function createBackfillIdempotencyKey(request: Omit<MarketDataVendorBackfillRequest, "idempotencyKey"> & {
+    idempotencyKey?: string;
+}): string;
+export declare function createBackfillIdempotencyKey(request: Omit<BackfillRequestWire, "idempotency_key"> & {
+    idempotency_key?: string;
+}): string;
+export declare function createBackfillIdempotencyKey(request: Record<string, unknown>): string;
+export declare function parseBackfillRequest(value: unknown): MarketDataVendorBackfillRequest;
+export declare const BACKFILL_STATUSES: readonly ["already_covered", "promoted", "capability_unsupported", "credentials_missing", "vendor_fetch_failed", "archive_ingest_failed", "promotion_verification_failed", "post_backfill_coverage_insufficient"];
+export type BackfillStatus = (typeof BACKFILL_STATUSES)[number];
+export type ProviderCapability = {
+    provider: "cryptohftdata";
+    adapterVersion: string;
+    providerExchangeId: string;
+    resolvedSymbol: string;
+};
+export type ProviderObjectEvidence = {
+    identity: string;
+    checksum: string;
+    bytes: number;
+    rows: number;
+};
+export type BackfillArchiveRow = {
+    table: "market_data.cex_order_book_levels" | "market_data.cex_order_book_depth_summary" | "market_data.cex_order_book_capture_promotions" | "market_data.cex_order_book_capture_qualifications" | "market_data.cex_order_book_archive_selections";
+    row: Record<string, unknown>;
+};
+export type ForwarderBatch = {
+    source: typeof EXTERNAL_BACKFILL_SOURCE;
+    deployment_id: string;
+    batch_id: string;
+    rows: BackfillArchiveRow[];
+};
+export type PromotionReceipt = {
+    schemaVersion: typeof BACKFILL_PROMOTION_SCHEMA_VERSION;
+    receiptId: string;
+    requestId: string;
+    idempotencyKey: string;
+    status: "passing";
+    source: typeof EXTERNAL_BACKFILL_SOURCE;
+    provider: "cryptohftdata";
+    adapterVersion: string;
+    captureBundleId: string;
+    exchange: string;
+    tradingPair: string;
+    marketType: "spot" | "swap" | "future";
+    feed: "ORDERBOOK";
+    startTimeMs: number;
+    endTimeMs: number;
+    depth: number;
+    constructionMode: "sampled_top_n_snapshot" | "exact_l2_reconstruction";
+    canonicalSchemaVersion: string;
+    checksumAlgorithm: "sha256-canonical-json-v1";
+    vendorSemanticDigest: string;
+    canonicalSemanticDigest: string;
+    prefixDigest: string;
+    suffixDigest: string;
+    seamVerified: true;
+    coverageVerified: true;
+    datasetObjects: ProviderObjectEvidence[];
+    verificationTimeMs: number;
+};
+export declare const promotionReceiptSchema: z.ZodType<PromotionReceipt>;
+export type BackfillResult = {
+    schemaVersion: typeof BACKFILL_RESULT_SCHEMA_VERSION;
+    requestId: string;
+    idempotencyKey?: string;
+    status: BackfillStatus;
+    reasonCode: string;
+    receipt?: PromotionReceipt;
+    diagnostics?: Record<string, string | number | boolean>;
+};
+export {};

package/dist/helpers/market-data-vendor-backfill/core.d.ts

@@ -0,0 +1,100 @@
+import { type ArchiveSelectionWire, type BackfillArchiveRow, type FinalBackfillStatus, type ForwarderBatch, type MarketDataVendorBackfillRequest, type PromotionReceiptWire, type ProviderCapability, type ProviderObjectEvidence } from "./contracts";
+export type ProviderDataset<Row = unknown> = {
+    objects: ProviderObjectEvidence[];
+    vendorSemanticDigest: string;
+    rows: Row[];
+};
+export type NormalizedBackfill = {
+    captureBundleId: string;
+    objects: ProviderObjectEvidence[];
+    rows: BackfillArchiveRow[];
+    vendorSemanticDigest: string;
+    canonicalSemanticDigest: string;
+};
+export type CandidateVerification = {
+    passed: boolean;
+    captureBundleId: string;
+    canonicalSemanticDigest: string;
+    prefixDigest: string;
+    suffixDigest: string;
+    seamVerified: boolean;
+    coverageVerified: boolean;
+    reasonCode?: string;
+};
+export type ArchiveClusterIdentity = {
+    environment: string;
+    cluster: string;
+};
+export type ProductionForwarderAuthorization = {
+    authorizationId: string;
+    scope: "production";
+    environment: string;
+    cluster: string;
+    expiresAt: string;
+    credentialValidated: true;
+};
+export type ArchivePreflightResolution = {
+    selection: ArchiveSelectionWire;
+    receipts: PromotionReceiptWire[];
+    readerIdentity: ArchiveClusterIdentity;
+    verificationBaseline?: {
+        prefixDigest: string;
+        suffixDigest: string;
+    };
+};
+export type ForwarderPreflightResolution = {
+    forwarderIdentity: ArchiveClusterIdentity;
+    authorization: ProductionForwarderAuthorization;
+};
+/** @deprecated Use ArchivePreflightResolution and its exact selection. */
+export type QualifiedCoverage = {
+    complete: boolean;
+    coverageDigest: string;
+    prefixDigest?: string;
+    suffixDigest?: string;
+};
+export type BackfillDomainOutcome = {
+    status: FinalBackfillStatus;
+    reasonCode: string;
+    reasonSubcode?: string;
+    requestId?: string;
+    idempotencyKey?: string;
+    target?: ArchiveClusterIdentity;
+    selection?: ArchiveSelectionWire;
+    receipt?: PromotionReceiptWire;
+    diagnostics?: Record<string, string | number | boolean>;
+};
+export type BackfillDependencies = {
+    archive: {
+        resolveSelection(request: MarketDataVendorBackfillRequest): Promise<ArchivePreflightResolution>;
+        verifyCandidate(request: MarketDataVendorBackfillRequest, normalized: NormalizedBackfill, captureBundleId: string, baseline: ArchivePreflightResolution): Promise<CandidateVerification>;
+    };
+    providers: {
+        capabilityFor(request: MarketDataVendorBackfillRequest): ProviderCapability | undefined;
+        acquire(request: MarketDataVendorBackfillRequest, capability: ProviderCapability, credential: unknown): Promise<ProviderDataset>;
+        normalize(request: MarketDataVendorBackfillRequest, capability: ProviderCapability, dataset: ProviderDataset, captureBundleId: string): Promise<NormalizedBackfill>;
+    };
+    credentials: {
+        resolve(provider: "cryptohftdata"): Promise<unknown | undefined>;
+    };
+    forwarder: {
+        preflight(input: {
+            authorizationId: string;
+            target: ArchiveClusterIdentity;
+        }): Promise<ForwarderPreflightResolution>;
+        submit(batch: ForwarderBatch): Promise<{
+            ok: boolean;
+            inserted: number;
+        }>;
+    };
+    clock: {
+        nowMs(): number;
+    };
+    retry?: {
+        maxAttempts: number;
+        wait?: (completedAttempt: number) => Promise<void>;
+    };
+    log?: (event: string, fields: Record<string, unknown>) => void;
+};
+export declare function createMarketDataVendorBackfillDependencies(dependencies: BackfillDependencies): BackfillDependencies;
+export declare function runMarketDataVendorBackfill(input: unknown, dependencies: BackfillDependencies): Promise<BackfillDomainOutcome>;