js-bao-wss-client / DocumentIngestSession
Interface: DocumentIngestSession
One bulk-load session, as the server describes it.
A session is how a directory of records becomes a large document's table: it is created, its chunks are uploaded, it is committed, and the pipeline then copies, applies, reconciles and swaps on the room's alarm. Nothing here is a key, a signature or a cursor — the view is what an operator may see.
Properties
buildId
buildId:
string|null
The base build the session waits on before it reports complete.
bytes
bytes:
number
chunks
chunks:
number
How many chunks the committed manifest holds.
completedAt?
optionalcompletedAt?:string|null
copyStartedAt?
optionalcopyStartedAt?:string|null
createdAt?
optionalcreatedAt?:string|null
createdBy?
optionalcreatedBy?:string
discontinuityEpoch
discontinuityEpoch:
number|null
The epoch the swap sealed with a base discontinuity, once it has happened. Connected clients converge on the base built for the epoch after it.
documentId
documentId:
string
expiresAt?
optionalexpiresAt?:string|null
failure
failure: {
code:string;reason:string;rows?:object[]; } |null
Why a failed session failed, with the rows that caused it.
Union Members
Type Literal
{ code: string; reason: string; rows?: object[]; }
code
code:
string
reason
reason:
string
rows?
optionalrows?:object[]
The records the failure names, each as its model and its id.
null
progress
progress:
object
chunksApplied
chunksApplied:
number
oldRowsRemoved
oldRowsRemoved:
number
Rows taken off the tables a swap moved aside, monotonic.
The number that says whether a session in registering is advancing. Removal is bounded per tick, so a large document leaves the state over many alarms and this climbs across them.
recordsReconciled
recordsReconciled:
number
rowsApplied
rowsApplied:
number
rowsCopied
rowsCopied:
number
rawBytes?
optionalrawBytes?:number|null
Decompressed bytes across the stored chunks.
null when it cannot be known: a session that completed before timings were recorded has had its chunk descriptors swept with its reservations.
rows
rows:
number
sessionId
sessionId:
string
state
state:
"uploading"|"failed"|"committed"|"validating"|"staging"|"applying"|"finalizing"|"registering"|"complete"|"aborted"
Where the session is. uploading accepts chunks; committed has frozen its manifest; the four working states are the pipeline's own; complete means the ingested table is live and its base is verified.
stateEnteredAt?
optionalstateEnteredAt?:string|null
When the current state began.
throughput?
optionalthroughput?: {pipelineMs:number;rawBytesPerSecond:number|null;rowsPerSecond:number;storedBytesPerSecond:number; } |null
Rates over the pipeline window, committed through the swap.
null unless the session reached registering and its timing history begins at uploading: a window nobody measured gets no rate rather than an invented one.
Union Members
Type Literal
{ pipelineMs: number; rawBytesPerSecond: number | null; rowsPerSecond: number; storedBytesPerSecond: number; }
pipelineMs
pipelineMs:
number
rawBytesPerSecond
rawBytesPerSecond:
number|null
null when the decompressed total is unknown.
rowsPerSecond
rowsPerSecond:
number
storedBytesPerSecond
storedBytesPerSecond:
number
null
timings?
optionaltimings?:object
Where the session's time went.
Three kinds of number, and they are not equally exact. A STATE WINDOW and an INTERVAL are wall time between tick starts, and every tick starts in a fresh alarm invocation, so both are exact. A STAGE total is what the tick's own timers read, and on Workers the clock advances only across I/O: copyMs, applyMs, decodeMs, swapMs and registerMs read 0 there, while readMs, sealMs and manifestMs are observation intervals ending at an I/O boundary that include the synchronous work before them. intervalMs belongs to the tick that STARTED it and includes the room's post-tick work and the 1,000 ms re-arm delay.
A server that settles the clock brackets those stage timers, and totals.bracketedTicks says how many ticks it managed it for. A bracketed stage total is WALL milliseconds — it includes the settle's own cost and any I/O inside the bracket — and is not CPU time. The ledger clock still does not move inside a transaction, so an unbracketed tick reads 0 for every synchronous stage. totals.counters is the clock-free half and is exact wherever the host has cursor counters.
Optional, because an older server omits the whole block.
longestInterval
longestInterval: {
intervalMs:number;state:"uploading"|"failed"|"committed"|"validating"|"staging"|"applying"|"finalizing"|"registering"|"complete"|"aborted"; } |null
since
since:
"uploading"|"failed"|"committed"|"validating"|"staging"|"applying"|"finalizing"|"registering"|"complete"|"aborted"|null
Where this row's history begins; uploading for a modern session.
states
states:
Partial<Record<DocumentIngestSession["state"], {intervalMs:number;ms:number;ticks:number; }>>
ticks
ticks:
number
totals
totals:
object
totals.applyMs
applyMs:
number
totals.bracketedTicks
bracketedTicks:
number
Ticks whose stage timers were bracketed by a clock settle.
The server yields at both ends of every stage bracket so the timer reads the wall time of the work it encloses instead of the 0 a frozen Workers clock gives it. Equal to ticks when every tick was bracketed; less when a settle was refused, and then the stage totals above are the old, un-bracketed figures for those ticks.
totals.copyMs
copyMs:
number
totals.counters
counters:
Record<"manifest"|"read"|"decode"|"copy"|"apply"|"reconcile"|"swap"|"seal"|"register",DocumentIngestStageCounters>
What each stage's SQL did, without asking a clock.
statements is exact everywhere. rowsRead and rowsWritten come from the SQL cursor's own billing counters and are null where the host has none — never a substituted zero. rowsReturned is a third figure: an aggregate returns one row after reading many.
byTarget splits the same figures by the table each statement named (records, members, claims, log, bookkeeping, other), which is what separates the records fold from string-set maintenance from unique claims inside one stage.
totals.decodeMs
decodeMs:
number
totals.manifestMs
manifestMs:
number
totals.readMs
readMs:
number
totals.reconcileMs
reconcileMs:
number
totals.registerMs
registerMs:
number
totals.sealMs
sealMs:
number
totals.swapMs
swapMs:
number
totals.totalMs
totalMs:
number
A lower bound on Workers, where a pure-SQL tick reads 0.
updatedAt?
optionalupdatedAt?:string|null