BootReport
Defined in: packages/client/src/boot-report.ts:21
A structured, versioned record of one client boot (ADR-0034). reportVersion is a contract number:
additive fields keep it, a breaking reshape bumps it. All durations are milliseconds; all *AtMs are
offsets from boot start (the startedAt epoch anchor is the only wall-clock value).
Properties
Section titled “Properties”engineHome?
Section titled “engineHome?”
optionalengineHome?:"in-process"|"shared-worker"|"elected-worker"
Defined in: packages/client/src/boot-report.ts:50
Where the engine ran for this boot (ADR-0049 decision 12): "in-process" for the main-thread/Bun
createSyncClient; inside defineSyncWorker, the placement-probe result — "shared-worker" (the engine boots
in the SharedWorker itself, WebKit today) or "elected-worker" (a tab-spawned dedicated worker holds the
handles, Chromium/Firefox). Absent (omitted) when the boot cannot derive it (e.g. a dedicated elected-engine
worker that never ran the SharedWorker placement decision). Additive field; reportVersion stays 1.
freshStore
Section titled “freshStore”freshStore:
boolean
Defined in: packages/client/src/boot-report.ts:26
Whether the caller proved the store a schemaless spare (the ADR-0032 S4 fresh-store hint).
groups
Section titled “groups”groups:
object[]
Defined in: packages/client/src/boot-report.ts:139
Per consistency GROUP, for the eager + promoted boot groups only (a lazily-activated-later group never
appears — nor mutates a finalized report). Groups run concurrently, so fetchMs/applyMs are per-group
wall SEGMENTS, not a partition of totalMs.
applyMs
Section titled “applyMs”applyMs:
number
Wall around this group’s batch commits into PGlite. Includes waiting behind another group’s
transaction on the shared connection (single writer), so concurrent groups’ applyMs can overlap.
fetchMs
Section titled “fetchMs”fetchMs:
number
Settle→next-delivery wall within this group’s chain. On the single-threaded WASM host this absorbs OTHER groups’ apply transactions and main-thread work between deliveries — read it as “time this group spent not applying”, an upper bound on its network wait, not pure network cost.
groupKey
Section titled “groupKey”groupKey:
string
readyAtMs
Section titled “readyAtMs”readyAtMs:
number
Offset from boot start when the group reached its initial sync.
requests
Section titled “requests”requests:
number
Number of batch deliveries the group’s stream chain received during boot catch-up.
rows:
number
Number of change rows ingested during boot catch-up.
startedAtMs
Section titled “startedAtMs”startedAtMs:
number
Offset from boot start when the group’s streams started.
tables
Section titled “tables”tables:
number
Number of member tables (shapes) in the group.
localReadReadyMs
Section titled “localReadReadyMs”localReadReadyMs:
number|null
Defined in: packages/client/src/boot-report.ts:73
Boot start → localReadReady resolved (ADR-0041): PGlite open, durable schema compatible, store-version
reconcile complete, and the drizzle read facade built — cached reads are safe with ZERO network. null
when the boot rejected before the stage. Additive field; reportVersion stays 1.
mode:
"in-process"|"worker"
Defined in: packages/client/src/boot-report.ts:24
How the engine booted: the in-process client (bun/Node/fallback) or inside defineSyncWorker.
overlapPrefetch
Section titled “overlapPrefetch”overlapPrefetch:
boolean
Defined in: packages/client/src/boot-report.ts:61
Whether the ADR-0032 S4 fetch/schema overlap was active for this boot.
phases
Section titled “phases”phases:
object
Defined in: packages/client/src/boot-report.ts:91
catchupMs
Section titled “catchupMs”catchupMs:
number
Sync-start done → last eager boot group ready.
journalRecoveryMs
Section titled “journalRecoveryMs”journalRecoveryMs:
number
pgliteCreateMs
Section titled “pgliteCreateMs”pgliteCreateMs:
number|null
PGlite create cost, or null when the store was adopted from a spare (see BootReport.provision).
prepareMs?
Section titled “prepareMs?”
optionalprepareMs?:number
Cumulative time in configured prepare hooks (prepareLocalDbBeforeSchema + prepareLocalDbAfterSchema), present
only when at least one hook is configured. Not part of the required v1 shape (ADR-0034).
schemaExecMs
Section titled “schemaExecMs”schemaExecMs:
number
storeVersionReconcileMs
Section titled “storeVersionReconcileMs”storeVersionReconcileMs:
number
syncStartMs
Section titled “syncStartMs”syncStartMs:
number
startConfiguredSync: stream/group construction wall. On an overlap boot (ADR-0032 S4,
BootReport.overlapPrefetch) the early-started segment runs concurrently with schema, journal
recovery, and registry reconciliation, so this includes that shared wall. Structurally 0 when the boot
is ready inside the
sync-start call itself (zero eager groups / instant catch-up) — finalize runs before the phase closes.
provision
Section titled “provision”provision: {
initdbMs:number;provisionedMsBeforeBoot:number; } |null
Defined in: packages/client/src/boot-report.ts:85
Present only when the store was pre-provisioned (a spare’s initdb ran off-thread before this boot
adopted it); null otherwise. When present, phases.pgliteCreateMs is null — the create cost is
reported here instead.
Union Members
Section titled “Union Members”Type Literal
Section titled “Type Literal”{ initdbMs: number; provisionedMsBeforeBoot: number; }
initdbMs
Section titled “initdbMs”initdbMs:
number
The spare’s PGlite create (initdb) cost, paid at provision time.
provisionedMsBeforeBoot
Section titled “provisionedMsBeforeBoot”provisionedMsBeforeBoot:
number
How long the provisioned store sat ready before this boot adopted it.
null
registryFingerprint
Section titled “registryFingerprint”registryFingerprint:
string
Defined in: packages/client/src/boot-report.ts:63
The registry fingerprint the store is provisioned under — the same value store-version reconcile stamps.
reportVersion
Section titled “reportVersion”reportVersion:
1
Defined in: packages/client/src/boot-report.ts:22
startedAt
Section titled “startedAt”startedAt:
number
Defined in: packages/client/src/boot-report.ts:65
Epoch anchor (Date.now()) at boot start; every other duration/offset is monotonic relative to it.
storageBackend?
Section titled “storageBackend?”
optionalstorageBackend?:"opfs-repacked"|"idbfs"|"filesystem"|"memory"
Defined in: packages/client/src/boot-report.ts:42
The store backend this boot actually opened (ADR-0049 decision 12): "opfs-repacked" (the placement probe
granted sync-access handles in the engine home), "idbfs" (browser/worker, handles denied — today’s default),
"filesystem" (Bun/Node), or "memory" (the sanctioned test/ephemeral lane). Derived from the minted dataDir
scheme at the single client-owned mint seam; absent (omitted) on a BYO instance whose backend is underivable.
Additive field; reportVersion stays 1. Distinct from BootReport.storeKind, which is untouched.
storageFallbackReason?
Section titled “storageFallbackReason?”
optionalstorageFallbackReason?:string
Defined in: packages/client/src/boot-report.ts:59
The verbatim reason an opfs-CAPABLE boot (the probe granted sync-access handles) nonetheless opened idbfs
(ADR-0049 decision 12). Set ONLY when such a fallback actually occurred — never on a plain idb boot (the probe
denied from the start), and never on a granted opfs boot that stayed on opfs. Today’s set-sites are the
granted-then-idb transitions the client owns: the recordless idb-store downgrade (invariant 14 — an existing
idb store is opened in place, never overwritten by a fresh opfs mint) and the virgin-uncreatable session
idbfs fallback (the verbatim opfs open failure). Additive field; reportVersion stays 1.
storeKind
Section titled “storeKind”storeKind:
"fresh"|"warm"|"restored"
Defined in: packages/client/src/boot-report.ts:34
How this store presented at boot: "restored" when the boot seeded a brand-new store from a backup
(ADR-0035 restoreFrom); "fresh" when the caller proved it a schemaless spare (the SAME signal as
BootReport.freshStore); "warm" otherwise (an existing persisted store — the common case).
Distinct from freshStore, which stays a bare boolean: storeKind additionally names the restore case,
which a boolean cannot express.
totalMs
Section titled “totalMs”totalMs:
number
Defined in: packages/client/src/boot-report.ts:67
Boot start → onInitialSync (all eager groups caught up).
warmBoot
Section titled “warmBoot”warmBoot:
object
Defined in: packages/client/src/boot-report.ts:117
Warm-store observability for the durable-schema and journal-recovery fast paths. Grouped like BootReport.phases so the flags structured-clone across the worker bridge as one unit.
journalRecoveryRequired
Section titled “journalRecoveryRequired”journalRecoveryRequired:
boolean
Whether the durable recovery marker required journal recovery this boot. A clean settle clears the marker, allowing the next boot to skip the recovery pass.
journalRecoverySkipped
Section titled “journalRecoverySkipped”journalRecoverySkipped:
boolean
Whether the boot-time recoverSending journal pass was skipped this boot.
journalRowsRecovered
Section titled “journalRowsRecovered”journalRowsRecovered:
number|null
Rows lifted sending → pending by recovery; null when the selected recovery path cannot count them.
journalTablesVisited
Section titled “journalTablesVisited”journalTablesVisited:
number
How many writable table journals the boot-time recoverSending pass visited (the registry’s writable-entry count).
schemaFingerprintMatch
Section titled “schemaFingerprintMatch”schemaFingerprintMatch:
boolean
Whether the stored durable-schema fingerprint matched the generated schema.
schemaSkipped
Section titled “schemaSkipped”schemaSkipped:
boolean
Whether durable-schema replay was skipped this boot because the stored fingerprint matched.
writeReadyMs
Section titled “writeReadyMs”writeReadyMs:
number|null
Defined in: packages/client/src/boot-report.ts:79
Boot start → writeReady resolved (ADR-0041): the mutation runtime is constructed and boot recovery
(plus restore quarantine on a restore boot) has completed — enqueue is safe. null when the boot
rejected before the stage. Additive field; reportVersion stays 1.