Appearance

Documentation / @etherfold/core / StreamHoleError

Class: StreamHoleError ​

Defined in: packages/core/src/errors.ts:264

AN APPEND THAT WOULD PUNCH A HOLE IN THE STORED STREAM, refused.

A hole is a range of blocks the stream never RECEIVED, hidden behind a cursor claiming to cover them (CONTEXT.md, "hole versus gap"). It is INVISIBLE to every later reader: the rows are perfectly well-formed, the coverage claim is self-consistent, and on the next state discard the stream replays as though it were whole with the missing blocks simply absent from the rebuilt state. Silent, permanent, self-consistent.

Why the guard is HERE, on the append-only writer ​

ADR-0087 first credited this guard to IndexerGeneration.streamCanReceive, and its own amendment corrects that: that method sits over an ExistingStream the load path always reads first, so the duplicate measured there was never on its path. The hazard is on the APPEND-ONLY path -- an EmissionAppender reads nothing back and had no hole guard of any kind -- which is precisely the path the thing that FETCHES a stream writes through.

It is a durable BACKSTOP and deliberately not the arbiter. The arbiter is the cursor protocol (UnexpectedFromBlockError), which refuses a batch that does not start where the stream resumes; this catches the case where the position a write was derived from is not the stream's own -- the exact failure that moving the write duty could reintroduce.

An ABSENT stream is PERMISSIVE and that is not an oversight. No stored stream is the documented ABSENCE of one rather than an unknown position (the same correction ADR-0087's amendment makes about streamLastToBlock === undefined): nothing constrains the next write, and refusing there would decline the first save of every fresh deployment.

Extends ​

  • Error

Constructors ​

Constructor ​

new StreamHoleError(stream, coveredThrough, appendingFrom): StreamHoleError

Defined in: packages/core/src/errors.ts:269

Parameters ​

stream ​

string

The stream that would have been damaged, as streamDigestOf renders it.

coveredThrough ​

number

How far the stored stream currently claims to reach.

appendingFrom ​

number

The first block of the range that was about to be appended.

Returns ​

StreamHoleError

Overrides ​

Error.constructor

Properties ​

appendingFrom ​

readonly appendingFrom: number

Defined in: packages/core/src/errors.ts:275

The first block of the range that was about to be appended.

cause? ​

optional cause?: unknown

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24

Inherited from ​

Error.cause

coveredThrough ​

readonly coveredThrough: number

Defined in: packages/core/src/errors.ts:273

How far the stored stream currently claims to reach.

message ​

message: string

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075

Inherited from ​

Error.message

name ​

readonly name: "StreamHoleError" = 'StreamHoleError'

Defined in: packages/core/src/errors.ts:265

Overrides ​

Error.name

retryable ​

readonly retryable: false = false

Defined in: packages/core/src/errors.ts:267

NOT retryable: re-sending the same range meets the same gap.

stack? ​

optional stack?: string

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from ​

Error.stack

stream ​

readonly stream: string

Defined in: packages/core/src/errors.ts:271

The stream that would have been damaged, as streamDigestOf renders it.

Methods ​

isError() ​

static isError(error): error is Error

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.esnext.error.d.ts:21

Indicates whether the argument provided is a built-in Error instance or not.

Parameters ​

error ​

unknown

Returns ​

error is Error

Inherited from ​

Error.isError