AttachSyncClientOptions

Defined in: packages/client/src/worker/attach-sync-client.ts:590

Type Parameters

TRegistry

TRegistry extends SyncTableRegistry

Properties

awaitOwnershipRelease?

optional awaitOwnershipRelease?: () => Promise<void>

Defined in: packages/client/src/worker/attach-sync-client.ts:731

Await the VFS ownership release after a deliberate engine termination (ADR-0049 step 8). Defaults to the documented no-op resolvedOwnershipRelease — the HONEST MINIMUM (step 11b follow-up 1): the OPFS-repacked VFS enforces ownership with EXCLUSIVE OPFS sync-access handles (StoreOwnedError / STORE_OWNED), NOT a Web Lock, so there is no lock name to navigator.locks.request(..., { ifAvailable }) against here. The bounded wait therefore lives in the SUCCESSOR’S OPEN PATH: the respawned elected engine worker’s own createOpfsRepacked open throws the owned-store contention error and is retried with backoff (the openWithBoundedRetries wrapper in createClientPGlite) until the dead worker’s agent releases the handle — exactly the fault-matrix row “VFS ownership-lock release lag → successor open retries on contention until clear, bounded, then boot failure”. Supply a custom async wait only to inject a real probe (tests do).

Returns

Promise<void>

---

bridgeSilenceMs?

optional bridgeSilenceMs?: number

Defined in: packages/client/src/worker/attach-sync-client.ts:676

The bridge-silence deadline (ms) for non-leader reconnection (ADR-0049 D5). DISABLED when undefined (the default); the election coordinator (step 8) sets it. When set: a pending op left with NO bridge traffic since it was posted, past this deadline, triggers ONE reconnect attempt via the worker FACTORY (if the input is a factory) — construct a fresh SharedWorker, resolve its port, re-attach, flush the queue, re-subscribe. With a bare-instance input reconstruction is structurally unavailable, so no reconnect is armed. Scheduled on timers.

---

codec?

optional codec?: BridgeCodec

Defined in: packages/client/src/worker/attach-sync-client.ts:655

---

createEngineWorker?

optional createEngineWorker?: () => ElectedEngineWorker

Defined in: packages/client/src/worker/attach-sync-client.ts:700

The elected engine worker OVERRIDE (ADR-0049 D5). In elected-worker placement (a router-only SharedWorker) the tab’s election coordinator spawns the real engine as a dedicated Worker. NORMALLY NO WIRING IS NEEDED: the worker entry is dual-scope (one file serves both homes), the SharedWorker reports its own script URL in the placement reply, and the winning tab constructs the engine as new Worker(swScriptUrl, { type: "module" }) itself. Supply this override ONLY for entries that cannot be reconstructed from their URL as a module worker (classic-script workers, blob:/data: URLs, CSP constraints); wrap the constructed worker with wrapEngineWorker. When election is required but NEITHER a derivable URL NOR this override is available, attach fails with the typed ElectedEngineUnconstructibleError — never a silent no-engine attach.

Returns

ElectedEngineWorker

---

executionLimit?

optional executionLimit?: ExecutionLimitConfig

Defined in: packages/client/src/worker/attach-sync-client.ts:711

The opt-in engine-construction EXECUTION LIMIT (ADR-0049 D5) as this tab carries it — every tab attaching to a store MUST carry the SAME value the worker was constructed with (ExecutionLimitMismatchError on a mismatch). DISABLED by default (undefined / absent maxDispatchMs) — no finite worst-case query duration exists, so enabling the limit (which converts slow to terminated by policy) is a deliberate consumer choice. When maxDispatchMs is set AND this tab is on an elected per-tab pipe, a dispatched RPC still outstanding past the limit is reported to the router as an overdue-dispatch (the router then probes the engine’s control channel; a WASM-blocked engine cannot answer → the leader retires + respawns it). ELECTED PLACEMENT ONLY — on SW-direct the option is rejected as unsupported during attach rather than silently ignored.

---

freshStore?

optional freshStore?: boolean

Defined in: packages/client/src/worker/attach-sync-client.ts:629

Fresh-store prefetch-overlap hint (ADR-0032 S4), forwarded in the attach config.freshStore. Set true ONLY when the tab knows the store is a claimed schemaless spare (never for a mapped/returning store); the worker’s createSyncClient then overlaps the shape catch-up with its local boot phases.

---

getToken?

optional getToken?: () => Promise<AuthTokenSnapshot | null>

Defined in: packages/client/src/worker/attach-sync-client.ts:608

The tab’s token provider (ADR-0032 decision 3). Richer than createSyncClient’s string form: the worker needs the EXPIRY to apply its pull margin, so this yields {accessToken, expiresAt} (or null when unauthenticated). Pushed at attach and answered on every worker pull-request.

Returns

Promise<AuthTokenSnapshot | null>

---

handoffQueue?

optional handoffQueue?: object

Defined in: packages/client/src/worker/attach-sync-client.ts:684

The bounded handoff queue (ADR-0049 invariant 9). While the handoff window is open — after a relocation notice, before the replacement pipe’s handshake completes — new data-path ops are QUEUED, not posted. cap overflow or deadlineMs expiry fails queued ops with EngineRelocatedError("not-dispatched") (they never left the tab, so they are safe to retry). Defaults: cap 256, deadlineMs 15000. The deadline is scheduled on timers.

cap?

optional cap?: number

deadlineMs?

optional deadlineMs?: number

---

keepaliveIntervalMs?

optional keepaliveIntervalMs?: number

Defined in: packages/client/src/worker/attach-sync-client.ts:717

The leader-keepalive ping cadence (ms) the election coordinator uses (ADR-0049 step 8). Default 20000. The keepalive is the ONE standing timer that detects SharedWorker death (unanswered pings) → reconstruct via the worker factory + re-announce the still-live engine. Lower it to detect SW death faster.

---

keepaliveMissThreshold?

optional keepaliveMissThreshold?: number

Defined in: packages/client/src/worker/attach-sync-client.ts:719

Consecutive unanswered keepalive pings before SharedWorker reconstruction (ADR-0049 step 8). Default 2.

---

onBootReport?

optional onBootReport?: (report) => void

Defined in: packages/client/src/worker/attach-sync-client.ts:667

Boot observability (ADR-0034): invoked once with the worker engine’s finalized BootReport if the engine’s boot finalizes WHILE this tab is attached (the one-shot boot-report broadcast). A tab that attaches AFTER the boot never receives the push — it reads the report via SyncClient.bootReport.

Parameters

report

BootReport

Returns

void

---

onConflict?

optional onConflict?: (details) => void

Defined in: packages/client/src/worker/attach-sync-client.ts:657

Parameters

details

MutationDetail[]

Returns

void

---

onQuarantine?

optional onQuarantine?: (details) => void

Defined in: packages/client/src/worker/attach-sync-client.ts:658

Parameters

details

MutationDetail[]

Returns

void

---

onReject?

optional onReject?: (details) => void

Defined in: packages/client/src/worker/attach-sync-client.ts:659

Parameters

details

MutationDetail[]

Returns

void

---

onSchemaChange?

optional onSchemaChange?: (event) => void

Defined in: packages/client/src/worker/attach-sync-client.ts:660

Parameters

event

LocalStoreVersionEvent

Returns

void

---

onStatusChange?

optional onStatusChange?: (status) => void

Defined in: packages/client/src/worker/attach-sync-client.ts:656

Parameters

status

SyncRuntimeStatus

Returns

void

---

onSyncError?

optional onSyncError?: (error) => void

Defined in: packages/client/src/worker/attach-sync-client.ts:661

Parameters

error

Error

Returns

void

---

port?

optional port?: BridgePort

Defined in: packages/client/src/worker/attach-sync-client.ts:602

A raw transport port (a MessageChannel port in tests, a SharedWorker.port in a browser).

---

registry

registry: TRegistry

Defined in: packages/client/src/worker/attach-sync-client.ts:591

---

restoreFrom?

optional restoreFrom?: File | Blob

Defined in: packages/client/src/worker/attach-sync-client.ts:643

Restore the worker’s store from a backup on attach (ADR-0035 decision 6) — the worker-mode restoreFrom. A File/Blob as produced by SyncClient.exportStore; the facade decomposes it into a transferred ArrayBuffer + name/mime (RestoreArtefactWire) and the worker recomposes it for createSyncClient. Restore rides the one handshake that reaches the ENGINE HOME: a restore-bearing attach awaits the placement reply, then carries the artifact on the SW-port handshake when the in-scope host is the engine (SW-direct / declared-idbfs) or on the first per-tab PIPE handshake when the engine is elected — the router-only SharedWorker is payload-blind, so a restore posted there would be dropped and destroyed. Passing it when the engine has ALREADY booted rejects the attach with a typed error (RestoreIntoRunningStoreError by name — you cannot restore into a running store). The restored engine boots offline and its recovered journal is quarantined, exactly as in-process — see restoreFrom on createSyncClient.

---

role?

optional role?: string

Defined in: packages/client/src/worker/attach-sync-client.ts:623

Which baked registry the worker boots (ADR-0032 S3) — forwarded in the attach config.role. A worker file that bakes multiple role variants (the board’s admin/member) picks by this; single-registry workers ignore it.

---

storage?

optional storage?: SyncStorageDeclaration

Defined in: packages/client/src/worker/attach-sync-client.ts:654

The tab’s WIRE storage declaration for this store (ADR-0050) — posted as the declaration message on the worker port BEFORE the placement query (so backend: "idbfs" can skip the probe), and carried on the provision/attach payloads so the engine binds it (durability included). Omit (or {}) for “no opinion”: a registry-attached static declaration, else the capability defaults, decide. A registry-attached declaration is AUTHORITATIVE — an explicit field here that disagrees with it (or with the declaration another tab already bound) is a typed refusal (StorageDeclarationRefusedError), never silently overridden: a store’s declaration is immutable, and a preference change mints a fresh store under a fresh path instead.

---

storeId?

optional storeId?: string

Defined in: packages/client/src/worker/attach-sync-client.ts:610

The bound store id (resolved tab-side before attach — SharedWorker naming, ADR-0032 decision 5).

---

storePath?

optional storePath?: string

Defined in: packages/client/src/worker/attach-sync-client.ts:616

The plain store PATH (ADR-0036) the worker opens if it must create its own store — a name, not a storage URL. Spread memoryStoreForTests(...) from @pgxsinkit/client/testing here for a memory store in tests (it also carries the internal marker forwarded to the worker as the memory-backend override).

---

syncEnabled?

optional syncEnabled?: boolean

Defined in: packages/client/src/worker/attach-sync-client.ts:617

---

timers?

optional timers?: AttachClientTimers

Defined in: packages/client/src/worker/attach-sync-client.ts:689

Injectable timers for the handoff-queue deadline and the bridge-silence reconnect (ADR-0049 step 7) — the same deterministic-test seam engine-router.ts exposes. Defaults to globalThis.setTimeout/clearTimeout.

---

worker?

optional worker?: WorkerLike | (() => WorkerLike)

Defined in: packages/client/src/worker/attach-sync-client.ts:600

The worker input — PRIMARILY a FACTORY () => SharedWorker (ADR-0049 D5). A SharedWorker object cannot be reconstructed from itself, so the factory is what makes SharedWorker-death recovery (the keepalive reconstruction, and the bridgeSilenceMs bridge-silence reconnect) a GUARANTEE rather than an option: both re-invoke it for a fresh SharedWorker. A bare instance (a native Worker/SharedWorker, or anything port-shaped) is ALSO accepted for tests and exotic hosts — reconstruction is then structurally unavailable (diagnostics say so). Provide this OR port.