@secondlayer/sdk 9.0.2 → 10.1.0

package/dist/subgraphs/index.d.ts

@@ -16,20 +16,50 @@ interface SecondLayerOptions {
 	dumpsBaseUrl?: string;
 	/** Deploy origin label sent as `x-sl-origin` (telemetry). Defaults to `cli`. */
 	origin?: "cli" | "mcp" | "session";
+	/** Check the ed25519 signature on every Streams read. Omit for lenient
+	*  (verify when signed, pass through unsigned self-host responses), `true`
+	*  or `{ publicKey }` for strict, `false` for off. Reaches `sl.streams`. */
+	verify?: boolean | {
+		publicKey: string;
+	};
+	/** Check the dumps manifest signature before trusting any file hash
+	*  (default on). Reaches `sl.streams.dumps`. */
+	verifyDumpsManifest?: boolean;
+	/** How long one request may take, headers and body, before it fails with a
+	*  retryable `ApiError` (default 30 000 ms). A hung socket then trips the
+	*  retry policy instead of stalling a walk or consume loop forever. `0`
+	*  disables the timeout. */
+	requestTimeoutMs?: number;
 }
+/** Per-call options every `request*` method accepts. */
+type RequestOptions = {
+	/** Cancels the in-flight request (and its body read). The rejection is the
+	*  signal's reason, an `AbortError` by default, never an `ApiError`. */
+	signal?: AbortSignal;
+};
 declare abstract class BaseClient {
 	protected baseUrl: string;
 	protected apiKey?: string;
 	protected origin: "cli" | "mcp" | "session";
 	protected fetchImpl: FetchLike;
+	protected requestTimeoutMs: number;
 	constructor(options?: Partial<SecondLayerOptions>);
 	static authHeaders(apiKey?: string): Record<string, string>;
-	protected request<T>(method: string, path: string, body?: unknown): Promise<T>;
+	protected request<T>(method: string, path: string, body?: unknown, opts?: RequestOptions): Promise<T>;
 	/** Like `request`, but maps a 404 to `null` instead of throwing — the one
 	*  place that owns the "absent resource" rule for `get*` accessors. */
-	protected requestOrNull<T>(method: string, path: string, body?: unknown): Promise<T | null>;
-	protected requestText(method: string, path: string, body?: unknown): Promise<string>;
-	private fetchResponse;
+	protected requestOrNull<T>(method: string, path: string, body?: unknown, opts?: RequestOptions): Promise<T | null>;
+	protected requestText(method: string, path: string, body?: unknown, opts?: RequestOptions): Promise<string>;
+	/** Run one request under the caller's signal plus the per-request timeout.
+	*  One combined signal covers the fetch and the body read, so a socket that
+	*  stalls mid-body times out the same way one that never answers does. A
+	*  timeout rejects with a retryable `ApiError`; a caller abort rejects with
+	*  the signal's reason so loops can tell "stop" from "try again". */
+	private withRequestBudget;
+	/** Issue the HTTP request and map non-2xx statuses onto the error family.
+	*  `signal` is the combined caller-plus-timeout signal from `request*`;
+	*  subclasses that stream a body call this directly and read it themselves. */
+	protected fetchResponse(method: string, path: string, body?: unknown, signal?: AbortSignal): Promise<Response>;
 }
 interface SubgraphSource {
 	name: string;
@@ -92,8 +122,10 @@ declare class Subgraphs extends BaseClient {
 	markdown(name: string, options?: SubgraphSpecOptions): Promise<string>;
 	/**
 	* Reindex always drops and rebuilds the whole subgraph, so it takes no
-	* block range — the API rejects one with `REINDEX_RANGE_NOT_SUPPORTED`.
-	* Use {@link backfill} to process a specific range.
+	* block range; the API rejects one with `REINDEX_RANGE_NOT_SUPPORTED`.
+	* Use {@link backfill} to process a specific range. While a reindex or
+	* backfill is already running the API answers 409 with code
+	* `OPERATION_IN_PROGRESS`; poll {@link operations} until it finishes.
 	*/
 	reindex(name: string): Promise<ReindexResponse>;
 	stop(name: string): Promise<{
@@ -101,6 +133,8 @@ declare class Subgraphs extends BaseClient {
 		operationId?: string;
 		status?: string;
 	}>;
+	/** Process one block range. 409 `OPERATION_IN_PROGRESS` while another
+	*  reindex or backfill runs on this subgraph. */
 	backfill(name: string, options: {
 		fromBlock: number;
 		toBlock: number;
@@ -130,6 +164,9 @@ declare class Subgraphs extends BaseClient {
 	/** Status of a single operation (poll the `operationId` returned by
 	*  reindex/backfill/stop until `status` is terminal). */
 	getOperation(name: string, operationId: string): Promise<SubgraphOperationStatus>;
+	/** Create or update a subgraph. A deploy that needs a rebuild queues one;
+	*  if a reindex or backfill is already running the API answers 409 with
+	*  code `OPERATION_IN_PROGRESS` (an `ApiError`, not a dedicated class). */
 	deploy(data: DeploySubgraphRequest): Promise<DeploySubgraphResponse>;
 	getSource(name: string): Promise<SubgraphSource>;
 	/**
@@ -160,6 +197,13 @@ declare class Subgraphs extends BaseClient {
 		name: string;
 		schema: Record<string, unknown>;
 	}>(def: T): InferSubgraphClient<T>;
+	/**
+	* `columns` is the table's declared column set from `defineSubgraph()`.
+	* Filters and orderBy always accept the canonical system names
+	* `_id` / `_blockHeight` / `_txId` / `_createdAt`; the unprefixed
+	* shorthands (`id`, `blockHeight`, ...) mean the system column only when
+	* the table declares no column of that name.
+	*/
 	private createTableClient;
 }
 import { InferSubgraphClient as InferSubgraphClient2 } from "@secondlayer/subgraphs";
@@ -367,8 +411,11 @@ interface ConsumerSink<Tx = unknown> {
 	* same `rewindCursor` (the lowest fork point) but its own
 	* `forkPointHeight` — scope the undo by `forkPointHeight` only (contract
 	* invariant #11), and expect re-application after a crash (#10).
+	*
+	* `rewindCursor` is `null` only for a fork at genesis: clear the
+	* checkpoint so the next run starts from the first event.
 	*/
-	rollback(forkPointHeight: number, rewindCursor: string): Promise<void>;
+	rollback(forkPointHeight: number, rewindCursor: string | null): Promise<void>;
 }
 /** `ctx` gains `tx` exactly when a sink is attached; without one the shape
 *  is unchanged (an intersection with `unknown` is an identity, so
@@ -516,11 +563,41 @@ type StreamsEventsSubscribeParams = {
 	filters?: StreamsFilterMap;
 	/** Abort to unsubscribe (the returned function does the same). */
 	signal?: AbortSignal;
-	/** Called for each pushed event, in order. */
+	/**
+	* Called for each pushed event, in order. The resume cursor advances only
+	* after this resolves, so a handler that throws sees the same event again
+	* on reconnect (at-least-once). Key durable writes by `cursor`.
+	*/
 	onEvent: (event: StreamsEvent) => void | Promise<void>;
-	/** Called on a connection error; the subscription auto-reconnects from the
-	*  last delivered cursor unless the signal has aborted. */
+	/**
+	* Called on every failure. Transport errors (dropped socket, 5xx, 429, a
+	* stale connection, a throwing handler) reconnect from the last handled
+	* cursor with exponential backoff. Errors that a retry cannot fix (401,
+	* 4xx, a bad signature) end the subscription and reject its `done`.
+	*/
 	onError?: (err: unknown) => void;
+	/**
+	* First reconnect pause in ms (default 1000). Doubles per consecutive
+	* failure up to 30 s with jitter, resets once a frame arrives, and never
+	* undercuts a `Retry-After`.
+	*/
+	reconnectDelayMs?: number;
+	/**
+	* Reconnect when no frame (pings included) arrives for this long (default
+	* 60000, three server heartbeats). Catches a half-open socket that never
+	* errors; set it above your instance's heartbeat interval.
+	*/
+	staleAfterMs?: number;
+};
+/**
+* Handle for a live subscription: call it to unsubscribe. `done` resolves
+* after unsubscribe (or the signal aborting) and rejects with the error that
+* ended the loop when a retry could not fix it, so a worker can `await`
+* it instead of polling for silence.
+*/
+type StreamsSubscription = {
+	(): void;
+	done: Promise<void>;
 };
 /**
 * The checkpoint the SDK computes for a batch. Persist `cursor` inside the same
@@ -585,8 +662,11 @@ type StreamsBatchContext = ConsumerBatchContext;
 * The checkpoint for a reorg rollback. Persist `cursor` (the rewind position)
 * inside the same transaction as your rollback so the two commit atomically.
 */
+/** `cursor` is the rewind position the loop resumes from after `onReorg`:
+*  the foot of the fork point, or `null` for a fork at genesis. Persist it
+*  in the same transaction as the rollback. */
 type StreamsReorgContext = {
-	cursor: string;
+	cursor: string | null;
 };
 type StreamsEventsConsumeParams<
 	TTx = never,
@@ -606,7 +686,8 @@ type StreamsEventsConsumeParams<
 	* the loop resumes from the sink's committed cursor, `onBatch` receives
 	* `ctx.tx` and must write ONLY through it (rows and cursor commit in one
 	* transaction), reorg rollback is automatic, and `onBatch`'s return value
-	* is ignored.
+	* is ignored. Folds (balances) invert in the sink's `onRollback`, not in
+	* `onReorg`.
 	*/
 	sink?: ConsumerSink<TTx>;
 	/** Fires once per page, before `onBatch` and before any early return. */
@@ -654,12 +735,23 @@ type StreamsEventsConsumeParams<
 	onBatch?: (events: D extends true ? IndexEvent[] : StreamsEvent[], envelope: StreamsEventsEnvelope, ctx: StreamsBatchContext & WithSinkTx<TTx>) => void | string | null | undefined | Promise<void> | Promise<string | null | undefined>;
 	/**
 	* Roll your projection back to `reorg.fork_point_height`, persisting
-	* `ctx.cursor` in the same transaction. Called once per *new* reorg
-	* (deduped in-memory, fork-ascending) before the SDK rewinds and re-reads the
-	* now-canonical events. Omit it to ignore reorgs (events stay canonical, but
-	* stale rows from an orphaned fork are left in place).
+	* `ctx.cursor` in the same transaction. Called once per *new* reorg at or
+	* below the checkpoint (deduped in-memory, fork-ascending) before the SDK
+	* rewinds and re-reads the now-canonical events. A reorg whose fork sits
+	* above the checkpoint is not a rollback (nothing past it was written) and
+	* is skipped. Omit it to ignore reorgs (events stay canonical, but stale
+	* rows from an orphaned fork are left in place).
+	*
+	* With `onReorg` or a `sink` attached, every empty page also polls
+	* `reorgs.list` (one extra request per idle poll) so a fork that lands
+	* while the consumer idles at the tip is rolled back too.
 	*/
 	onReorg?: (reorg: StreamsReorg, ctx: StreamsReorgContext) => Promise<void> | void;
+	/** Deepest rewind one reorg may make below the checkpoint before the loop
+	*  refuses with `ValidationError`. Default 1000 blocks. The fork point is
+	*  server supplied and drives a delete on every declared table, so raise
+	*  this only for a source you trust. */
+	maxRollbackDepth?: number;
 	/** Page-fetch retries after the first failure (429/5xx/network only —
 	*  4xx and handler throws always propagate). Default 3; `0` disables. */
 	retryCount?: number;
@@ -722,8 +814,16 @@ type StreamsEventsReplayParams = {
 	* Called once per finalized dump file, in block order, before live tailing.
 	* Process the parquet with your own tooling (e.g. DuckDB) — the SDK does not
 	* decode parquet. Use `client.dumps.download(file)` to fetch + verify bytes.
+	*
+	* Delivery is file-granular and at-least-once: a file whose range straddles
+	* `from` is handed over whole. `ctx.from` is that cursor (`null` from
+	* genesis); skip rows at or below it, or key rows by `cursor` so a re-run
+	* is an idempotent no-op. Files ending at or below `from` are not handed
+	* over at all.
 	*/
-	onDumpFile: (file: StreamsDumpFile) => Promise<void> | void;
+	onDumpFile: (file: StreamsDumpFile, ctx: {
+		from: string | null;
+	}) => Promise<void> | void;
 	/** Called per live page after the dump phase, like `consume`. */
 	onBatch: (events: StreamsEvent[], envelope: StreamsEventsEnvelope) => Promise<string | null | undefined> | string | null | undefined;
 	/**
@@ -858,9 +958,11 @@ type StreamsClient = {
 		* Subscribe to the real-time SSE push surface. Calls `onEvent` for each new
 		* canonical event as the server pushes it (chain cadence, not poll-bounded),
 		* and verifies each frame's inline ed25519 signature when the client was
-		* created with `verify`. Returns an unsubscribe function.
+		* created with `verify`. Returns an unsubscribe function whose `done`
+		* settles when the loop ends. Not reorg-aware: an event delivered then
+		* orphaned is never retracted. Durable writers use `consume()`.
 		*/
-		subscribe(params: StreamsEventsSubscribeParams): () => void;
+		subscribe(params: StreamsEventsSubscribeParams): StreamsSubscription;
 	};
 	blocks: {
 		events(heightOrHash: number | string): Promise<StreamsEventsListEnvelope>;
@@ -931,7 +1033,8 @@ type IndexConsumeOptions<
 	* the loop resumes from the sink's committed cursor, `onBatch` receives
 	* `ctx.tx` and must write ONLY through it (rows and cursor commit in one
 	* transaction — a throw aborts both), reorg rollback is automatic (no
-	* `onReorg` needed), and `onBatch`'s return value is ignored.
+	* `onReorg` needed), and `onBatch`'s return value is ignored. Folds
+	* (balances) invert in the sink's `onRollback`, not in `onReorg`.
 	*/
 	sink?: ConsumerSink<TTx>;
 	/** Fires once per page, before `onBatch` and before any early return —
@@ -939,9 +1042,18 @@ type IndexConsumeOptions<
 	*  `consumerHealth().record`. */
 	onProgress?: (ctx: ConsumerBatchContext) => void;
 	onBatch: (items: TItem[], envelope: TEnvelope, ctx: ConsumerBatchContext & WithSinkTx<TTx>) => void | string | null | undefined | Promise<void> | Promise<string | null | undefined>;
+	/** Called once per new reorg at or below the checkpoint, before the loop
+	*  rewinds to `ctx.cursor` (`null` = pre-genesis) and re-reads. A reorg
+	*  whose fork sits ABOVE the checkpoint is not a rollback: nothing past
+	*  it was written, so it is noted and the page is read as normal. */
 	onReorg?: (reorg: IndexReorg, ctx: {
-		cursor: string;
+		cursor: string | null;
 	}) => Promise<void> | void;
+	/** Deepest rewind one reorg may make below the checkpoint before the loop
+	*  refuses with `ValidationError`. Default 1000 blocks. The fork point is
+	*  server supplied and drives a delete on every declared table, so raise
+	*  this only for a source you trust. */
+	maxRollbackDepth?: number;
 	sleep?: Sleep;
 	emptyBackoffMs?: number;
 	maxPages?: number;
@@ -1037,10 +1149,20 @@ type FtTransfersListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
-type FtTransfersWalkParams = Omit<FtTransfersListParams, "limit"> & {
+/** Options every `walk*` feed shares on top of its list filters. Page fetches
+*  retry with the same `retryCount`/`retryDelay`/`onError` vocabulary as
+*  `consume()`; the tradeoff is that a walk can pause for the retry delays
+*  instead of failing fast on the first 429. */
+type WalkOptions = PageRetryOptions & {
+	/** Rows per page request. Default 200, max `INDEX_MAX_PAGE_SIZE` (1000). */
 	batchSize?: number;
+	/** Stops the walk. The iterator always rejects with the signal's reason (an
+	*  `AbortError` by default), whether the abort lands during a page request
+	*  (which is cancelled) or between yields, so a caller can tell a finished
+	*  walk from a stopped one. */
 	signal?: AbortSignal;
 };
+type FtTransfersWalkParams = Omit<FtTransfersListParams, "limit"> & WalkOptions;
 type NftTransfer = {
 	cursor: string;
 	block_height: number;
@@ -1078,10 +1200,7 @@ type NftTransfersListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
-type NftTransfersWalkParams = Omit<NftTransfersListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+type NftTransfersWalkParams = Omit<NftTransfersListParams, "limit"> & WalkOptions;
 type IndexEventBase = {
 	cursor: string;
 	block_height: number;
@@ -1236,10 +1355,7 @@ type EventsListParams<T extends IndexEventType = IndexEventType> = {
 	*/
 	fields?: readonly (keyof IndexEventOf<T> & string)[];
 };
-type EventsWalkParams<T extends IndexEventType = IndexEventType> = Omit<EventsListParams<T>, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+type EventsWalkParams<T extends IndexEventType = IndexEventType> = Omit<EventsListParams<T>, "limit"> & WalkOptions;
 type EventsConsumeParams<
 	T extends IndexEventType = IndexEventType,
 	TTx = never
@@ -1279,10 +1395,7 @@ type ContractCallsListParams = {
 	*  Mutually exclusive with contractId. */
 	trait?: string;
 };
-type ContractCallsWalkParams = Omit<ContractCallsListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+type ContractCallsWalkParams = Omit<ContractCallsListParams, "limit"> & WalkOptions;
 type ContractCallsConsumeParams<TTx = never> = Omit<ContractCallsListParams, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexContractCall, ContractCallsEnvelope, TTx>;
 /** One canonical block in the sync map. Lean by design — block + parent hash
 *  for chain linkage, burn anchor for Bitcoin confirmations. Use `blocks` for
@@ -1307,10 +1420,7 @@ type CanonicalListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
-type CanonicalWalkParams = Omit<CanonicalListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+type CanonicalWalkParams = Omit<CanonicalListParams, "limit"> & WalkOptions;
 /** A block resource. Metadata is intentionally thin — only chain-linkage and
 *  burn-anchor fields are persisted (no miner / tx_count / signer). */
 type IndexBlock = {
@@ -1339,10 +1449,7 @@ type BlocksListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
-type BlocksWalkParams = Omit<BlocksListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+type BlocksWalkParams = Omit<BlocksListParams, "limit"> & WalkOptions;
 type IndexPostCondition = {
 	type: "stx";
 	principal: string;
@@ -1448,10 +1555,7 @@ type TransactionsListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
-type TransactionsWalkParams = Omit<TransactionsListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+type TransactionsWalkParams = Omit<TransactionsListParams, "limit"> & WalkOptions;
 /** A decoded PoX-4 stacking action (one per stacking contract call). */
 type IndexStackingAction = {
 	cursor: string;
@@ -1495,10 +1599,7 @@ type StackingListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
-type StackingWalkParams = Omit<StackingListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+type StackingWalkParams = Omit<StackingListParams, "limit"> & WalkOptions;
 /** A pending (unconfirmed) transaction. Like a transaction document but
 *  pre-chain — no block_height/tx_index/result/events — with `received_at` and
 *  a sequence cursor instead of a block position. */
@@ -1554,10 +1655,7 @@ type MempoolListParams = {
 	/** Filter to pending calls to a single function (composes with `contractId`). */
 	functionName?: string;
 };
-type MempoolWalkParams = Omit<MempoolListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+type MempoolWalkParams = Omit<MempoolListParams, "limit"> & WalkOptions;
 /**
 * Empirical per-topic print payload schema for a contract, inferred from
 * sampled on-chain events. `topics` is sorted by count desc; `sampled` is true
@@ -1749,10 +1847,7 @@ type SbtcDepositsListParams = {
 type SbtcDepositAlwaysFields = "cursor" | "block_height";
 /** A deposit row narrowed to the requested columns plus the always-present ones. */
 type SbtcDepositFields<F extends keyof IndexSbtcDeposit & string> = Pick<IndexSbtcDeposit, (F | SbtcDepositAlwaysFields) & keyof IndexSbtcDeposit>;
-type SbtcDepositsWalkParams = Omit<SbtcDepositsListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+type SbtcDepositsWalkParams = Omit<SbtcDepositsListParams, "limit"> & WalkOptions;
 /** SbtcWithdrawal columns that survive any projection. */
 type SbtcWithdrawalAlwaysFields = "cursor" | "request_id";
 /** A SbtcWithdrawal row narrowed to the requested columns plus the always-present ones. */
@@ -1777,10 +1872,7 @@ type SbtcWithdrawalsListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
-type SbtcWithdrawalsWalkParams = Omit<SbtcWithdrawalsListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+type SbtcWithdrawalsWalkParams = Omit<SbtcWithdrawalsListParams, "limit"> & WalkOptions;
 type SbtcEventsListParams = {
 	cursor?: string | null;
 	fromCursor?: string | null;
@@ -1793,10 +1885,7 @@ type SbtcEventsListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
-type SbtcEventsWalkParams = Omit<SbtcEventsListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+type SbtcEventsWalkParams = Omit<SbtcEventsListParams, "limit"> & WalkOptions;
 type SbtcEventsConsumeParams<TTx = never> = Omit<SbtcEventsListParams, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexSbtcEvent, SbtcEventsEnvelope, TTx>;
 type SbtcDepositsConsumeParams<TTx = never> = Omit<SbtcDepositsListParams, "cursor" | "fromCursor" | "limit" | "fields"> & IndexConsumeOptions<IndexSbtcDeposit, SbtcDepositsEnvelope, TTx>;
 /** `index.sbtc` — the decoded sBTC peg surface (deposits, withdrawals, raw
@@ -1887,10 +1976,7 @@ type PoxCyclesListParams = {
 	cursor?: number | null;
 	limit?: number;
 };
-type PoxCyclesWalkParams = Omit<PoxCyclesListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+type PoxCyclesWalkParams = Omit<PoxCyclesListParams, "limit"> & WalkOptions;
 /** `index.pox` — PoX reward-cycle aggregates. */
 interface PoxResource {
 	cycles: {
@@ -1965,10 +2051,7 @@ type Pox5EventsListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
-type Pox5EventsWalkParams = Omit<Pox5EventsListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+type Pox5EventsWalkParams = Omit<Pox5EventsListParams, "limit"> & WalkOptions;
 /** `index.pox5` — decoded PoX-5 print events, the staking primitive from the
 *  epoch 4.0 hard fork onward (PoX-4's `index.stacking` stream ends there). */
 interface Pox5Resource {
@@ -2173,9 +2256,13 @@ declare class Index extends BaseClient {
 	private listNftTransfers;
 	/** Shared keyset-pagination loop for every `walk*` feed: seed the cursor from
 	*  `cursor`/`fromCursor` (and `fromHeight` 0 on the first page), then page until
-	*  the cursor stops advancing or a short page signals the tail. `list` merges the
-	*  resource's filter params; `itemsOf` selects the envelope's item array. PoX
-	*  cycles use a numeric cursor and are walked separately. */
+	*  the server stops advancing the cursor (`next_cursor` null or unchanged). A
+	*  short page is not a tail signal: the server clamps oversized limits without
+	*  saying so, so trusting page length truncated backfills. The cost is one
+	*  extra empty fetch at the end of feeds that never return a null cursor.
+	*  `list` merges the resource's filter params; `itemsOf` selects the envelope's
+	*  item array. Each page fetch retries under `fetchPageWithRetry`; the cursor
+	*  is a string keyset for every feed except PoX cycles, which use a number. */
 	private keysetWalk;
 	private walkFtTransfers;
 	private walkNftTransfers;
@@ -2262,22 +2349,43 @@ interface ActiveSubgraphOperation {
 	status: SubgraphOperationStatus["status"];
 	progress: number | null;
 }
+/** Why one snapshot field could not be read. Serialized from the SDK error
+*  family so a snapshot stays plain data. */
+interface ContextFieldError {
+	message: string;
+	/** Stable code from the API envelope (`UNAUTHORIZED`, `INDEX_NOT_READY`)
+	*  or the SDK (`REQUEST_TIMEOUT`); absent for a bare transport failure. */
+	code?: string;
+	/** HTTP status; `0` when the API could not be reached. */
+	status?: number;
+	/** Whether the same read can succeed on a retry (429, 5xx, network). */
+	retryable: boolean;
+}
+/** One snapshot field: the value, or `null` plus the error that produced it.
+*  `value: null` with no `error` means the read succeeded and found nothing. */
+interface ContextField<T> {
+	value: T | null;
+	error?: ContextFieldError;
+}
 /**
-* A point-in-time orientation snapshot for an agent: who you are, the live tips,
-* and what you own. Each field is `null` when it couldn't be read (e.g. no key,
-* or a free-tier key for a Build+ surface) so the snapshot never throws.
+* A point-in-time orientation snapshot for an agent: the live tips and what
+* this instance holds. Every field is a {@link ContextField}, so a missing
+* value says why it is missing (API unreachable, token rejected, index still
+* catching up) instead of a bare `null`. `context()` itself never throws.
 */
 interface ContextSnapshot {
-	account: ContextAccount | null;
-	streamsTip: StreamsTip | null;
-	indexTip: IndexTip | null;
-	subgraphs: SubgraphSummary2[] | null;
-	subscriptions: {
+	/** Token identity from `/api/accounts/me`. A self-hosted instance has no
+	*  account system: the read 404s and the field carries that error. */
+	account: ContextField<ContextAccount>;
+	streamsTip: ContextField<StreamsTip>;
+	indexTip: ContextField<IndexTip>;
+	subgraphs: ContextField<SubgraphSummary2[]>;
+	subscriptions: ContextField<{
 		count: number;
 		byStatus: Record<string, number>;
-	} | null;
+	}>;
 	/** In-flight reindex operations (bounded to subgraphs reporting `reindexing`). */
-	activeOperations: ActiveSubgraphOperation[] | null;
+	activeOperations: ContextField<ActiveSubgraphOperation[]>;
 }
 declare class SecondLayer extends BaseClient {
 	readonly streams: StreamsClient;
@@ -2287,14 +2395,8 @@ declare class SecondLayer extends BaseClient {
 	readonly subscriptions: Subscriptions;
 	constructor(options?: Partial<SecondLayerOptions>);
 	/**
-	* Assemble a {@link ContextSnapshot} — the same orientation an MCP agent reads
-	* from `secondlayer://context`, but available to any SDK/CLI consumer. Reads
-	* run concurrently and degrade to `null` per field on failure.
-	*/
-	/**
 	* Up to 10 public reads in one round trip (`POST /v1/batch`). Each item
-	* keeps its own auth/quota/x402 semantics; forwarded credentials (API key,
-	* PAYMENT-BALANCE/SESSION) apply to every item.
+	* is authorized on its own; the client's bearer token applies to every item.
 	*/
 	batch(requests: Array<{
 		path: string;
@@ -2306,6 +2408,12 @@ declare class SecondLayer extends BaseClient {
 			body: unknown;
 		}>;
 	}>;
+	/**
+	* Assemble a {@link ContextSnapshot}: the same orientation an MCP agent
+	* reads from `secondlayer://context`, available to any SDK/CLI consumer.
+	* Reads run concurrently; a failed read lands as `{ value: null, error }`
+	* on its field rather than rejecting the whole snapshot.
+	*/
 	context(): Promise<ContextSnapshot>;
 }
 /**