@zlink-systems/framework 0.10.0

package/dist/runtime/host/stateful-authority-route-runtime.js

@@ -0,0 +1,440 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkStatefulAuthorityRouteRuntime = void 0;
+const node_crypto_1 = require("node:crypto");
+const relocation_blob_1 = require("../locations/relocation-blob");
+const routing_id_1 = require("../routing-id");
+const service_authority_payload_codec_1 = require("../foundation/service-authority-payload-codec");
+const service_instance_activation_recovery_codec_1 = require("../foundation/service-instance-activation-recovery-codec");
+const service_relocation_runtime_1 = require("../foundation/service-relocation-runtime");
+const actors_1 = require("../actors");
+/**
+ * Reconciles durable Spot authority into the raw service runtime. The Location
+ * Store remains authoritative; this object only maintains fenced routing cache.
+ */
+class ZLinkStatefulAuthorityRouteRuntime {
+    options;
+    abortController = new AbortController();
+    appliedByMesh = new Map();
+    loop;
+    constructor(options) {
+        this.options = options;
+    }
+    async start(parentSignal) {
+        if (this.loop !== undefined)
+            return;
+        if (parentSignal?.aborted === true)
+            throw parentSignal.reason;
+        const onParentAbort = () => this.abortController.abort(parentSignal?.reason);
+        parentSignal?.addEventListener('abort', onParentAbort, { once: true });
+        try {
+            await this.reconcile(this.abortController.signal, true);
+            this.loop = this.run(this.abortController.signal).finally(() => {
+                parentSignal?.removeEventListener('abort', onParentAbort);
+            });
+        }
+        catch (error) {
+            parentSignal?.removeEventListener('abort', onParentAbort);
+            throw error;
+        }
+    }
+    async stop() {
+        this.abortController.abort();
+        await this.loop;
+        this.loop = undefined;
+        this.appliedByMesh.clear();
+    }
+    async reconcile(signal, requireComplete = false) {
+        const snapshot = await this.readCompleteSnapshot(signal);
+        if (snapshot === undefined) {
+            if (requireComplete) {
+                throw new Error('The initial authority recovery scan expired before a complete snapshot was read.');
+            }
+            return;
+        }
+        const current = snapshot.routes;
+        for (const actor of snapshot.actors) {
+            await this.options.recoverActor?.(actor, signal);
+        }
+        const sinks = [];
+        for (const [meshName, node] of this.options.meshNodes) {
+            const sink = asStatefulAuthorityRouteSink(node);
+            if (sink === undefined)
+                continue;
+            sinks.push({ meshName, sink });
+            const previous = this.appliedByMesh.get(meshName) ?? new Map();
+            const status = sink.status();
+            for (const pending of snapshot.pending) {
+                if (pending.targetMeshName === meshName
+                    && (0, routing_id_1.routingIdsEqual)(status.routingId, pending.targetNodeRid)
+                    && status.lifecycleGeneration === pending.targetNodeGeneration) {
+                    await this.recoverPendingInstanceActivation(sink, pending, signal);
+                }
+            }
+            for (const [key, route] of current) {
+                if (route.meshName !== meshName)
+                    continue;
+                const previousRoute = previous.get(key);
+                const expectedSpotRoute = previousRoute?.spotRoute ?? null;
+                const expectedInstanceRoute = previousRoute?.kind === 'instance_spot'
+                    ? previousRoute.instanceRoute
+                    : null;
+                sink.rememberSpotRoute(route.spotRoute, expectedSpotRoute);
+                if (route.kind === 'instance_spot') {
+                    const status = sink.status();
+                    if ((0, routing_id_1.routingIdsEqual)(status.routingId, route.instanceRoute.targetNodeRid)
+                        && status.lifecycleGeneration === route.instanceRoute.targetNodeGeneration) {
+                        if (route.activationRecovery !== undefined) {
+                            if (route.activationRecovery.replayCursor
+                                === route.activationRecovery.inboxSequence) {
+                                const released = await sink.completeRecoveredInstanceActivation({
+                                    targetSpotId: route.instanceRoute.targetSpotId,
+                                    stableType: route.stableType,
+                                    targetNodeRid: route.instanceRoute.targetNodeRid,
+                                    targetNodeGeneration: route.instanceRoute.targetNodeGeneration,
+                                    descriptorVersion: status.descriptorRevision.toString()
+                                }, route.instanceRoute, expectedInstanceRoute);
+                                if (released === undefined)
+                                    continue;
+                                const { activationRecovery: _, ...routeWithoutRecovery } = route;
+                                const completed = {
+                                    ...routeWithoutRecovery,
+                                    spotRoute: {
+                                        ...route.spotRoute,
+                                        spot: {
+                                            spotId: released.targetSpotId,
+                                            generation: released.objectGeneration
+                                        },
+                                        targetNodeRid: released.targetNodeRid,
+                                        targetNodeGeneration: released.targetNodeGeneration,
+                                        authorityOwnerGeneration: released.authorityOwnerGeneration,
+                                        ownerLeaseGeneration: released.leaseGeneration,
+                                        storeVersion: released.storeVersion
+                                    },
+                                    instanceRoute: released
+                                };
+                                current.set(key, completed);
+                                sink.rememberSpotRoute(completed.spotRoute, completed.spotRoute);
+                                sink.registerInstanceIntent(route.stableType, released, released);
+                                continue;
+                            }
+                            else {
+                                const recovered = await this.recoverInstanceActivation(sink, route, route.activationRecovery, expectedInstanceRoute, signal);
+                                if (!recovered) {
+                                    sink.forgetSpotRoute(route.spotRoute.spot, route.instanceRoute.authorityOwnerGeneration, route.instanceRoute.storeVersion);
+                                    continue;
+                                }
+                                sink.registerInstanceIntent(route.stableType, route.instanceRoute, route.instanceRoute);
+                                continue;
+                            }
+                        }
+                        sink.registerInstanceIntent(route.stableType, route.instanceRoute, expectedInstanceRoute);
+                    }
+                }
+            }
+        }
+        // Publish every successor before cleaning old entries. Conditional cleanup
+        // then cannot remove a route or intent installed for a newer generation.
+        for (const { meshName, sink } of sinks) {
+            const previous = this.appliedByMesh.get(meshName) ?? new Map();
+            const meshCurrent = new Map([...current].filter(([, route]) => route.meshName === meshName));
+            const changedSpotIds = new Set();
+            for (const [key, oldRoute] of previous) {
+                const next = meshCurrent.get(key);
+                if (oldRoute.meshName === meshName && !sameAppliedRoute(oldRoute, next)) {
+                    changedSpotIds.add(String(oldRoute.spotRoute.spot.spotId));
+                    sink.forgetSpotRoute(oldRoute.spotRoute.spot, oldRoute.spotRoute.authorityOwnerGeneration, oldRoute.instanceRoute.storeVersion);
+                    if (oldRoute.kind === 'instance_spot' && oldRoute.meshName === meshName) {
+                        sink.forgetInstanceIntent(oldRoute.instanceRoute.targetSpotId, oldRoute.instanceRoute.objectGeneration, oldRoute.instanceRoute.authorityOwnerGeneration, oldRoute.instanceRoute.storeVersion);
+                    }
+                }
+            }
+            for (const [key, nextRoute] of meshCurrent) {
+                const previousRoute = previous.get(key);
+                if (previousRoute === undefined || !sameAppliedRoute(previousRoute, nextRoute)) {
+                    changedSpotIds.add(String(nextRoute.spotRoute.spot.spotId));
+                }
+            }
+            this.appliedByMesh.set(meshName, meshCurrent);
+            for (const spotId of changedSpotIds) {
+                this.options.onSpotRouteChanged?.(spotId);
+            }
+        }
+    }
+    async recoverInstanceActivation(sink, route, recovery, expectedCurrentRoute, signal) {
+        const envelope = await this.readRecoveryEnvelope(recovery, signal);
+        const status = sink.status();
+        if (envelope.targetMeshName !== route.meshName
+            || envelope.target.stableType !== route.stableType
+            || envelope.target.targetSpotId !== route.instanceRoute.targetSpotId
+            || envelope.target.targetNodeRid !== route.instanceRoute.targetNodeRid
+            || envelope.target.targetNodeGeneration !== route.instanceRoute.targetNodeGeneration
+            || envelope.target.descriptorVersion !== status.descriptorRevision.toString()) {
+            this.options.reportError(new Error('Instance activation recovery envelope does not match Ready authority.'));
+            return false;
+        }
+        return (await sink.recoverInstanceActivation(envelope, route.instanceRoute, expectedCurrentRoute)) !== false;
+    }
+    async recoverPendingInstanceActivation(sink, recovery, signal) {
+        const envelope = await this.readRecoveryEnvelope({
+            reference: recovery.pending.requestReference,
+            sha256: recovery.pending.requestSha256,
+            encodedSize: Number(recovery.pending.requestEncodedSize),
+            inboxSequence: 1n,
+            replayCursor: 0n
+        }, signal);
+        const status = sink.status();
+        if (envelope.targetMeshName !== recovery.targetMeshName
+            || envelope.target.stableType !== recovery.stableType
+            || envelope.target.targetSpotId !== recovery.spotId
+            || envelope.target.targetNodeRid !== recovery.targetNodeRid
+            || envelope.target.targetNodeGeneration !== recovery.targetNodeGeneration
+            || envelope.target.descriptorVersion !== status.descriptorRevision.toString()) {
+            const creationStore = this.options.creationStore;
+            if (creationStore === undefined) {
+                this.options.reportError(new Error('Pending Instance activation mismatch requires an object creation store.'));
+                return;
+            }
+            const aborted = await creationStore.abort({
+                key: { kind: 'instance_spot', globalId: recovery.spotId },
+                reservationId: recovery.pending.reservationId,
+                expectedStoreVersion: recovery.pending.storeVersion,
+                target: {
+                    meshName: recovery.pending.meshName,
+                    nodeRid: recovery.pending.nodeRid,
+                    nodeLifecycleGeneration: recovery.pending.nodeGeneration,
+                    owner: {
+                        ownerId: recovery.pending.ownerId,
+                        leaseGeneration: recovery.pending.ownerLeaseGeneration
+                    }
+                }
+            }, signal);
+            if (aborted.kind === 'aborted' || aborted.kind === 'alreadyAborted') {
+                try {
+                    await this.options.relocationStore?.delete((0, relocation_blob_1.relocationBlobReference)(recovery.pending.requestReference));
+                }
+                catch {
+                    // The authority no longer publishes this root. Retention owns a
+                    // failed best-effort orphan cleanup.
+                }
+            }
+            return;
+        }
+        if ((await sink.recoverPendingInstanceActivation(envelope, recovery.pending, null)) === false)
+            return;
+    }
+    async readRecoveryEnvelope(recovery, signal) {
+        const relocationStore = this.options.relocationStore;
+        if (relocationStore === undefined) {
+            throw new Error('Instance activation recovery requires a Relocation Store.');
+        }
+        const result = await relocationStore.read((0, relocation_blob_1.relocationBlobReference)(recovery.reference), signal);
+        if (result.kind !== 'found') {
+            throw new Error(`Instance activation recovery payload '${recovery.reference}' is missing.`);
+        }
+        const payload = Buffer.from(result.bytes);
+        const sha256 = (0, node_crypto_1.createHash)('sha256').update(payload).digest();
+        if (payload.byteLength !== recovery.encodedSize
+            || !sha256.equals(Buffer.from(recovery.sha256))) {
+            throw new Error(`Instance activation recovery payload '${recovery.reference}' failed integrity validation.`);
+        }
+        return (0, service_instance_activation_recovery_codec_1.decodeInstanceActivationRecoveryEnvelope)(payload);
+    }
+    async run(signal) {
+        while (!signal.aborted) {
+            try {
+                await wait(this.options.pollingIntervalMs, signal);
+                await this.reconcile(signal);
+            }
+            catch (error) {
+                if (aborted(signal))
+                    return;
+                this.options.reportError(error);
+            }
+        }
+    }
+    async readCompleteSnapshot(signal) {
+        const candidates = new Map();
+        let cursor;
+        do {
+            const page = await this.options.store.listAuthorities('', cursor, this.options.pageSize, signal);
+            if (page.kind === 'scanExpired')
+                return undefined;
+            for (const entry of page.items) {
+                // listAuthorities returns the key and the snapshot observed by the
+                // same bounded scan. Re-reading every key here adds one store round
+                // trip per authority and can observe a different version from the
+                // scan that selected the key.
+                candidates.set(entry.key.value, entry);
+            }
+            cursor = page.nextCursor;
+        } while (cursor !== undefined);
+        const result = new Map();
+        const pending = [];
+        const actors = [];
+        const relocationCodec = new service_relocation_runtime_1.ServiceRelocationAuthorityPayloadCodec();
+        for (const { key, snapshot: scanned } of candidates.values()) {
+            let current = scanned;
+            if (authorityNeedsExactRead(scanned, relocationCodec)) {
+                current = await this.options.store.readAuthority(key, signal);
+                if (current.kind !== 'snapshot')
+                    continue;
+            }
+            const route = authorityRoute(current);
+            if (route !== undefined)
+                result.set(authorityRouteKey(route), route);
+            if (current.allocation.state === 'active'
+                && current.allocation.objectKind === 'actor'
+                && (0, actors_1.decodeActorAuthorityIdentity)((0, service_relocation_runtime_1.serviceRelocationAuthorityApplicationPayload)(current.payload), current.objectGeneration) !== undefined) {
+                actors.push(current);
+            }
+            const pendingRecovery = pendingInstanceActivation(current);
+            if (pendingRecovery !== undefined)
+                pending.push(pendingRecovery);
+        }
+        return { routes: result, pending, actors };
+    }
+}
+exports.ZLinkStatefulAuthorityRouteRuntime = ZLinkStatefulAuthorityRouteRuntime;
+function authorityNeedsExactRead(snapshot, relocationCodec) {
+    if (pendingInstanceActivation(snapshot) !== undefined)
+        return true;
+    if (relocationCodec.read(snapshot.payload) !== undefined)
+        return true;
+    if ((0, service_authority_payload_codec_1.decodeServiceReadySpotAuthority)((0, service_relocation_runtime_1.serviceRelocationAuthorityApplicationPayload)(snapshot.payload))?.activationRecovery !== undefined) {
+        return true;
+    }
+    return snapshot.allocation.state === 'active'
+        && snapshot.allocation.objectKind === 'actor'
+        && (0, actors_1.decodeActorAuthorityIdentity)(snapshot.payload, snapshot.objectGeneration) !== undefined;
+}
+function pendingInstanceActivation(snapshot) {
+    const allocation = snapshot.allocation;
+    const projection = snapshot.pendingCreation;
+    const decoded = (0, service_authority_payload_codec_1.decodeServiceInstanceAuthorityPayload)(snapshot.payload);
+    if (allocation.state !== 'reserved'
+        || allocation.objectKind !== 'instance_spot'
+        || projection === undefined
+        || decoded?.state !== 'coldActivating'
+        || decoded.stableType !== allocation.stableType
+        || decoded.ownerId !== snapshot.ownerId
+        || decoded.ownerLeaseGeneration !== snapshot.ownerLeaseGeneration
+        || decoded.ownerMeshName !== allocation.descriptor.meshName
+        || decoded.ownerNodeGeneration !== allocation.descriptorLifecycleGeneration
+        || !(0, routing_id_1.routingIdsEqual)(decoded.ownerNodeRid, allocation.descriptor.rid)) {
+        return undefined;
+    }
+    return {
+        targetMeshName: allocation.descriptor.meshName,
+        targetNodeRid: String(allocation.descriptor.rid),
+        targetNodeGeneration: allocation.descriptorLifecycleGeneration,
+        stableType: allocation.stableType,
+        spotId: decoded.spotId,
+        pending: {
+            reservationId: projection.reservationId,
+            storeVersion: snapshot.storeVersion.value,
+            objectGeneration: snapshot.objectGeneration,
+            authorityOwnerGeneration: snapshot.authorityOwnerGeneration,
+            ownerId: snapshot.ownerId,
+            ownerLeaseGeneration: snapshot.ownerLeaseGeneration,
+            meshName: allocation.descriptor.meshName,
+            nodeRid: String(allocation.descriptor.rid),
+            nodeGeneration: allocation.descriptorLifecycleGeneration,
+            requestReference: projection.requestContentReference,
+            requestSha256: projection.requestSha256,
+            requestEncodedSize: projection.requestEncodedSize
+        }
+    };
+}
+function authorityRoute(snapshot) {
+    const allocation = snapshot.allocation;
+    const decoded = (0, service_authority_payload_codec_1.decodeServiceReadySpotAuthority)((0, service_relocation_runtime_1.serviceRelocationAuthorityApplicationPayload)(snapshot.payload));
+    if (allocation.state !== 'active'
+        || allocation.objectKind === 'actor'
+        || allocation.descriptor.meshName.length === 0
+        || decoded === undefined
+        || decoded.kind !== allocation.objectKind
+        || decoded.stableType !== allocation.stableType
+        || decoded.ownerId !== snapshot.ownerId
+        || decoded.ownerLeaseGeneration !== snapshot.ownerLeaseGeneration
+        || decoded.ownerMeshName !== allocation.descriptor.meshName
+        || decoded.ownerNodeGeneration !== allocation.descriptorLifecycleGeneration
+        || !(0, routing_id_1.routingIdsEqual)(decoded.ownerNodeRid, allocation.descriptor.rid)) {
+        return undefined;
+    }
+    const spotId = decoded.spotId;
+    const targetNodeRid = String(allocation.descriptor.rid);
+    const spotRoute = {
+        spot: { spotId, generation: snapshot.objectGeneration },
+        targetNodeRid,
+        targetNodeGeneration: allocation.descriptorLifecycleGeneration,
+        authorityOwnerGeneration: snapshot.authorityOwnerGeneration,
+        ownerLeaseGeneration: snapshot.ownerLeaseGeneration,
+        storeVersion: snapshot.storeVersion.value
+    };
+    return {
+        kind: allocation.objectKind,
+        stableType: allocation.stableType,
+        meshName: allocation.descriptor.meshName,
+        spotRoute,
+        instanceRoute: {
+            targetNodeRid,
+            targetNodeGeneration: allocation.descriptorLifecycleGeneration,
+            targetSpotId: spotId,
+            objectGeneration: snapshot.objectGeneration,
+            ownerId: snapshot.ownerId,
+            authorityOwnerGeneration: snapshot.authorityOwnerGeneration,
+            leaseGeneration: snapshot.ownerLeaseGeneration,
+            storeVersion: snapshot.storeVersion.value
+        },
+        ...(decoded.activationRecovery === undefined
+            ? {}
+            : { activationRecovery: decoded.activationRecovery })
+    };
+}
+function authorityRouteKey(route) {
+    return `${route.meshName}\0${route.spotRoute.spot.spotId}\0`
+        + `${route.spotRoute.spot.generation}`;
+}
+function sameAppliedRoute(left, right) {
+    if (right === undefined)
+        return false;
+    return left.kind === right.kind
+        && left.stableType === right.stableType
+        && left.meshName === right.meshName
+        && left.instanceRoute.targetNodeRid === right.instanceRoute.targetNodeRid
+        && left.instanceRoute.targetNodeGeneration === right.instanceRoute.targetNodeGeneration
+        && left.instanceRoute.authorityOwnerGeneration === right.instanceRoute.authorityOwnerGeneration
+        && left.instanceRoute.storeVersion === right.instanceRoute.storeVersion;
+}
+function asStatefulAuthorityRouteSink(node) {
+    const candidate = node;
+    return typeof candidate.rememberSpotRoute === 'function'
+        && typeof candidate.forgetSpotRoute === 'function'
+        && typeof candidate.registerInstanceIntent === 'function'
+        && typeof candidate.forgetInstanceIntent === 'function'
+        && typeof candidate.recoverInstanceActivation === 'function'
+        && typeof candidate.completeRecoveredInstanceActivation === 'function'
+        ? candidate
+        : undefined;
+}
+function aborted(signal) {
+    return signal.aborted;
+}
+function wait(timeoutMs, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, timeoutMs);
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}

package/dist/runtime/host/user-spot-creation-coordinator.d.ts

@@ -0,0 +1,69 @@
+import type { RoutingId, SpotRef, ZLinkSpotCreateResult } from '../../contracts';
+import type { ZLinkAuthoritySnapshot, ZLinkLocationOwnerToken } from '../locations/internal-location-contracts';
+import type { ZLinkAuthorityStore, ZLinkObjectCreationStore } from '../locations/internal-store-contracts';
+import type { ZLinkLocalSpotCreateResult } from '../spots/spot-manager-internal-contracts';
+import type { ServiceUserSpotOperationResult } from '../foundation/service-stateful-runtime';
+import type { ServiceUserSpotCloseRecord, ServiceUserSpotCreateRecord, ServiceDirectSpotRouteFence } from '../foundation/service-stateful-wire-codec';
+export interface ZLinkUserSpotCreationCoordinatorOptions {
+    readonly store: ZLinkObjectCreationStore & ZLinkAuthorityStore;
+    readonly target: (request: Pick<ZLinkUserSpotCreationRequest, 'meshName' | 'stableType'>, signal?: AbortSignal, excludedNodeRids?: ReadonlySet<string>) => Promise<{
+        readonly meshName: string;
+        readonly nodeRid: RoutingId;
+        readonly nodeGeneration: bigint;
+        readonly owner: ZLinkLocationOwnerToken;
+        readonly isLocal: boolean;
+    } | undefined>;
+    readonly pollIntervalMs?: number;
+    readonly cleanupTimeoutMs?: number;
+    readonly remoteCreate?: (meshName: string, targetNodeRid: string, request: Omit<ServiceUserSpotCreateRecord, 'kind' | 'correlation' | 'operation'>, timeoutMs: number) => Promise<ServiceUserSpotOperationResult>;
+    readonly decodeRemoteReply?: (payload: Uint8Array) => unknown;
+    /** Records the committed Ready fence on the owning MeshNode before publication. */
+    readonly publishReadyRoute?: (meshName: string, route: ServiceDirectSpotRouteFence) => void;
+    /** Removes the committed Ready fence after the authority is deleted. */
+    readonly forgetReadyRoute?: (meshName: string, route: ServiceDirectSpotRouteFence) => void;
+}
+export interface ZLinkUserSpotCreationRequest {
+    readonly meshName?: string;
+    readonly spotId: RoutingId;
+    readonly stableType: string;
+    readonly requestPayload: Uint8Array;
+    readonly timeoutMs: number;
+    readonly signal?: AbortSignal;
+    readonly generatedIdentity?: boolean;
+}
+export interface ZLinkUserSpotCreationResult {
+    readonly result: ZLinkSpotCreateResult;
+    readonly spot: SpotRef;
+}
+export interface ZLinkUserSpotCloseTarget {
+    readonly spot: SpotRef;
+    readonly snapshot: ZLinkAuthoritySnapshot;
+}
+/**
+ * Makes generic Location Store reservation the only visibility barrier for a
+ * User Spot. Only the reservation winner invokes application lifecycle code.
+ */
+export declare class ZLinkUserSpotCreationCoordinator {
+    private readonly options;
+    private readonly localCreations;
+    private readonly remoteCreations;
+    constructor(options: ZLinkUserSpotCreationCoordinatorOptions);
+    getOrCreate(request: ZLinkUserSpotCreationRequest, materialize: (target: {
+        readonly meshName: string;
+        readonly nodeRid: RoutingId;
+        readonly isLocal: boolean;
+    }, authority: ZLinkAuthoritySnapshot, signal: AbortSignal) => Promise<ZLinkLocalSpotCreateResult>, discard?: (signal?: AbortSignal) => Promise<void>): Promise<ZLinkUserSpotCreationResult>;
+    close(spot: SpotRef, closeOwner: (current: SpotRef, snapshot: ZLinkAuthoritySnapshot) => Promise<boolean>, signal?: AbortSignal, ownerPresent?: (current: SpotRef) => boolean, ownerCanClose?: (current: SpotRef) => boolean): Promise<boolean>;
+    resolveCloseTarget(spot: SpotRef, signal?: AbortSignal): Promise<ZLinkUserSpotCloseTarget | undefined>;
+    handleRemoteCreate(record: ServiceUserSpotCreateRecord, materialize: (requestPayload: Uint8Array, authority: ZLinkAuthoritySnapshot, signal: AbortSignal) => Promise<ZLinkLocalSpotCreateResult>, discard?: (signal?: AbortSignal) => Promise<void>, signal?: AbortSignal): Promise<ZLinkUserSpotCreationResult>;
+    private handleLocalCreate;
+    private materializeRemoteCreate;
+    handleRemoteClose(record: ServiceUserSpotCloseRecord, closeOwner: (spot: SpotRef, signal?: AbortSignal) => Promise<boolean>, signal?: AbortSignal): Promise<boolean>;
+    forgetReadyRoute(spotId: RoutingId, snapshot: ZLinkAuthoritySnapshot): void;
+    private beginClosing;
+    private restoreReady;
+    private awaitReady;
+    private remoteCreate;
+}
+export declare function encodeLocationCreationContent(payload: Uint8Array, checksum?: number): string;
+export declare function decodeLocationCreationContent(reference: string, expectedSha256?: Uint8Array, expectedEncodedSize?: bigint): Buffer;