@lix-js/sdk 0.16.1 → 0.17.0

package/dist/worker/factory.browser.js

@@ -1,4 +1,5 @@
 /// <reference lib="webworker" />
+import { deserializeWorkerError } from "./protocol.js";
 // Browser/Wasm execution stays off the main thread.
 export const openDirectLixBinding = undefined;
 export function createWorkerConnection() {
@@ -14,7 +15,7 @@ export function createWorkerConnection() {
             worker.onmessage = (event) => listener(event.data);
         },
         onFatal(listener) {
-            worker.onerror = (event) => listener(event.error ?? new Error(event.message ?? "Lix worker failed"));
+            worker.onerror = (event) => listener(workerFailure(event));
         },
         ref() { },
         unref() { },
@@ -23,3 +24,66 @@ export function createWorkerConnection() {
         },
     };
 }
+/** Package-private provider identity selects one engine, not one engine per tab. */
+export function createSharedWorkerConnection(key) {
+    if (typeof SharedWorker === "undefined" || !navigator.locks)
+        throw new Error("Shared partial replicas require SharedWorker and Web Locks");
+    const worker = new SharedWorker(new URL("./entry.shared.browser.js", import.meta.url), { type: "module", name: key });
+    const port = worker.port;
+    const leaseName = `lix:shared-client:${crypto.randomUUID()}`;
+    let release;
+    const lifetime = new Promise(resolve => { release = resolve; });
+    let ready;
+    const acquired = new Promise(resolve => { ready = resolve; });
+    let failure;
+    void navigator.locks.request(leaseName, async () => { ready(); await lifetime; }).catch(error => failure?.(error));
+    void acquired.then(() => port.postMessage({ kind: "shared.clientLease", name: leaseName }));
+    port.start();
+    let closed = false;
+    let termination;
+    let disconnected;
+    const detached = new Promise((resolve, reject) => { disconnected = error => error ? reject(error) : resolve(); });
+    return {
+        postMessage(message) { if (closed)
+            throw new Error("Shared engine connection closed"); port.postMessage(message); },
+        onMessage(listener) {
+            port.onmessage = event => {
+                if (event.data?.kind === "shared.disconnected") {
+                    const error = event.data.error;
+                    disconnected(error ? deserializeWorkerError(error) : undefined);
+                }
+                else
+                    listener(event.data);
+            };
+        },
+        onFatal(listener) { failure = listener; worker.onerror = event => listener(workerFailure(event)); },
+        ref() { }, unref() { },
+        terminate() {
+            if (termination)
+                return termination;
+            termination = (async () => {
+                closed = true;
+                port.postMessage({ kind: "shared.disconnect" });
+                release();
+                let timeout;
+                try {
+                    await Promise.race([detached, new Promise((_, reject) => {
+                            timeout = setTimeout(() => reject(Object.assign(new Error("Shared engine close was not acknowledged"), { code: "LIX_SHARED_ENGINE_CLOSE_UNCONFIRMED" })), 10000);
+                        })]);
+                }
+                finally {
+                    if (timeout !== undefined)
+                        clearTimeout(timeout);
+                    port.close();
+                }
+            })();
+            return termination;
+        },
+    };
+}
+function workerFailure(event) {
+    if (event.error instanceof Error)
+        return event.error;
+    const location = event.filename ? ` (${event.filename}:${event.lineno ?? 0}:${event.colno ?? 0})` : "";
+    return Object.assign(new Error(`${event.message || "Lix worker failed to load or execute"}${location}`), { code: "LIX_WORKER_FAILED" });
+}

package/dist/worker/factory.node.d.ts

@@ -3,3 +3,4 @@ import type { WorkerConnection } from "./protocol.js";
 export declare function createWorkerConnection(): WorkerConnection;
 export declare function workerExecArgv(execArgv: readonly string[]): string[];
 export declare const openDirectLixBinding: (storage: LixStorageConfig, telemetry?: TelemetryDispatch, telemetryParent?: TelemetryParentContext, server?: SyncServerBindingOptions, openProgress?: OpenProgressDispatch, snapshot?: ReadableStream<Uint8Array>) => Promise<LixBinding | undefined>;
+export declare function createSharedWorkerConnection(_key: string): WorkerConnection | undefined;

package/dist/worker/factory.node.js

@@ -55,3 +55,6 @@ export function workerExecArgv(execArgv) {
 export const openDirectLixBinding = async (storage, telemetry, telemetryParent, server, openProgress, snapshot) => {
     return openLixBinding(storage, telemetry, telemetryParent, server, openProgress, snapshot);
 };
+export function createSharedWorkerConnection(_key) {
+    return undefined;
+}

package/dist/worker/host.d.ts

@@ -1,4 +1,6 @@
-import { openLixBinding } from "#binding";
+import { openLixBinding, convertReplicaBinding } from "#binding";
 import { type WorkerHostEndpoint, type WorkerSyncFetchResponse } from "./protocol.js";
-export declare function startWorkerHost(endpoint: WorkerHostEndpoint, openBinding?: typeof openLixBinding): void;
+export declare function startWorkerHost(endpoint: WorkerHostEndpoint, openBinding?: typeof openLixBinding, convertBinding?: typeof convertReplicaBinding): {
+    close(): Promise<void>;
+};
 export declare function responseFromSyncFetch(resolved: WorkerSyncFetchResponse): Response;

package/dist/worker/host.js

@@ -1,6 +1,8 @@
-import { openLixBinding, createHostedBinding, deleteHostedBinding, } from "#binding";
+import { validateHttpRequest } from "../http-transport.js";
+import { openLixBinding, convertReplicaBinding, retryReplicaMigrationCleanupBinding, createHostedBinding, deleteHostedBinding, } from "#binding";
 import { deserializeWorkerError, serializeWorkerError, } from "./protocol.js";
-export function startWorkerHost(endpoint, openBinding = openLixBinding) {
+export function startWorkerHost(endpoint, openBinding = openLixBinding, convertBinding = convertReplicaBinding) {
+    let closed = false;
     const sessions = new Map();
     let nextSessionId = 1;
     let nextTransactionId = 1;
@@ -16,7 +18,10 @@ export function startWorkerHost(endpoint, openBinding = openLixBinding) {
     const pendingSyncStreamPulls = new Map();
     const syncStreamCleanup = new Map();
     let finiteQueue = Promise.resolve();
+    const registrations = new Set();
     endpoint.onMessage((message) => {
+        if (closed && "id" in message)
+            return;
         if (!("id" in message)) {
             handleNotification(message);
             return;
@@ -54,15 +59,21 @@ export function startWorkerHost(endpoint, openBinding = openLixBinding) {
             // finite-operation queue lets a long-running operation block a newly
             // mounted query, including one that needs lazy history hydration.
             // The live `next()` lane is already independent for the same reason.
-            void respond(message, () => handleObserveRegistration(message.sessionId, operation.sql, operation.params));
+            const registration = respond(message, () => handleObserveRegistration(message.sessionId, operation.sql, operation.params));
+            registrations.add(registration);
+            void registration.finally(() => registrations.delete(registration));
             return;
         }
         finiteQueue = finiteQueue.then(async () => {
             try {
                 await respond(message, async () => {
+                    if (closed)
+                        throw workerStateError("Worker client disconnected");
                     if (message.operation.kind !== "open" &&
                         message.operation.kind !== "hosted.create" &&
-                        message.operation.kind !== "hosted.delete") {
+                        message.operation.kind !== "hosted.delete" &&
+                        message.operation.kind !== "replica.convert" &&
+                        message.operation.kind !== "replica.cleanup") {
                         requiredLix(message.sessionId).setTelemetryParent(message.telemetryParent);
                     }
                     return handleFiniteOperation(message.sessionId, message.operation, message.telemetryParent);
@@ -165,6 +176,14 @@ export function startWorkerHost(endpoint, openBinding = openLixBinding) {
     }
     async function handleFiniteOperation(sessionId, operation, telemetryParent) {
         switch (operation.kind) {
+            case "replica.cleanup":
+                if (sessions.size > 0)
+                    throw workerStateError("Migration cleanup requires closed storage");
+                return retryReplicaMigrationCleanupBinding(operation.storage, createSyncServerBridge(operation.server));
+            case "replica.convert":
+                if (sessions.size > 0)
+                    throw workerStateError("Conversion requires closed storage");
+                return convertBinding(operation.storage, createSyncServerBridge(operation.server), operation.branchId);
             case "hosted.create":
                 return createHostedBinding(operation.server);
             case "hosted.delete":
@@ -221,8 +240,7 @@ export function startWorkerHost(endpoint, openBinding = openLixBinding) {
             case "transaction.commit": {
                 const transaction = requiredTransaction(operation.transactionId);
                 transactions.delete(operation.transactionId);
-                await transaction.commit();
-                return undefined;
+                return await transaction.commit();
             }
             case "transaction.rollback": {
                 const transaction = requiredTransaction(operation.transactionId);
@@ -236,6 +254,10 @@ export function startWorkerHost(endpoint, openBinding = openLixBinding) {
                 return requiredLix(sessionId).exportReplicaRecovery(operation.id);
             case "recoverReplica":
                 return requiredLix(sessionId).recoverReplica(operation.id);
+            case "recoverReplicaWithServer":
+                return requiredLix(sessionId).recoverReplicaWithServer(operation.id, createSyncServerBridge(operation.server, operation.transportScope));
+            case "syncHealth":
+                return requiredLix(sessionId).syncHealth();
             case "activeBranchId":
                 return requiredLix(sessionId).activeBranchId();
             case "activeAccountId":
@@ -328,7 +350,46 @@ export function startWorkerHost(endpoint, openBinding = openLixBinding) {
         }
         await input.writer.close();
     }
-    function createSyncServerBridge(server) {
+    return { async close() {
+            if (closed)
+                return;
+            closed = true;
+            const failure = workerStateError("Worker client disconnected");
+            for (const pending of pendingSyncHeaders.values())
+                pending.reject(failure);
+            pendingSyncHeaders.clear();
+            for (const pending of pendingSyncFetch.values())
+                pending.reject(failure);
+            pendingSyncFetch.clear();
+            for (const cleanup of syncStreamCleanup.values())
+                cleanup();
+            syncStreamCleanup.clear();
+            for (const pending of pendingSyncStreamPulls.values()) {
+                pending.controller.error(failure);
+                pending.reject(failure);
+            }
+            pendingSyncStreamPulls.clear();
+            for (const observation of observations.values())
+                observation.close();
+            observations.clear();
+            for (const snapshot of snapshotExports.values())
+                await Promise.resolve(snapshot.cancel()).catch(() => undefined);
+            snapshotExports.clear();
+            await finiteQueue.catch(() => undefined);
+            await Promise.allSettled(registrations);
+            // The active finite operation has finished; never roll back a handle
+            // concurrently with its execute/commit operation.
+            for (const transaction of transactions.values())
+                await transaction.rollback().catch(() => undefined);
+            transactions.clear();
+            for (const snapshot of snapshotExports.values())
+                await Promise.resolve(snapshot.cancel()).catch(() => undefined);
+            snapshotExports.clear();
+            for (const session of sessions.values())
+                await session.close();
+            sessions.clear();
+        } };
+    function createSyncServerBridge(server, transportScope) {
         if (!server)
             return undefined;
         return {
@@ -336,48 +397,37 @@ export function startWorkerHost(endpoint, openBinding = openLixBinding) {
             headers: server.headers ?? [],
             headerProvider: server.dynamicHeaders
                 ? () => {
+                    if (closed)
+                        throw workerStateError("Worker client disconnected");
                     const requestId = nextSyncRequestId++;
                     return new Promise((resolve, reject) => {
                         pendingSyncHeaders.set(requestId, { resolve, reject });
-                        endpoint.postMessage({ kind: "sync.headers", requestId });
+                        endpoint.postMessage({ kind: "sync.headers", requestId, transportScope });
                     });
                 }
                 : undefined,
-            fetch: server.customFetch ? bridgeFetch : undefined,
+            transport: (request) => bridgeFetch(request, transportScope),
         };
     }
-    async function bridgeFetch(input, init) {
-        const extension = init;
-        const streaming = extension?.lixResponseStream === true;
-        const responseLimit = extension?.lixResponseLimit;
-        if (!streaming &&
-            (typeof responseLimit !== "number" ||
-                !Number.isSafeInteger(responseLimit) ||
-                responseLimit <= 0)) {
-            throw new TypeError("Browser sync fetch has no valid response limit");
-        }
+    async function bridgeFetch(httpRequest, transportScope) {
+        validateHttpRequest(httpRequest);
+        const { url: input, init, response: policy } = httpRequest;
+        const streaming = policy.mode === "streaming";
+        if (closed)
+            throw workerStateError("Worker client disconnected");
         const requestId = nextSyncRequestId++;
         const requestBase = {
-            url: typeof input === "string"
-                ? input
-                : input instanceof URL
-                    ? input.toString()
-                    : input.url,
+            url: input,
             method: init?.method ?? "GET",
             headers: headerEntries(init?.headers),
             body: serializableBody(init?.body),
             credentials: init?.credentials,
+            cache: init?.cache, redirect: init?.redirect,
         };
-        const request = streaming
-            ? { ...requestBase, responseMode: "stream" }
-            : {
-                ...requestBase,
-                responseMode: "buffered",
-                responseLimit: responseLimit,
-            };
+        const request = { ...requestBase, response: policy };
         const response = new Promise((resolve, reject) => {
             pendingSyncFetch.set(requestId, { resolve, reject });
-            endpoint.postMessage({ kind: "sync.fetch", requestId, request });
+            endpoint.postMessage({ kind: "sync.fetch", requestId, request, transportScope });
         });
         const abort = () => {
             const pending = pendingSyncFetch.get(requestId);
@@ -469,6 +519,10 @@ export function startWorkerHost(endpoint, openBinding = openLixBinding) {
         // serialized finite lane. Each `observe.next` supplies telemetry directly
         // to its observation binding.
         const events = await requiredLix(sessionId).observe(sql, params);
+        if (closed) {
+            events.close();
+            throw workerStateError("Worker client disconnected");
+        }
         const observeId = nextObserveId++;
         observations.set(observeId, events);
         return observeId;

package/dist/worker/protocol.d.ts

@@ -1,10 +1,10 @@
+import type { HttpResponsePolicy } from "../http-transport.js";
 import type { BindingBatchStatement, BindingParam, LixStorageConfig } from "../binding-types.js";
 import type { CreateBranchOptions, ExecuteOptions, LixBatchOptions, MergeBranchOptions, SwitchBranchOptions, LixTelemetrySpan, LixTelemetryParentContext, LixOpenProgress, OpenAnotherSessionOptions } from "../types.js";
 export type WorkerSyncServerOptions = {
     url: string;
     headers?: [string, string][];
     dynamicHeaders: boolean;
-    customFetch: boolean;
 };
 export type WorkerSyncFetchRequest = {
     url: string;
@@ -12,12 +12,10 @@ export type WorkerSyncFetchRequest = {
     headers: [string, string][];
     body?: string | Uint8Array;
     credentials?: RequestCredentials;
-} & ({
-    responseMode: "buffered";
-    responseLimit: number;
-} | {
-    responseMode: "stream";
-});
+    cache?: RequestCache;
+    redirect?: RequestRedirect;
+    response: HttpResponsePolicy;
+};
 type WorkerSyncFetchResponseHead = {
     status: number;
     statusText: string;
@@ -36,6 +34,15 @@ export type WorkerRequest = {
     operation: WorkerOperation;
 };
 export type WorkerOperation = {
+    kind: "replica.cleanup";
+    storage: LixStorageConfig;
+    server: WorkerSyncServerOptions;
+} | {
+    kind: "replica.convert";
+    storage: LixStorageConfig;
+    server: WorkerSyncServerOptions;
+    branchId?: string;
+} | {
     kind: "hosted.create";
     server: import("../binding-types.js").HostedServerBindingOptions;
 } | {
@@ -92,6 +99,13 @@ export type WorkerOperation = {
 } | {
     kind: "recoverReplica";
     id: string;
+} | {
+    kind: "recoverReplicaWithServer";
+    id: string;
+    server: WorkerSyncServerOptions;
+    transportScope: number;
+} | {
+    kind: "syncHealth";
 } | {
     kind: "activeBranchId";
 } | {
@@ -193,6 +207,7 @@ export type WorkerHostEndpoint = {
     onMessage(listener: (message: WorkerInput) => void): void;
 };
 export type SerializedWorkerError = {
+    cause?: SerializedWorkerError;
     name: string;
     message: string;
     stack?: string;
@@ -217,10 +232,12 @@ export type WorkerResponse = {
 } | {
     kind: "sync.headers";
     requestId: number;
+    transportScope?: number;
 } | {
     kind: "sync.fetch";
     requestId: number;
     request: WorkerSyncFetchRequest;
+    transportScope?: number;
 } | {
     kind: "sync.fetch.stream.pull";
     requestId: number;
@@ -228,6 +245,6 @@ export type WorkerResponse = {
     kind: "sync.fetch.cancel";
     requestId: number;
 };
-export declare function serializeWorkerError(error: unknown): SerializedWorkerError;
+export declare function serializeWorkerError(error: unknown, depth?: number): SerializedWorkerError;
 export declare function deserializeWorkerError(error: SerializedWorkerError): Error;
 export {};

package/dist/worker/protocol.js

@@ -1,19 +1,20 @@
-export function serializeWorkerError(error) {
+export function serializeWorkerError(error, depth = 0) {
     if (!(error instanceof Error)) {
-        return { name: "Error", message: String(error) };
+        return { name: "Error", message: "Non-error failure" };
     }
     const lixError = error;
     return {
         name: error.name,
-        message: error.message,
-        stack: error.stack,
+        message: redactDiagnostic(error.message),
+        stack: error.stack ? redactDiagnostic(error.stack) : undefined,
         code: typeof lixError.code === "string" ? lixError.code : undefined,
-        hint: typeof lixError.hint === "string" ? lixError.hint : undefined,
-        details: lixError.details,
+        hint: typeof lixError.hint === "string" ? redactDiagnostic(lixError.hint) : undefined,
+        details: redactDetails(lixError.details),
+        cause: depth < 3 && error.cause !== undefined ? serializeWorkerError(error.cause, depth + 1) : undefined,
     };
 }
 export function deserializeWorkerError(error) {
-    const restored = new Error(error.message);
+    const restored = new Error(error.message, error.cause ? { cause: deserializeWorkerError(error.cause) } : undefined);
     restored.name = error.name;
     restored.stack = error.stack;
     restored.code = error.code;
@@ -21,3 +22,20 @@ export function deserializeWorkerError(error) {
     restored.details = error.details;
     return restored;
 }
+function redactDiagnostic(value) {
+    return value.slice(0, 4096).replace(/Bearer\s+[^\s,;"']+/gi, "Bearer [redacted]")
+        .replace(/((?:authorization|cookie|token|password|secret)\s*[:=]\s*)[^\n]+/gi, "$1[redacted]");
+}
+function redactDetails(value, depth = 0) {
+    if (depth > 3)
+        return "[truncated]";
+    if (typeof value === "string")
+        return redactDiagnostic(value);
+    if (value === null || typeof value === "number" || typeof value === "boolean" || value === undefined)
+        return value;
+    if (Array.isArray(value))
+        return value.slice(0, 32).map(item => redactDetails(item, depth + 1));
+    if (typeof value === "object")
+        return Object.fromEntries(Object.entries(value).slice(0, 32).map(([key, item]) => [key, /authorization|cookie|token|password|secret|headers/i.test(key) ? "[redacted]" : redactDetails(item, depth + 1)]));
+    return "[unsupported]";
+}

package/dist/worker/shared-admission.d.ts

@@ -0,0 +1,26 @@
+import { type HttpTransport } from "../http-transport.js";
+export declare const ADMISSION_PROTOCOL_EPOCH = 17;
+export declare const ADMISSION_STORAGE_EPOCH = 81;
+export type AdmissionIdentity = {
+    repositoryId: string;
+    principalId: string;
+    protocolEpoch: number;
+    storageEpoch: number;
+};
+export declare function sharedCredentialKey(url: string, headers: [string, string][]): string;
+export declare function sameAdmission(a: AdmissionIdentity, b: AdmissionIdentity): boolean;
+/** Authorize attachment, awaiting any server-owned repository upgrade. */
+export declare function requestAdmission(url: string, credentials: [string, string][], transport: HttpTransport): Promise<AdmissionIdentity>;
+/** Memory-only proofs grant cached local attachment, never remote authorization. */
+export declare class SharedAdmissionCache {
+    private readonly revocations;
+    private readonly proofs;
+    record(url: string, headers: [string, string][], identity: AdmissionIdentity): void;
+    generation(url: string, headers: [string, string][]): number;
+    remove(url: string, headers: [string, string][]): void;
+    persistLocal(url: string, headers: [string, string][], generation: number, write: () => Promise<void>, remove: () => Promise<void>): Promise<void>;
+    verify(url: string, headers: [string, string][], expected: AdmissionIdentity | undefined, probe: () => Promise<AdmissionIdentity>, allowOffline?: boolean): Promise<{
+        identity: AdmissionIdentity;
+        online: boolean;
+    }>;
+}

package/dist/worker/shared-admission.js

@@ -0,0 +1,116 @@
+import { HttpTransportError } from "../http-transport.js";
+export const ADMISSION_PROTOCOL_EPOCH = 17;
+export const ADMISSION_STORAGE_EPOCH = 81;
+const ANONYMOUS_ACCOUNT_ID = "00000000-0000-7000-8000-000000000002";
+export function sharedCredentialKey(url, headers) {
+    const entries = [];
+    new Headers(headers).forEach((value, key) => entries.push([key, value]));
+    return JSON.stringify([url, entries]);
+}
+export function sameAdmission(a, b) {
+    return a.repositoryId === b.repositoryId && a.principalId === b.principalId &&
+        a.protocolEpoch === b.protocolEpoch && a.storageEpoch === b.storageEpoch;
+}
+/** Authorize attachment, awaiting any server-owned repository upgrade. */
+export async function requestAdmission(url, credentials, transport) {
+    const locator = new URL(url);
+    const repositoryId = locator.pathname.match(/\/lix\/([0-9a-f-]{36})\/?$/i)?.[1];
+    if (!repositoryId || locator.search || locator.hash || locator.username || locator.password) {
+        throw new HttpTransportError("LIX_TRANSPORT_CONTRACT", "Admission requires a repository protocol URL");
+    }
+    const headers = new Headers(credentials);
+    headers.set("lix-sync-protocol-version", String(ADMISSION_PROTOCOL_EPOCH));
+    locator.pathname = `/lix/v1/${repositoryId}/admission`;
+    let response;
+    for (;;) {
+        response = await transport({ url: locator.toString(),
+            init: { method: "GET", headers, signal: AbortSignal.timeout(10_000), cache: "no-store", redirect: "error", credentials: "omit" },
+            response: { mode: "buffered", maxBytes: 16 * 1024 } });
+        if (response.status !== 503)
+            break;
+        const body = await response.clone().json().catch(() => null);
+        if (body?.error?.code !== "LIX_REPOSITORY_MIGRATING")
+            break;
+        // The authority owns the migration independently of this request. Poll only
+        // its explicit in-progress response; other failures retain their semantics.
+        await new Promise(resolve => setTimeout(resolve, 1_000));
+    }
+    if (response.status === 401 || response.status === 403) {
+        throw new HttpTransportError("LIX_ADMISSION_AUTH_REJECTED", "Authority rejected repository admission");
+    }
+    if (response.status === 409 || response.status === 426) {
+        throw new HttpTransportError("LIX_ADMISSION_EPOCH", "Repository is incompatible with this client version");
+    }
+    if (!response.ok)
+        throw new HttpTransportError("LIX_ADMISSION_HTTP", `Authority admission returned HTTP ${response.status}`);
+    let result;
+    try {
+        result = await response.json();
+    }
+    catch {
+        throw new HttpTransportError("LIX_ADMISSION_PROTOCOL", "Authority returned invalid admission metadata");
+    }
+    if (!result || result.repositoryId !== repositoryId ||
+        typeof result.principalId !== "string" || !/^[\x21-\x7e]{1,255}$/.test(result.principalId)) {
+        throw new HttpTransportError("LIX_ADMISSION_PROTOCOL", "Authority admission identity does not match the repository");
+    }
+    if (result.protocolEpoch !== ADMISSION_PROTOCOL_EPOCH || result.storageEpoch !== ADMISSION_STORAGE_EPOCH) {
+        throw new HttpTransportError("LIX_ADMISSION_EPOCH", "Repository is incompatible with this client version");
+    }
+    return result;
+}
+/** Memory-only proofs grant cached local attachment, never remote authorization. */
+export class SharedAdmissionCache {
+    revocations = new Map();
+    proofs = new Map();
+    record(url, headers, identity) {
+        // Invisible cookies/custom-fetch identity cannot be a credential proof.
+        if (!new Headers(headers).get("authorization") && identity.principalId !== ANONYMOUS_ACCOUNT_ID)
+            return;
+        if (this.proofs.size >= 64)
+            this.proofs.delete(this.proofs.keys().next().value);
+        this.proofs.set(sharedCredentialKey(url, headers), { ...identity });
+    }
+    generation(url, headers) {
+        return this.revocations.get(sharedCredentialKey(url, headers)) ?? 0;
+    }
+    remove(url, headers) {
+        const key = sharedCredentialKey(url, headers);
+        this.revocations.set(key, this.generation(url, headers) + 1);
+        this.proofs.delete(key);
+    }
+    async persistLocal(url, headers, generation, write, remove) {
+        if (this.generation(url, headers) !== generation)
+            return;
+        await write();
+        if (this.generation(url, headers) !== generation)
+            await remove();
+    }
+    async verify(url, headers, expected, probe, allowOffline = true) {
+        const generation = this.generation(url, headers);
+        let identity;
+        let online = true;
+        try {
+            identity = await probe();
+        }
+        catch (error) {
+            if (!(error instanceof Error) || error.code !== "LIX_TRANSPORT_NETWORK")
+                throw error;
+            const known = this.proofs.get(sharedCredentialKey(url, headers));
+            if (!allowOffline || !known || !expected || !sameAdmission(known, expected)) {
+                throw new HttpTransportError("LIX_IDENTITY_UNVERIFIED_OFFLINE", "Repository identity cannot be verified while offline", { cause: error });
+            }
+            identity = known;
+            online = false;
+        }
+        if (this.generation(url, headers) !== generation) {
+            throw new HttpTransportError("LIX_ADMISSION_AUTH_REJECTED", "Credentials were rejected while admission was in flight");
+        }
+        if (expected && !sameAdmission(identity, expected)) {
+            throw new HttpTransportError("LIX_SHARED_ENGINE_IDENTITY_MISMATCH", "Shared engine repository/account does not match this client");
+        }
+        if (online)
+            this.record(url, headers, identity);
+        return { identity, online };
+    }
+}

package/dist/worker/shared-engine.d.ts

@@ -0,0 +1,34 @@
+import type { LixBinding, SyncServerBindingOptions, TelemetryDispatch, TelemetryParentContext, OpenProgressDispatch } from "../binding-types.js";
+export type SharedEngineClient = {
+    server: SyncServerBindingOptions;
+    isDisconnected?(): boolean;
+    telemetry?: TelemetryDispatch;
+    parent?: TelemetryParentContext;
+    progress?: OpenProgressDispatch;
+    commitIdentity?(): void | Promise<void>;
+    rejectCredentials?(headers: [string, string][]): void | Promise<void>;
+    verifyIdentity(): Promise<{
+        authorityUrl: string;
+        accountId: string;
+        headers: [string, string][];
+        online?: boolean;
+    }>;
+};
+/** One physical owner; ports receive independent sessions, never the root. */
+export declare class SharedEngineOwner {
+    private readonly open;
+    private root;
+    private principalId;
+    private state;
+    get lifecycleState(): "closed" | "ready" | "closing" | "opening" | "migration-exclusive";
+    private readonly clients;
+    private queue;
+    constructor(open: (server: SyncServerBindingOptions, telemetry: TelemetryDispatch, client: SharedEngineClient) => Promise<LixBinding>);
+    private readonly backgroundTelemetry;
+    attach(client: SharedEngineClient): Promise<LixBinding>;
+    /** Serialize closed-storage conversion with root admission across all ports. */
+    convert(client: SharedEngineClient, conversion: (server: SyncServerBindingOptions) => Promise<void>, branchId?: string): Promise<void>;
+    deactivate(client: SharedEngineClient): void;
+    detach(client: SharedEngineClient): Promise<void>;
+    private transport;
+}