@usherlabs/cex-broker 0.2.51 → 0.3.0

package/dist/commands/cli.js

@@ -315838,6 +315838,22 @@ import {
 import { basename, dirname } from "node:path";
 var EXPORT_CHUNK_BYTES = 8 * 1024 * 1024;
 var SHA256_RECEIPT_PATTERN = /^([0-9a-f]{64}) {2}(.+)\n$/;
+function sha256File(path) {
+  const hash4 = createHash3("sha256");
+  const fd2 = openSync(path, "r");
+  try {
+    const chunk = Buffer.alloc(EXPORT_CHUNK_BYTES);
+    for (;; ) {
+      const read = readSync(fd2, chunk, 0, chunk.length, null);
+      if (read === 0)
+        break;
+      hash4.update(chunk.subarray(0, read));
+    }
+  } finally {
+    closeSync(fd2);
+  }
+  return hash4.digest("hex");
+}
 
 class DeadLetterJournalExportError extends Error {
   constructor(message, options) {
@@ -315871,6 +315887,9 @@ function exportDeadLetterJournal(journalPath, exportPath) {
       if (match?.[1] === undefined || match[2] !== basename(exportPath)) {
         throw new Error("export receipt is malformed");
       }
+      if (sha256File(exportPath) !== match[1]) {
+        throw new Error("export digest does not match receipt");
+      }
     } catch (error) {
       throw new DeadLetterJournalExportError("Dead-letter journal export target is incomplete or unverifiable", { cause: error });
     }
@@ -317211,6 +317230,16 @@ function withTimeout(promise, timeoutMs, label) {
   return Promise.race([promise, expiry]).finally(() => clearTimeout(timer));
 }
 var ALL_CURRENCIES_CODE = "*";
+var BINANCE_UNLOCK_PROGRESS_SOURCE = {
+  venue: "binance",
+  endpoint: "GET /sapi/v1/capital/deposit/hisrec",
+  fields: {
+    status: "info.status",
+    confirmTimes: "info.confirmTimes",
+    unlockConfirm: "info.unlockConfirm",
+    completeTime: "info.completeTime"
+  }
+};
 function depositTimestamp(record) {
   const observedAt = depositField(record, [
     "timestamp",
@@ -317223,12 +317252,185 @@ function depositTimestamp(record) {
   const timestamp = typeof observedAt === "number" ? observedAt : typeof observedAt === "string" ? Date.parse(observedAt) : Number.NaN;
   return Number.isFinite(timestamp) ? timestamp : undefined;
 }
-function archivedDepositStatus(exchangeId, record) {
-  const rawStatus = asRecord(record.info)?.status;
-  if (exchangeId?.toLowerCase() === "binance" && String(rawStatus ?? "").trim() === "6") {
-    return "credited_not_withdrawable";
+function parseNonNegativeInteger(value) {
+  if (typeof value === "number") {
+    return Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+  }
+  if (typeof value !== "string") {
+    return;
+  }
+  const trimmed = value.trim();
+  if (!/^\d+$/.test(trimmed)) {
+    return;
+  }
+  const parsed = Number(trimmed);
+  return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : undefined;
+}
+function parseConfirmTimes(value) {
+  if (value === undefined || value === null) {
+    return { reason: "missing_confirmTimes" };
+  }
+  let currentValue;
+  let creditRequiredValue;
+  if (typeof value === "string") {
+    const match = /^(\d+)\s*\/\s*(\d+)$/.exec(value.trim());
+    if (!match) {
+      return { reason: "invalid_confirmTimes" };
+    }
+    currentValue = match[1];
+    creditRequiredValue = match[2];
+  } else {
+    const record = asRecord(value);
+    if (!record) {
+      return { reason: "invalid_confirmTimes" };
+    }
+    currentValue = record.current;
+    creditRequiredValue = record.credit_required;
+  }
+  const current = parseNonNegativeInteger(currentValue);
+  const creditRequired = parseNonNegativeInteger(creditRequiredValue);
+  if (current === undefined || creditRequired === undefined) {
+    return { reason: "invalid_confirmTimes" };
   }
-  return normalizeCcxtTransactionForArchive(record).status;
+  return { current, creditRequired, reason: null };
+}
+function parseOptionalNonNegativeInteger(value, fieldName) {
+  if (value === undefined || value === null) {
+    return { value: undefined, reason: null };
+  }
+  const parsed = parseNonNegativeInteger(value);
+  return parsed === undefined ? { value: undefined, reason: `invalid_${fieldName}` } : { value: parsed, reason: null };
+}
+function parseBinanceUnlockProgress(record) {
+  const info = asRecord(record.info);
+  const nativeStatus = parseNonNegativeInteger(info?.status);
+  const confirmations = parseConfirmTimes(info?.confirmTimes);
+  const unlockRequired = parseOptionalNonNegativeInteger(info?.unlockConfirm, "unlockConfirm");
+  const completeTime = parseOptionalNonNegativeInteger(info?.completeTime, "completeTime");
+  let quality = "valid";
+  let reason = null;
+  if (nativeStatus === undefined) {
+    quality = "unknown";
+    reason = "missing_or_invalid_status";
+  } else if (confirmations.reason !== null) {
+    quality = "unknown";
+    reason = confirmations.reason;
+  } else if (unlockRequired.reason !== null) {
+    quality = "unknown";
+    reason = unlockRequired.reason;
+  } else if (completeTime.reason !== null) {
+    quality = "unknown";
+    reason = completeTime.reason;
+  }
+  let state = "unknown";
+  switch (nativeStatus) {
+    case 0:
+      state = "pending";
+      break;
+    case 1:
+      if (quality === "valid" && confirmations.current !== undefined && unlockRequired.value !== undefined && confirmations.current >= unlockRequired.value) {
+        state = "ok";
+      } else if (quality === "valid") {
+        state = "credited_not_withdrawable";
+      }
+      break;
+    case 2:
+    case 7:
+      state = "failed";
+      break;
+    case 6:
+      state = "credited_not_withdrawable";
+      break;
+    case 8:
+      state = "pending";
+      break;
+    default:
+      quality = "unknown";
+      reason = "unsupported_status";
+      break;
+  }
+  return {
+    version: 1,
+    state,
+    progress_state: quality,
+    reason,
+    native_status: nativeStatus ?? null,
+    current: confirmations.current ?? null,
+    credit_required: confirmations.creditRequired ?? null,
+    unlock_required: unlockRequired.value ?? null,
+    complete_time: completeTime.value ?? null,
+    observed_at: new Date().toISOString(),
+    source: BINANCE_UNLOCK_PROGRESS_SOURCE
+  };
+}
+function unlockProgressKey(progress) {
+  return JSON.stringify({
+    version: progress.version,
+    state: progress.state,
+    progress_state: progress.progress_state,
+    reason: progress.reason,
+    native_status: progress.native_status,
+    current: progress.current,
+    credit_required: progress.credit_required,
+    unlock_required: progress.unlock_required,
+    complete_time: progress.complete_time
+  });
+}
+function progressWatermark(progress, previous) {
+  if (progress.progress_state !== "valid" || progress.current === null || progress.credit_required === null || progress.unlock_required === null) {
+    return previous;
+  }
+  return {
+    current: Math.max(previous?.current ?? 0, progress.current),
+    credit_required: progress.credit_required,
+    unlock_required: progress.unlock_required
+  };
+}
+function classifyBinanceDeposit(record, previous) {
+  let progress = parseBinanceUnlockProgress(record);
+  let highWatermark = previous?.highWatermark;
+  if (progress.progress_state === "valid" && progress.current !== null && progress.credit_required !== null && progress.unlock_required !== null && previous?.highWatermark !== undefined && (progress.current < previous.highWatermark.current || progress.credit_required !== previous.highWatermark.credit_required || progress.unlock_required !== previous.highWatermark.unlock_required)) {
+    progress = {
+      ...progress,
+      state: "unknown",
+      progress_state: "contradictory",
+      reason: "confirmation_progress_regressed_or_requirement_changed"
+    };
+  } else {
+    highWatermark = progressWatermark(progress, previous?.highWatermark);
+  }
+  return {
+    archiveStatus: progress.state,
+    holdCursor: progress.state === "pending" || progress.state === "credited_not_withdrawable" || progress.state === "unknown",
+    unlockProgress: progress,
+    progressKey: unlockProgressKey(progress),
+    highWatermark
+  };
+}
+function classifyDeposit(exchangeId, record, previous) {
+  if (exchangeId?.toLowerCase() === "binance") {
+    return classifyBinanceDeposit(record, previous);
+  }
+  const archiveStatus = normalizeCcxtTransactionForArchive(record).status ?? "";
+  const status = normalizeDepositStatus(depositField(record, ["status", "state"]));
+  return {
+    archiveStatus,
+    holdCursor: archiveStatus === "credited_not_withdrawable" || status === "pending",
+    progressKey: JSON.stringify({ status: archiveStatus })
+  };
+}
+function depositIdentity(input) {
+  if (input.externalId === undefined && input.txid === undefined) {
+    return;
+  }
+  return JSON.stringify({
+    exchange: input.exchangeId,
+    account: input.accountSelector,
+    coin: input.coin === undefined ? "" : String(input.coin),
+    network: input.network === undefined ? "" : String(input.network),
+    external_id: input.externalId ?? "",
+    txid: input.txid ?? ""
+  });
 }
 function nextDepositCursor(deposits, currentSince, depositsLimit, exchangeId) {
   if (deposits.length >= depositsLimit) {
@@ -317242,9 +317444,8 @@ function nextDepositCursor(deposits, currentSince, depositsLimit, exchangeId) {
       return currentSince;
     }
     const timestamp = depositTimestamp(record);
-    const archiveStatus = archivedDepositStatus(exchangeId, record);
-    const status = normalizeDepositStatus(depositField(record, ["status", "state"]));
-    const isPending = archiveStatus === "credited_not_withdrawable" || status === "pending";
+    const classification = classifyDeposit(exchangeId, record);
+    const isPending = classification.holdCursor;
     if (timestamp === undefined) {
       if (isPending) {
         return currentSince;
@@ -317364,7 +317565,8 @@ class DepositArchivePoller {
       if (!record) {
         continue;
       }
-      const assetSymbol = depositField(record, ["currency", "code", "asset"]);
+      const info = asRecord(record.info);
+      const assetSymbol = depositField(record, ["currency", "code", "asset"]) ?? info?.coin;
       const amount = depositField(record, ["amount"]);
       const address = depositField(record, [
         "address",
@@ -317373,8 +317575,21 @@ class DepositArchivePoller {
         "destination"
       ]);
       const txid = depositField(record, ["txid", "txId", "tx_hash", "txHash"]);
-      const network = depositField(record, ["network", "chain"]);
-      const archiveStatus = archivedDepositStatus(target.exchangeId, record);
+      const network = depositField(record, ["network", "chain"]) ?? info?.network;
+      const depositTxid = txid === undefined ? undefined : String(txid);
+      const identity = depositIdentity({
+        exchangeId: target.exchangeId,
+        accountSelector: target.account.label,
+        coin: assetSymbol,
+        network,
+        externalId: depositTxid,
+        txid: depositTxid
+      });
+      const lastArchived = identity === undefined ? undefined : this.#lastArchivedByTarget.get(key)?.get(identity);
+      const classification = classifyDeposit(target.exchangeId, record, lastArchived);
+      if (lastArchived && lastArchived.status === classification.archiveStatus && lastArchived.progressKey === classification.progressKey) {
+        continue;
+      }
       const creditedAt = depositField(record, [
         "creditedAt",
         "credited_at",
@@ -317383,11 +317598,7 @@ class DepositArchivePoller {
         "timestamp",
         "datetime"
       ]);
-      const depositTxid = txid === undefined ? undefined : String(txid);
-      const lastArchived = depositTxid === undefined ? undefined : this.#lastArchivedByTarget.get(key)?.get(depositTxid);
-      if (lastArchived && lastArchived.status === archiveStatus) {
-        continue;
-      }
+      const payload = classification.unlockProgress === undefined ? record : { ...record, unlock_progress: classification.unlockProgress };
       this.params.archiver.enqueue(buildTransferEventArchiveRow({
         tags: buildCommonArchiveTags({
           deploymentId: this.params.archiver.getDeploymentId(),
@@ -317398,25 +317609,27 @@ class DepositArchivePoller {
         transfer: {
           eventKind: "deposit",
           lifecycleAction: "observe_deposit",
-          status: archiveStatus,
+          status: classification.archiveStatus,
           amount: amount === undefined ? undefined : String(amount),
           address: address === undefined ? undefined : String(address),
           network: network === undefined ? undefined : String(network),
           externalId: depositTxid,
           txid: depositTxid,
           exchangeTimestamp: normalizeTimestamp(creditedAt),
-          payload: record
+          payload
         }
       }));
-      if (depositTxid !== undefined) {
+      if (identity !== undefined) {
         let targetDeposits2 = this.#lastArchivedByTarget.get(key);
         if (!targetDeposits2) {
           targetDeposits2 = new Map;
           this.#lastArchivedByTarget.set(key, targetDeposits2);
         }
-        targetDeposits2.set(depositTxid, {
-          status: archiveStatus,
-          timestamp: depositTimestamp(record)
+        targetDeposits2.set(identity, {
+          status: classification.archiveStatus,
+          timestamp: depositTimestamp(record),
+          progressKey: classification.progressKey,
+          highWatermark: classification.highWatermark
         });
       }
       archived += 1;
@@ -317584,10 +317797,7 @@ import { createHash as createHash4 } from "node:crypto";
 var MARKET_CAPTURE_SCHEMA_VERSION = "1.0.0";
 var CHECKSUM_ALGORITHM = "sha256-canonical-json-v1";
 var ARCHIVE_SOURCES = ["broker_read", "broker_write"];
-var MARKET_ARCHIVE_SOURCES = [
-  ...ARCHIVE_SOURCES,
-  "external_backfill"
-];
+var MARKET_ARCHIVE_SOURCES = ARCHIVE_SOURCES;
 var CAPTURE_FEEDS = [
   "ORDERBOOK",
   "TICKER",
@@ -317601,15 +317811,12 @@ var SOURCE_MODES = [
   "broker_bootstrap_fetch_v1",
   "external_ccxt_fallback_v1",
   "external_hummingbot_fallback_v1",
-  "legacy_migration_v1",
-  "historical_vendor_orderbook_v1",
-  "vendor_historical_backfill_v1"
+  "legacy_migration_v1"
 ];
 var RAW_CAPTURE_SCOPES = [
   "ccxt_normalized_object",
   "broker_visible_payload",
-  "exchange_wire_frame",
-  "vendor_normalized_dataset_file"
+  "exchange_wire_frame"
 ];
 var CHECKSUM_FIELDS = new Set([
   "normalized_row_checksum",
@@ -317798,6 +318005,9 @@ function createRawCapture(context2, input) {
     checksumAlgorithm: context2.checksumAlgorithm
   };
 }
+function projectRawCapturePayload(rawCapture, redactedPayload) {
+  return { ...rawCapture, redactedPayload };
+}
 function captureCoreFields(context2, rawCapture) {
   assertCaptureContext(context2);
   return {
@@ -318374,14 +318584,20 @@ function resolveConservativeOrderBookAcquisitionProfile(input) {
       id: `${exchange}:conservative:default`,
       upstreamLimit: undefined,
       guaranteedRetainedDepth: undefined,
-      coalescingSupported: false
+      coalescingSupported: false,
+      bidExhaustionEvidence: false,
+      askExhaustionEvidence: false,
+      exhaustionEvidenceValidated: true
     };
   }
   return {
     id: `${exchange}:conservative:limit:${input.requestedDepth}`,
     upstreamLimit: input.requestedDepth,
     guaranteedRetainedDepth: input.requestedDepth,
-    coalescingSupported: false
+    coalescingSupported: false,
+    bidExhaustionEvidence: false,
+    askExhaustionEvidence: false,
+    exhaustionEvidenceValidated: true
   };
 }
 function resolveOrderBookAcquisitionProfile(input) {
@@ -318393,7 +318609,10 @@ function resolveOrderBookAcquisitionProfile(input) {
       id: candidateProfileId,
       upstreamLimit: VERIFIED_PROFILE_DEPTH,
       guaranteedRetainedDepth: VERIFIED_PROFILE_DEPTH,
-      coalescingSupported: true
+      coalescingSupported: true,
+      bidExhaustionEvidence: false,
+      askExhaustionEvidence: false,
+      exhaustionEvidenceValidated: true
     };
   }
   return resolveConservativeOrderBookAcquisitionProfile(input);
@@ -318543,7 +318762,63 @@ class PublicFeedSubscriberBuffer {
     this.#bytes = 0;
   }
 }
+// src/helpers/market-data-archive/orderbook-depth.ts
+var DEFAULT_ORDERBOOK_ARCHIVE_DEPTH_LIMIT = 25;
+var MAX_ORDERBOOK_ARCHIVE_DEPTH_LIMIT = 500;
+var MAX_ORDERBOOK_MEASUREMENT_BANDS = 64;
+var MAX_ORDERBOOK_MEASUREMENT_BAND_BPS = 1e4;
+var DEFAULT_ORDERBOOK_MEASUREMENT_BANDS_BPS = [10, 25, 50, 100];
+function parseBoundedDepth(raw, field) {
+  if (!/^[1-9]\d*$/.test(raw)) {
+    throw new Error(`${field} must be an integer between 1 and 500`);
+  }
+  const parsed = Number(raw);
+  if (!Number.isSafeInteger(parsed) || parsed > MAX_ORDERBOOK_ARCHIVE_DEPTH_LIMIT) {
+    throw new Error(`${field} must be an integer between 1 and 500`);
+  }
+  return parsed;
+}
+function getOrderbookArchiveDepthLimit() {
+  const raw = process.env.CEX_BROKER_ORDERBOOK_ARCHIVE_DEPTH_LIMIT?.trim();
+  if (!raw) {
+    return DEFAULT_ORDERBOOK_ARCHIVE_DEPTH_LIMIT;
+  }
+  return parseBoundedDepth(raw, "CEX_BROKER_ORDERBOOK_ARCHIVE_DEPTH_LIMIT");
+}
+function normalizeOrderbookMeasurementBandsBps(input) {
+  const bands = input ?? DEFAULT_ORDERBOOK_MEASUREMENT_BANDS_BPS;
+  if (bands.length === 0) {
+    throw new Error("ORDERBOOK measurement bands must not be empty");
+  }
+  if (bands.length > MAX_ORDERBOOK_MEASUREMENT_BANDS) {
+    throw new Error(`ORDERBOOK measurement bands must contain at most ${MAX_ORDERBOOK_MEASUREMENT_BANDS} entries`);
+  }
+  for (const band of bands) {
+    if (!Number.isSafeInteger(band) || band <= 0 || band > MAX_ORDERBOOK_MEASUREMENT_BAND_BPS) {
+      throw new Error("ORDERBOOK measurement bands must be integer basis points in 1..10000");
+    }
+  }
+  const normalized = [...new Set(bands)].sort((left, right) => left - right);
+  if (normalized.length > MAX_ORDERBOOK_MEASUREMENT_BANDS) {
+    throw new Error(`ORDERBOOK measurement bands must contain at most ${MAX_ORDERBOOK_MEASUREMENT_BANDS} unique entries`);
+  }
+  return normalized;
+}
+function getOrderbookMeasurementBandsBps() {
+  const raw = process.env.CEX_BROKER_ORDERBOOK_MEASUREMENT_BANDS_BPS?.trim();
+  if (!raw) {
+    return [...DEFAULT_ORDERBOOK_MEASUREMENT_BANDS_BPS];
+  }
+  const parts = raw.split(",").map((entry) => entry.trim());
+  if (parts.some((entry) => !/^[1-9]\d*$/.test(entry))) {
+    throw new Error("CEX_BROKER_ORDERBOOK_MEASUREMENT_BANDS_BPS must be a comma-separated list of positive integers");
+  }
+  return normalizeOrderbookMeasurementBandsBps(parts.map(Number));
+}
+
 // src/helpers/market-data-archive/canonical-orderbook.ts
+var ORDERBOOK_SUMMARY_SCHEMA_VERSION = "2.0.0";
+
 class OrderBookValidationError extends Error {
   reason;
   constructor(reason) {
@@ -318569,38 +318844,70 @@ function parseSequence(value) {
   }
   return parsed.toString(10);
 }
-function validateSide(side, levels, depthLimit) {
+function validatePositiveInteger(value, field, maximum = Number.MAX_SAFE_INTEGER) {
+  if (!Number.isSafeInteger(value) || value <= 0 || value > maximum) {
+    throw new OrderBookValidationError(`${field} must be a positive integer${maximum === 500 ? " between 1 and 500" : ""}`);
+  }
+}
+function validateSide(side, levels) {
   if (levels.length === 0) {
     throw new OrderBookValidationError(`${side} side is missing`);
   }
-  const retained = levels.slice(0, depthLimit);
-  for (let index2 = 0;index2 < retained.length; index2 += 1) {
-    const entry = retained[index2];
+  const validated = [];
+  for (let index2 = 0;index2 < levels.length; index2 += 1) {
+    const entry = levels[index2];
     const price = entry?.[0];
     const amount = entry?.[1];
     if (!Array.isArray(entry) || entry.length < 2 || price === undefined || amount === undefined || !Number.isFinite(price) || !Number.isFinite(amount) || price <= 0 || amount <= 0) {
       throw new OrderBookValidationError(`${side} level ${index2} has a non-positive or non-finite price/amount`);
     }
     if (index2 > 0) {
-      const previous = retained[index2 - 1]?.[0];
+      const previous = validated[index2 - 1]?.price;
       if (previous === undefined || (side === "bid" ? price >= previous : price <= previous)) {
         throw new OrderBookValidationError(`${side} levels are not strictly ${side === "bid" ? "descending" : "ascending"}`);
       }
     }
+    validated.push({ price, amount });
   }
-  return retained.map(([price, amount]) => ({
-    price,
-    amount
-  }));
+  return validated;
 }
-function normalizedBands(input) {
-  const bands = input ?? [10, 25, 50, 100];
-  for (const band of bands) {
-    if (!Number.isFinite(band) || band <= 0 || !Number.isInteger(band)) {
-      throw new OrderBookValidationError("measurement bands must be positive integer basis points");
+function validateMetadata(metadata, observedBids, observedAsks) {
+  if (!metadata.captureProfileId.trim()) {
+    throw new OrderBookValidationError("capture_profile_id must not be empty");
+  }
+  validatePositiveInteger(metadata.effectiveCadenceMs, "effective_cadence_ms");
+  if (metadata.requestedUpstreamDepth !== null) {
+    validatePositiveInteger(metadata.requestedUpstreamDepth, "requested_upstream_depth", 500);
+  }
+  validatePositiveInteger(metadata.observedBidCount, "observed_bid_count");
+  validatePositiveInteger(metadata.observedAskCount, "observed_ask_count");
+  if (metadata.observedBidCount !== observedBids.length) {
+    throw new OrderBookValidationError("observed_bid_count does not match the complete observation");
+  }
+  if (metadata.observedAskCount !== observedAsks.length) {
+    throw new OrderBookValidationError("observed_ask_count does not match the complete observation");
+  }
+  const farthestBid = observedBids.at(-1)?.price;
+  const farthestAsk = observedAsks.at(-1)?.price;
+  if (!Number.isFinite(metadata.observedFarthestBid) || metadata.observedFarthestBid <= 0 || metadata.observedFarthestBid !== farthestBid) {
+    throw new OrderBookValidationError("observed_farthest_bid does not match the complete observation");
+  }
+  if (!Number.isFinite(metadata.observedFarthestAsk) || metadata.observedFarthestAsk <= 0 || metadata.observedFarthestAsk !== farthestAsk) {
+    throw new OrderBookValidationError("observed_farthest_ask does not match the complete observation");
+  }
+  for (const [side, evidence] of [
+    ["bid", metadata.exhaustionEvidence.bid],
+    ["ask", metadata.exhaustionEvidence.ask]
+  ]) {
+    if (evidence.validated !== true || typeof evidence.exhausted !== "boolean" || !evidence.source.trim()) {
+      throw new OrderBookValidationError(`${side} exhaustion evidence must be validated and source-bound`);
     }
   }
-  return [...new Set(bands)].sort((left, right) => left - right);
+  try {
+    return normalizeOrderbookMeasurementBandsBps(metadata.measurementBandsBps);
+  } catch (error) {
+    throw new OrderBookValidationError(error instanceof Error ? error.message : "invalid measurement bands");
+  }
 }
 function checksumRow(row) {
   return { ...row, normalized_row_checksum: sha256Canonical(row) };
@@ -318611,20 +318918,33 @@ function commonEvidenceFields(context2, rawCapture, input) {
     source_time_ms: input.eventTimeMs,
     received_time_ms: input.receivedTimeMs,
     snapshot_id: input.snapshotId,
-    construction_mode: input.constructionMode,
+    construction_mode: "sampled_top_n_snapshot",
     gap_policy: "record_gap",
     depth_limit: input.depthLimit,
     sequence: input.sequence,
     exact_l2_reconstruction_complete: 0
   };
 }
+function sideBandEvidence(input) {
+  const farthest = input.levels.at(-1)?.price;
+  const depths = input.boundaries.map((boundary) => input.levels.filter(({ price }) => input.side === "bid" ? price >= boundary : price <= boundary).reduce((sum3, { amount }) => sum3 + amount, 0));
+  const statuses = input.boundaries.map((boundary) => {
+    const boundaryReached = input.side === "bid" ? farthest <= boundary : farthest >= boundary;
+    return boundaryReached || input.exhausted ? "exact" : "censored";
+  });
+  return { depths, statuses };
+}
 function buildCanonicalOrderBookRows(input) {
-  if (!Number.isSafeInteger(input.depthLimit) || input.depthLimit <= 0 || input.depthLimit > 500) {
-    throw new OrderBookValidationError("depth limit must be an integer between 1 and 500");
-  }
+  validatePositiveInteger(input.depthLimit, "depth limit", 500);
   if (input.context.feed !== "ORDERBOOK") {
     throw new OrderBookValidationError("capture context feed is not ORDERBOOK");
   }
+  if (input.context.schemaVersion !== "1.0.0") {
+    throw new OrderBookValidationError("ORDERBOOK raw and level capture schema must be 1.0.0");
+  }
+  if (!input.context.provenanceComplete) {
+    throw new OrderBookValidationError("summary v2 requires complete live provenance");
+  }
   if (input.constructionMode === "exact_l2_reconstruction") {
     throw new OrderBookValidationError("exact L2 requires a complete continuity proof and is unsupported");
   }
@@ -318639,13 +318959,18 @@ function buildCanonicalOrderBookRows(input) {
   if (receivedTimeMs < eventTimeMs) {
     throw new OrderBookValidationError("received timestamp precedes source timestamp");
   }
-  const bids = validateSide("bid", input.snapshot.bids, input.depthLimit);
-  const asks = validateSide("ask", input.snapshot.asks, input.depthLimit);
-  const bestBid = bids[0];
-  const bestAsk = asks[0];
+  const observedBids = validateSide("bid", input.snapshot.bids);
+  const observedAsks = validateSide("ask", input.snapshot.asks);
+  const bestBid = observedBids[0];
+  const bestAsk = observedAsks[0];
   if (bestBid.price >= bestAsk.price) {
     throw new OrderBookValidationError("book is crossed or locked");
   }
+  const bands = validateMetadata(input.archiveMetadata, observedBids, observedAsks);
+  const bids = observedBids.slice(0, input.depthLimit);
+  const asks = observedAsks.slice(0, input.depthLimit);
+  const retainedFarthestBid = bids.at(-1);
+  const retainedFarthestAsk = asks.at(-1);
   const sequence = parseSequence(input.snapshot.sequence);
   const midPrice = (bestBid.price + bestAsk.price) / 2;
   const spread2 = bestAsk.price - bestBid.price;
@@ -318665,8 +318990,7 @@ function buildCanonicalOrderBookRows(input) {
     sequence,
     depthLimit: input.depthLimit,
     eventTimeMs,
-    receivedTimeMs,
-    constructionMode: input.constructionMode ?? "sampled_top_n_snapshot"
+    receivedTimeMs
   });
   const levels = [
     ["bid", bids],
@@ -318684,17 +319008,34 @@ function buildCanonicalOrderBookRows(input) {
     });
     return { table: "market_data.cex_order_book_levels", row };
   }));
-  const bands = normalizedBands(input.measurementBandsBps);
-  const bidDepth = bands.map((band) => {
-    const minimumPrice = bestBid.price * (1 - band / 1e4);
-    return bids.filter(({ price }) => price >= minimumPrice).reduce((sum3, { amount }) => sum3 + amount, 0);
+  const bidBoundaries = bands.map((band) => midPrice * (1 - band / 1e4));
+  const askBoundaries = bands.map((band) => midPrice * (1 + band / 1e4));
+  const bidEvidence = sideBandEvidence({
+    levels: observedBids,
+    boundaries: bidBoundaries,
+    side: "bid",
+    exhausted: input.archiveMetadata.exhaustionEvidence.bid.exhausted
   });
-  const askDepth = bands.map((band) => {
-    const maximumPrice = bestAsk.price * (1 + band / 1e4);
-    return asks.filter(({ price }) => price <= maximumPrice).reduce((sum3, { amount }) => sum3 + amount, 0);
+  const askEvidence = sideBandEvidence({
+    levels: observedAsks,
+    boundaries: askBoundaries,
+    side: "ask",
+    exhausted: input.archiveMetadata.exhaustionEvidence.ask.exhausted
   });
   const summaryRow = checksumRow({
     ...common,
+    schema_version: ORDERBOOK_SUMMARY_SCHEMA_VERSION,
+    capture_profile_id: input.archiveMetadata.captureProfileId,
+    effective_cadence_ms: input.archiveMetadata.effectiveCadenceMs,
+    requested_upstream_depth: input.archiveMetadata.requestedUpstreamDepth,
+    observed_bid_count: input.archiveMetadata.observedBidCount,
+    observed_ask_count: input.archiveMetadata.observedAskCount,
+    observed_farthest_bid: input.archiveMetadata.observedFarthestBid,
+    observed_farthest_ask: input.archiveMetadata.observedFarthestAsk,
+    retained_farthest_bid: retainedFarthestBid.price,
+    retained_farthest_ask: retainedFarthestAsk.price,
+    bid_exhausted: input.archiveMetadata.exhaustionEvidence.bid.exhausted ? 1 : 0,
+    ask_exhausted: input.archiveMetadata.exhaustionEvidence.ask.exhausted ? 1 : 0,
     best_bid: bestBid.price,
     best_ask: bestAsk.price,
     best_bid_amount: bestBid.amount,
@@ -318706,8 +319047,12 @@ function buildCanonicalOrderBookRows(input) {
     bid_level_count: bids.length,
     ask_level_count: asks.length,
     measurement_bands_bps: bands,
-    bid_depth_by_band: bidDepth,
-    ask_depth_by_band: askDepth
+    bid_boundary_price_by_band: bidBoundaries,
+    ask_boundary_price_by_band: askBoundaries,
+    bid_depth_by_band: bidEvidence.depths,
+    ask_depth_by_band: askEvidence.depths,
+    bid_status_by_band: bidEvidence.statuses,
+    ask_status_by_band: askEvidence.statuses
   });
   return {
     snapshotId,
@@ -318837,21 +319182,6 @@ class OhlcvBarTracker {
   }
 }
 
-// src/helpers/market-data-archive/orderbook-depth.ts
-var DEFAULT_ORDERBOOK_ARCHIVE_DEPTH_LIMIT = 25;
-var MAX_ORDERBOOK_ARCHIVE_DEPTH_LIMIT = 500;
-function getOrderbookArchiveDepthLimit() {
-  const raw = process.env.CEX_BROKER_ORDERBOOK_ARCHIVE_DEPTH_LIMIT;
-  if (!raw) {
-    return DEFAULT_ORDERBOOK_ARCHIVE_DEPTH_LIMIT;
-  }
-  const parsed = Number.parseInt(raw, 10);
-  if (!Number.isFinite(parsed) || parsed <= 0) {
-    return DEFAULT_ORDERBOOK_ARCHIVE_DEPTH_LIMIT;
-  }
-  return Math.min(parsed, MAX_ORDERBOOK_ARCHIVE_DEPTH_LIMIT);
-}
-
 // src/helpers/market-data-archive/parse-stream.ts
 function isFiniteNumber2(value) {
   return typeof value === "number" && Number.isFinite(value);
@@ -318975,13 +319305,17 @@ function legacyMarketFields(context2, rawCapture) {
 function legacyDecimal8(value) {
   return value === undefined ? undefined : Number(value.toFixed(8));
 }
-function buildCanonicalCexStreamEventRow(context2, rawCapture) {
+function buildCanonicalCexStreamEventRow(context2, rawCapture, options) {
+  const payloadEncoding = options?.payloadEncoding ?? "canonical_json_v1";
+  if (payloadEncoding === "orderbook_metadata_only_v1" && context2.feed !== "ORDERBOOK") {
+    throw new Error("Metadata-only raw encoding requires an ORDERBOOK context");
+  }
   const row = withNormalizedChecksum({
     ...captureCoreFields(context2, rawCapture),
     ...legacyMarketFields(context2, rawCapture),
     stream_type: context2.feed,
     event_time_ms: rawCapture.eventTimeMs,
-    payload_encoding: "canonical_json_v1",
+    payload_encoding: payloadEncoding,
     payload_json: canonicalSerialize(rawCapture.redactedPayload)
   });
   return { table: "market_data.cex_stream_events", row };
@@ -319125,7 +319459,13 @@ function archiveOrderbookInBackground(archiver, otelMetrics, input, options) {
   queueMicrotask(() => {
     try {
       const context2 = resolveCaptureContext(archiver, input, "ORDERBOOK", options?.sourceMode ?? "broker_live_sampling_v1");
-      const rawCapture = createRawCapture(context2, {
+      const depthLimit = options?.depthLimit ?? getOrderbookArchiveDepthLimit();
+      const measurementBandsBps = normalizeOrderbookMeasurementBandsBps(input.archiveMetadata.measurementBandsBps);
+      const archiveMetadata = {
+        ...input.archiveMetadata,
+        measurementBandsBps
+      };
+      const completeRawCapture = createRawCapture(context2, {
         payload: input.snapshot,
         eventTimeMs: input.snapshot.timestamp,
         receivedTimeMs: input.snapshot.receivedTimestamp,
@@ -319134,10 +319474,29 @@ function archiveOrderbookInBackground(archiver, otelMetrics, input, options) {
       const canonical = buildCanonicalOrderBookRows({
         context: context2,
         snapshot: input.snapshot,
-        rawCapture,
-        depthLimit: options?.depthLimit ?? getOrderbookArchiveDepthLimit()
+        rawCapture: completeRawCapture,
+        depthLimit,
+        archiveMetadata
       });
-      archiver.enqueue(buildCanonicalCexStreamEventRow(context2, rawCapture));
+      const rawMetadata = {
+        capture_profile_id: archiveMetadata.captureProfileId,
+        effective_cadence_ms: archiveMetadata.effectiveCadenceMs,
+        requested_upstream_depth: archiveMetadata.requestedUpstreamDepth,
+        archive_depth_limit: depthLimit,
+        observed_bid_count: archiveMetadata.observedBidCount,
+        observed_ask_count: archiveMetadata.observedAskCount,
+        observed_farthest_bid: canonicalDecimal(archiveMetadata.observedFarthestBid),
+        observed_farthest_ask: canonicalDecimal(archiveMetadata.observedFarthestAsk),
+        bid_exhausted: archiveMetadata.exhaustionEvidence.bid.exhausted,
+        ask_exhausted: archiveMetadata.exhaustionEvidence.ask.exhausted,
+        retained_bid_count: canonical.levels.filter(({ row }) => row.side === "bid").length,
+        retained_ask_count: canonical.levels.filter(({ row }) => row.side === "ask").length,
+        measurement_bands_bps: measurementBandsBps
+      };
+      const storedRawCapture = projectRawCapturePayload(completeRawCapture, rawMetadata);
+      archiver.enqueue(buildCanonicalCexStreamEventRow(context2, storedRawCapture, {
+        payloadEncoding: "orderbook_metadata_only_v1"
+      }));
       for (const row of canonical.levels)
         archiver.enqueue(row);
       archiver.enqueue(canonical.summary);
@@ -319259,6 +319618,9 @@ function archiveTickerInBackground(archiver, otelMetrics, input) {
   });
 }
 function archiveCexStreamEventInBackground(archiver, otelMetrics, input) {
+  if (input.streamType === "ORDERBOOK") {
+    throw new Error("Generic ORDERBOOK archive events are unsupported; use archiveOrderbookInBackground");
+  }
   archiveMarketRowsInBackground(archiver, otelMetrics, "stream", input, input.streamType, () => [
     buildCexStreamEventRow({
       ...input,
@@ -319283,6 +319645,82 @@ function resolveOhlcvBootstrapLimit(optionValue) {
   }
   return Math.min(parsed, MAX_OHLCV_BOOTSTRAP_LIMIT);
 }
+// src/helpers/market-data-archive/summary-v2-conformance.ts
+var ORDERBOOK_SUMMARY_V2_SUPPORTED_VIEW_FIELDS = [
+  ["source", "String", false],
+  ["deployment_id", "String", false],
+  ["capture_bundle_id", "String", false],
+  ["exchange", "String", false],
+  ["symbol", "String", false],
+  ["trading_pair", "String", false],
+  ["source_symbol", "String", false],
+  ["asset_type", "String", false],
+  ["feed", "String", false],
+  ["provider", "String", false],
+  ["source_mode", "String", false],
+  ["source_time_ms", "UInt64", false],
+  ["received_time_ms", "UInt64", false],
+  ["raw_capture_id", "String", false],
+  ["raw_capture_scope", "String", false],
+  ["schema_version", "String", false],
+  ["checksum_algorithm", "String", false],
+  ["raw_checksum", "String", false],
+  ["provenance_complete", "UInt8", false],
+  ["snapshot_id", "String", false],
+  ["construction_mode", "String", false],
+  ["gap_policy", "String", false],
+  ["depth_limit", "UInt16", false],
+  ["sequence", "UInt64", true],
+  ["exact_l2_reconstruction_complete", "UInt8", false],
+  ["capture_profile_id", "String", false],
+  ["effective_cadence_ms", "UInt32", false],
+  ["requested_upstream_depth", "UInt16", true],
+  ["observed_bid_count", "UInt32", false],
+  ["observed_ask_count", "UInt32", false],
+  ["observed_farthest_bid", "Decimal(38,18)", false],
+  ["observed_farthest_ask", "Decimal(38,18)", false],
+  ["retained_farthest_bid", "Decimal(38,18)", false],
+  ["retained_farthest_ask", "Decimal(38,18)", false],
+  ["bid_exhausted", "UInt8", false],
+  ["ask_exhausted", "UInt8", false],
+  ["best_bid", "Decimal(38,18)", false],
+  ["best_ask", "Decimal(38,18)", false],
+  ["best_bid_amount", "Decimal(38,18)", false],
+  ["best_ask_amount", "Decimal(38,18)", false],
+  ["mid_price", "Decimal(38,18)", false],
+  ["spread", "Decimal(38,18)", false],
+  ["spread_bps", "Float64", false],
+  ["staleness_ms", "UInt64", false],
+  ["bid_level_count", "UInt16", false],
+  ["ask_level_count", "UInt16", false],
+  ["measurement_bands_bps", "Array(UInt32)", false],
+  ["bid_boundary_price_by_band", "Array(Decimal(38,18))", false],
+  ["ask_boundary_price_by_band", "Array(Decimal(38,18))", false],
+  ["bid_depth_by_band", "Array(Decimal(38,18))", false],
+  ["ask_depth_by_band", "Array(Decimal(38,18))", false],
+  ["bid_status_by_band", "Array(Enum8('exact'=1,'censored'=2))", false],
+  ["ask_status_by_band", "Array(Enum8('exact'=1,'censored'=2))", false],
+  ["normalized_row_checksum", "String", false]
+];
+var ORDERBOOK_SUMMARY_V2_SUPPORTED_VIEW_FIELD_NAMES = ORDERBOOK_SUMMARY_V2_SUPPORTED_VIEW_FIELDS.map(([name]) => name);
+var DECIMAL_38_18_FIELDS = new Set([
+  "observed_farthest_bid",
+  "observed_farthest_ask",
+  "retained_farthest_bid",
+  "retained_farthest_ask",
+  "best_bid",
+  "best_ask",
+  "best_bid_amount",
+  "best_ask_amount",
+  "mid_price",
+  "spread"
+]);
+var DECIMAL_38_18_ARRAY_FIELDS = new Set([
+  "bid_boundary_price_by_band",
+  "ask_boundary_price_by_band",
+  "bid_depth_by_band",
+  "ask_depth_by_band"
+]);
 // src/helpers/order-book.ts
 var ORDER_BOOK_CALL_METHODS = {
   FETCH_CAPABILITY: "fetch_order_book_capability",
@@ -319634,7 +320072,7 @@ class PublicFeedWorker {
     if (this.options.profile) {
       this.options.metrics?.recordCounter("public_feed_acquisition_profiles_total", 1, {
         ...this.#metricLabels(),
-        profile: this.options.profile.id
+        profile_class: this.options.profile.coalescingSupported ? "coalesced" : "conservative"
       });
     }
     this.#run = this.#watchLoop();
@@ -319702,7 +320140,34 @@ class PublicFeedWorker {
         depthLimit: retainedDepth,
         receivedTimestamp
       });
-      this.options.archiveSink.orderbook({ ...context2, snapshot }, { sampledOut: !this.#sampler.shouldEmit(receivedTimestamp) });
+      const observedBidCount = snapshot.bids.length;
+      const observedAskCount = snapshot.asks.length;
+      this.options.archiveSink.orderbook({
+        ...context2,
+        snapshot,
+        archiveMetadata: {
+          captureProfileId: this.options.profile?.id ?? `${this.options.exchangeName}:conservative:default`,
+          effectiveCadenceMs: getOrderbookIntervalMs(),
+          requestedUpstreamDepth: this.options.profile?.upstreamLimit ?? null,
+          observedBidCount,
+          observedAskCount,
+          observedFarthestBid: snapshot.bids.at(-1)?.[0] ?? Number.NaN,
+          observedFarthestAsk: snapshot.asks.at(-1)?.[0] ?? Number.NaN,
+          exhaustionEvidence: {
+            bid: {
+              exhausted: this.options.profile?.bidExhaustionEvidence ?? false,
+              validated: this.options.profile?.exhaustionEvidenceValidated ?? true,
+              source: this.options.profile?.id ?? "broker:conservative"
+            },
+            ask: {
+              exhausted: this.options.profile?.askExhaustionEvidence ?? false,
+              validated: this.options.profile?.exhaustionEvidenceValidated ?? true,
+              source: this.options.profile?.id ?? "broker:conservative"
+            }
+          },
+          measurementBandsBps: getOrderbookMeasurementBandsBps()
+        }
+      }, { sampledOut: !this.#sampler.shouldEmit(receivedTimestamp) });
       this.#recordCounter("public_feed_archive_decisions_total");
       this.options.observer?.archiveDecision?.(this.#observation());
       this.#fanout((subscriber) => this.#frame(projectOrderBookSnapshot(snapshot, subscriber.depthLimit), receivedTimestamp));
@@ -319875,7 +320340,7 @@ class PublicFeedWorker {
   }
   #metricLabels() {
     return {
-      exchange: this.options.exchangeName,
+      exchange_bucket: this.options.exchangeOwned ? "dynamic" : "configured",
       feed: this.options.feed,
       market_type: this.options.marketType
     };
@@ -335242,7 +335707,29 @@ async function handleOrderBookCall(ctx) {
       assetType: "spot",
       accountSelector: ctx.selectedBrokerAccount?.label,
       deploymentId: ctx.brokerArchiver?.getDeploymentId() ?? "unarchived",
-      snapshot
+      snapshot,
+      archiveMetadata: {
+        captureProfileId: `${orderBookPayload.exchange.trim().toLowerCase()}:current-snapshot:requested:${orderBookPayload.depthLimit}`,
+        effectiveCadenceMs: 1,
+        requestedUpstreamDepth: orderBookPayload.depthLimit,
+        observedBidCount: snapshot.bids.length,
+        observedAskCount: snapshot.asks.length,
+        observedFarthestBid: snapshot.bids.at(-1)?.[0] ?? Number.NaN,
+        observedFarthestAsk: snapshot.asks.at(-1)?.[0] ?? Number.NaN,
+        exhaustionEvidence: {
+          bid: {
+            exhausted: false,
+            validated: true,
+            source: "broker:current-snapshot"
+          },
+          ask: {
+            exhausted: false,
+            validated: true,
+            source: "broker:current-snapshot"
+          }
+        },
+        measurementBandsBps: getOrderbookMeasurementBandsBps()
+      }
     }, {
       sourceMode: "broker_current_snapshot_v1",
       depthLimit: orderBookPayload.depthLimit