@zlink-systems/framework 0.10.0

package/dist/runtime/host/instance-activation-authority.d.ts

@@ -0,0 +1,33 @@
+import type { ZLinkLocationOwnerToken, ZLinkRelocationStore } from '../../contracts/Locations';
+import type { ZLinkAuthorityStore, ZLinkObjectCreationStore } from '../locations/internal-store-contracts';
+import type { ServiceAsyncInstanceActivationAuthority, ServiceInstanceActivationReservation, ServiceInstanceAuthorityRead, ServiceInstanceAuthorityReserve, ServicePendingInstanceActivation } from '../foundation/service-stateful-runtime';
+import type { ServiceSpotState } from '../foundation/service-stateful-registry';
+import type { ServiceInstanceActivationTarget, ServiceInstanceRouteFence } from '../foundation/service-stateful-wire-codec';
+import { type ServiceInstanceActivationRecoveryEnvelope } from '../foundation/service-instance-activation-recovery-codec';
+export interface ZLinkInstanceActivationAuthorityOptions {
+    readonly store: ZLinkObjectCreationStore & ZLinkAuthorityStore;
+    readonly relocationStore?: ZLinkRelocationStore;
+    readonly meshName: string;
+    readonly owner: () => ZLinkLocationOwnerToken | undefined;
+    readonly metrics?: import('../diagnostics').ZLinkRuntimeMetrics;
+    readonly onReady?: (target: ServiceInstanceActivationTarget, route: ServiceInstanceRouteFence) => void;
+}
+export declare class ZLinkInstanceActivationAuthority implements ServiceAsyncInstanceActivationAuthority {
+    private readonly options;
+    private readonly pending;
+    constructor(options: ZLinkInstanceActivationAuthorityOptions);
+    read(target: ServiceInstanceActivationTarget): Promise<ServiceInstanceAuthorityRead>;
+    reserve(activation: Omit<ServiceInstanceActivationRecoveryEnvelope, 'targetMeshName'>): Promise<ServiceInstanceAuthorityReserve>;
+    resume(target: ServiceInstanceActivationTarget, pending: ServicePendingInstanceActivation): Promise<ServiceInstanceActivationReservation>;
+    commit(target: ServiceInstanceActivationTarget, reservation: ServiceInstanceActivationReservation, spot: ServiceSpotState): Promise<{
+        readonly kind: 'committed' | 'lost';
+        readonly route: ServiceInstanceRouteFence;
+    }>;
+    complete(target: ServiceInstanceActivationTarget, route: ServiceInstanceRouteFence): Promise<ServiceInstanceRouteFence>;
+    abort(target: ServiceInstanceActivationTarget, reservation: ServiceInstanceActivationReservation): Promise<void>;
+    private requireOwner;
+    private deleteOrphan;
+    private awaitConcurrentActivation;
+    private awaitClosingRelease;
+    private requirePending;
+}

package/dist/runtime/host/instance-activation-authority.js

@@ -0,0 +1,496 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkInstanceActivationAuthority = void 0;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const node_crypto_1 = require("node:crypto");
+const contracts_1 = require("../../contracts");
+const service_authority_payload_codec_1 = require("../foundation/service-authority-payload-codec");
+const routing_id_1 = require("../routing-id");
+const authority_key_codec_1 = require("../locations/authority-key-codec");
+const service_relocation_runtime_1 = require("../foundation/service-relocation-runtime");
+const relocation_blob_1 = require("../locations/relocation-blob");
+const service_instance_activation_recovery_codec_1 = require("../foundation/service-instance-activation-recovery-codec");
+const CREATION_REQUEST_RETENTION_MS = 24 * 60 * 60 * 1_000;
+const MAX_CREATION_REQUEST_BYTES = 1024 * 1024;
+const ACTIVATION_JOIN_POLL_INTERVAL_MS = 10;
+class ZLinkInstanceActivationAuthority {
+    options;
+    pending = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    async read(target) {
+        const current = await this.options.store.readAuthority(authorityKey(target.targetSpotId));
+        return current.kind === 'snapshot'
+            ? readyRead(current, target)
+            : { kind: 'missing' };
+    }
+    async reserve(activation) {
+        const target = activation.target;
+        const owner = this.requireOwner();
+        const requestBytes = (0, service_instance_activation_recovery_codec_1.encodeInstanceActivationRecoveryEnvelope)({
+            ...activation,
+            targetMeshName: this.options.meshName
+        });
+        if (requestBytes.byteLength > MAX_CREATION_REQUEST_BYTES) {
+            throw new RangeError('Encoded Instance activation request exceeds 1 MiB.');
+        }
+        const relocationStore = this.options.relocationStore;
+        if (relocationStore === undefined) {
+            throw new Error('Instance activation requires a Relocation Store.');
+        }
+        const requestHash = (0, node_crypto_1.createHash)('sha256').update(requestBytes).digest();
+        const stored = await (0, relocation_blob_1.putNewRelocationBlob)(relocationStore, requestBytes, CREATION_REQUEST_RETENTION_MS);
+        const storedRead = await relocationStore.read(stored.reference);
+        if (stored.reference.value.length === 0
+            || stored.expiresAt.getTime() <= stored.storeNow.getTime()
+            || storedRead.kind !== 'found'
+            || (0, service_relocation_runtime_1.crc32c)(storedRead.bytes) !== (0, service_relocation_runtime_1.crc32c)(requestBytes)
+            || !Buffer.from(storedRead.bytes).equals(requestBytes)) {
+            await this.deleteOrphan(stored.reference);
+            throw new Error('Relocation Store returned an invalid creation request receipt.');
+        }
+        let reserved;
+        try {
+            for (;;) {
+                reserved = await this.options.store.reserve({
+                    key: { kind: 'instance_spot', globalId: target.targetSpotId },
+                    intent: {
+                        stableType: target.stableType,
+                        requestContentReference: stored.reference.value,
+                        requestSha256: requestHash,
+                        requestEncodedSize: BigInt(requestBytes.byteLength)
+                    },
+                    target: {
+                        meshName: this.options.meshName,
+                        nodeRid: target.targetNodeRid,
+                        nodeLifecycleGeneration: target.targetNodeGeneration,
+                        owner
+                    },
+                    creatingPayload: (0, service_authority_payload_codec_1.encodeServiceInstanceAuthorityPayload)({
+                        state: 'coldActivating',
+                        stableType: target.stableType,
+                        spotId: target.targetSpotId,
+                        ownerId: owner.ownerId,
+                        ownerLeaseGeneration: owner.leaseGeneration,
+                        ownerMeshName: this.options.meshName,
+                        ownerNodeRid: target.targetNodeRid,
+                        ownerNodeGeneration: target.targetNodeGeneration
+                    }),
+                    capacity: {
+                        actors: 0,
+                        spots: 1,
+                        spotType: {
+                            objectKind: 'instance_spot',
+                            stableType: target.stableType,
+                            count: 1
+                        }
+                    }
+                });
+                if (reserved.kind === 'conflict' || reserved.kind === 'alreadyExists') {
+                    const existingState = reserved.current.kind === 'snapshot'
+                        ? (0, service_authority_payload_codec_1.decodeServiceInstanceAuthorityPayload)(reserved.current.payload)?.state
+                        : undefined;
+                    if (existingState === 'closing') {
+                        await this.awaitClosingRelease(target, activation.deadlineUnixMs);
+                        continue;
+                    }
+                }
+                if (reserved.kind !== 'alreadyExists')
+                    break;
+                this.options.metrics?.recordInstanceSpotClaimConflict(this.options.meshName, target.stableType, 'already_exists');
+                await this.deleteOrphan(stored.reference);
+                return readyExisting(reserved.current, target);
+            }
+        }
+        catch (error) {
+            await this.deleteOrphan(stored.reference);
+            throw error;
+        }
+        if (reserved.kind === 'conflict'
+            && reserved.current.kind === 'snapshot'
+            && reserved.current.allocation.objectKind === 'instance_spot'
+            && reserved.current.allocation.stableType === target.stableType
+            && reserved.current.allocation.state === 'reserved') {
+            this.options.metrics?.recordInstanceSpotClaimConflict(this.options.meshName, target.stableType, 'activation_in_progress');
+            await this.deleteOrphan(stored.reference);
+            return await this.awaitConcurrentActivation(target, activation.deadlineUnixMs);
+        }
+        if (reserved.kind !== 'reserved') {
+            this.options.metrics?.recordInstanceSpotClaimConflict(this.options.meshName, target.stableType, reserved.kind);
+            await this.deleteOrphan(stored.reference);
+            if (reserved.kind === 'placementCapacityExhausted') {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.PlacementCapacityExhausted, `Instance Spot placement capacity is exhausted for '${String(target.targetSpotId)}'.`);
+            }
+            throw new Error(`Instance activation reservation failed: ${reserved.kind}.`);
+        }
+        const reservation = {
+            attempt: reserved.creating.objectGeneration,
+            authorityOwnerGeneration: reserved.creating.authorityOwnerGeneration,
+            token: reserved.reservationId
+        };
+        this.pending.set(reservation.token, {
+            reservationId: reserved.reservationId,
+            creating: reserved.creating,
+            owner,
+            requestReference: stored.reference,
+            requestSha256: requestHash,
+            requestEncodedSize: requestBytes.byteLength
+        });
+        return { kind: 'reserved', reservation };
+    }
+    async resume(target, pending) {
+        const current = await this.options.store.readAuthority(authorityKey(target.targetSpotId));
+        const projection = current.kind === 'snapshot' ? current.pendingCreation : undefined;
+        if (current.kind !== 'snapshot'
+            || current.allocation.state !== 'reserved'
+            || current.allocation.objectKind !== 'instance_spot'
+            || current.allocation.stableType !== target.stableType
+            || current.storeVersion.value !== pending.storeVersion
+            || current.objectGeneration !== pending.objectGeneration
+            || current.authorityOwnerGeneration !== pending.authorityOwnerGeneration
+            || current.ownerId !== pending.ownerId
+            || current.ownerLeaseGeneration !== pending.ownerLeaseGeneration
+            || current.allocation.descriptor.meshName !== pending.meshName
+            || !(0, routing_id_1.routingIdsEqual)(current.allocation.descriptor.rid, pending.nodeRid)
+            || current.allocation.descriptorLifecycleGeneration !== pending.nodeGeneration
+            || projection?.reservationId !== pending.reservationId
+            || projection.requestContentReference !== pending.requestReference
+            || projection.requestEncodedSize !== pending.requestEncodedSize
+            || !Buffer.from(projection.requestSha256).equals(Buffer.from(pending.requestSha256))) {
+            throw new Error('Pending Instance activation recovery fence is stale.');
+        }
+        const reservation = {
+            attempt: current.objectGeneration,
+            authorityOwnerGeneration: current.authorityOwnerGeneration,
+            token: projection.reservationId
+        };
+        this.pending.set(reservation.token, {
+            reservationId: projection.reservationId,
+            creating: current,
+            owner: {
+                ownerId: current.ownerId,
+                leaseGeneration: current.ownerLeaseGeneration
+            },
+            requestReference: (0, relocation_blob_1.relocationBlobReference)(projection.requestContentReference),
+            requestSha256: Buffer.from(projection.requestSha256),
+            requestEncodedSize: Number(projection.requestEncodedSize)
+        });
+        return reservation;
+    }
+    async commit(target, reservation, spot) {
+        const pending = this.requirePending(reservation);
+        requireCommitIdentity(target, reservation, pending.creating, spot, this.options.meshName);
+        let result;
+        try {
+            result = await this.options.store.commit({
+                key: { kind: 'instance_spot', globalId: target.targetSpotId },
+                reservationId: pending.reservationId,
+                expectedStoreVersion: pending.creating.storeVersion.value,
+                target: {
+                    meshName: this.options.meshName,
+                    nodeRid: target.targetNodeRid,
+                    nodeLifecycleGeneration: target.targetNodeGeneration,
+                    owner: pending.owner
+                },
+                readyPayload: (0, service_authority_payload_codec_1.encodeServiceInstanceAuthorityPayload)({
+                    state: 'ready',
+                    stableType: spot.stableType,
+                    spotId: spot.ref.spotId,
+                    ownerId: pending.owner.ownerId,
+                    ownerLeaseGeneration: pending.owner.leaseGeneration,
+                    ownerMeshName: this.options.meshName,
+                    ownerNodeRid: target.targetNodeRid,
+                    ownerNodeGeneration: target.targetNodeGeneration,
+                    activationRecovery: {
+                        reference: pending.requestReference.value,
+                        sha256: pending.requestSha256,
+                        encodedSize: pending.requestEncodedSize,
+                        inboxSequence: 1n,
+                        replayCursor: 0n
+                    }
+                })
+            });
+        }
+        catch (error) {
+            if (error instanceof contracts_1.ZLinkFrameworkException)
+                throw error;
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestFailed, 'Instance Spot Ready commit Store operation failed.', false, error);
+        }
+        if (result.kind === 'committed' || result.kind === 'alreadyCommitted') {
+            this.pending.delete(reservation.token);
+            const route = routeFromSnapshot(result.ready);
+            this.options.onReady?.(target, route);
+            return { kind: 'committed', route };
+        }
+        const current = await this.options.store.readAuthority(authorityKey(target.targetSpotId));
+        if (current.kind === 'snapshot') {
+            const ready = readyRead(current, target);
+            if (ready.kind === 'ready') {
+                this.pending.delete(reservation.token);
+                return { kind: 'lost', route: ready.route };
+            }
+        }
+        throw new Error(`Instance activation commit failed: ${result.kind}.`);
+    }
+    async complete(target, route) {
+        const key = authorityKey(target.targetSpotId);
+        const current = await this.options.store.readAuthority(key);
+        if (current.kind !== 'snapshot') {
+            throw new Error('Instance activation authority disappeared before inbox release.');
+        }
+        const decoded = (0, service_authority_payload_codec_1.decodeServiceReadySpotAuthority)(current.payload);
+        if (decoded?.kind !== 'instance_spot'
+            || decoded.spotId !== target.targetSpotId
+            || decoded.stableType !== target.stableType
+            || current.allocation.state !== 'active'
+            || current.objectGeneration !== route.objectGeneration
+            || current.authorityOwnerGeneration !== route.authorityOwnerGeneration
+            || current.ownerId !== route.ownerId
+            || current.ownerLeaseGeneration !== route.leaseGeneration
+            || current.allocation.descriptorLifecycleGeneration !== route.targetNodeGeneration
+            || !(0, routing_id_1.routingIdsEqual)(current.allocation.descriptor.rid, route.targetNodeRid)) {
+            throw new Error('Instance activation authority changed before inbox release.');
+        }
+        const recovery = decoded.activationRecovery;
+        if (recovery === undefined)
+            return routeFromSnapshot(current);
+        let completed = current;
+        if (recovery.replayCursor < recovery.inboxSequence) {
+            const cursorStored = await this.options.store.compareExchangeAuthority(key, current.storeVersion, {
+                kind: 'put',
+                generationTransition: 'preserve',
+                payload: (0, service_authority_payload_codec_1.encodeServiceInstanceAuthorityPayload)({
+                    state: 'ready',
+                    stableType: decoded.stableType,
+                    spotId: decoded.spotId,
+                    ownerId: decoded.ownerId,
+                    ownerLeaseGeneration: decoded.ownerLeaseGeneration,
+                    ownerMeshName: decoded.ownerMeshName,
+                    ownerNodeRid: decoded.ownerNodeRid,
+                    ownerNodeGeneration: decoded.ownerNodeGeneration,
+                    activationRecovery: {
+                        ...recovery,
+                        replayCursor: recovery.inboxSequence
+                    }
+                })
+            });
+            if (cursorStored.kind !== 'stored') {
+                throw new Error(`Instance activation terminal completion record failed: ${cursorStored.kind}.`);
+            }
+            const { kind: _, ...snapshot } = cursorStored;
+            completed = { kind: 'snapshot', ...snapshot };
+        }
+        const completedPayload = (0, service_authority_payload_codec_1.decodeServiceReadySpotAuthority)(completed.payload);
+        const completedRecovery = completedPayload?.activationRecovery;
+        if (completedPayload?.kind !== 'instance_spot'
+            || completedRecovery === undefined
+            || completedRecovery.replayCursor !== completedRecovery.inboxSequence) {
+            throw new Error('Instance activation terminal completion was not durably recorded.');
+        }
+        const stored = await this.options.store.compareExchangeAuthority(key, completed.storeVersion, {
+            kind: 'put',
+            generationTransition: 'preserve',
+            payload: (0, service_authority_payload_codec_1.encodeServiceInstanceAuthorityPayload)({
+                state: 'ready',
+                stableType: completedPayload.stableType,
+                spotId: completedPayload.spotId,
+                ownerId: completedPayload.ownerId,
+                ownerLeaseGeneration: completedPayload.ownerLeaseGeneration,
+                ownerMeshName: completedPayload.ownerMeshName,
+                ownerNodeRid: completedPayload.ownerNodeRid,
+                ownerNodeGeneration: completedPayload.ownerNodeGeneration
+            })
+        });
+        if (stored.kind !== 'stored') {
+            throw new Error(`Instance activation inbox release failed: ${stored.kind}.`);
+        }
+        await this.deleteOrphan((0, relocation_blob_1.relocationBlobReference)(recovery.reference));
+        const { kind: _, ...snapshot } = stored;
+        return routeFromSnapshot({ kind: 'snapshot', ...snapshot });
+    }
+    async abort(target, reservation) {
+        const pending = this.pending.get(reservation.token);
+        if (pending === undefined)
+            return;
+        const result = await this.options.store.abort({
+            key: { kind: 'instance_spot', globalId: target.targetSpotId },
+            reservationId: pending.reservationId,
+            expectedStoreVersion: pending.creating.storeVersion.value,
+            target: {
+                meshName: this.options.meshName,
+                nodeRid: target.targetNodeRid,
+                nodeLifecycleGeneration: target.targetNodeGeneration,
+                owner: pending.owner
+            }
+        });
+        if (result.kind === 'aborted' || result.kind === 'alreadyAborted') {
+            this.pending.delete(reservation.token);
+            await this.deleteOrphan(pending.requestReference);
+        }
+        else {
+            throw new Error(`Instance activation abort failed: ${result.kind}.`);
+        }
+    }
+    requireOwner() {
+        const owner = this.options.owner();
+        if (owner === undefined)
+            throw new Error('Location owner lease is not ready.');
+        return owner;
+    }
+    async deleteOrphan(reference) {
+        try {
+            await this.options.relocationStore?.delete(reference);
+        }
+        catch {
+            // No authority publishes this root. Retention owns cleanup when
+            // best-effort deletion fails.
+        }
+    }
+    async awaitConcurrentActivation(target, deadlineUnixMs) {
+        const key = authorityKey(target.targetSpotId);
+        const deadlineMs = performance.now() + Number(deadlineUnixMs - BigInt(Date.now()));
+        while (performance.now() <= deadlineMs) {
+            const current = await this.options.store.readAuthority(key);
+            if (current.kind === 'snapshot') {
+                if (current.allocation.objectKind !== 'instance_spot'
+                    || current.allocation.stableType !== target.stableType) {
+                    throw new Error('Concurrent Instance activation resolved to a different Spot type.');
+                }
+                if (current.allocation.state === 'active') {
+                    return readyExisting(current, target);
+                }
+            }
+            else {
+                throw new Error('Concurrent Instance activation ended before the Ready barrier.');
+            }
+            await waitForActivationJoin(deadlineMs);
+        }
+        throw new Error(`Concurrent Instance activation for '${target.targetSpotId}' did not reach Ready before deadline.`);
+    }
+    async awaitClosingRelease(target, deadlineUnixMs) {
+        const key = authorityKey(target.targetSpotId);
+        const deadlineMs = performance.now() + Number(deadlineUnixMs - BigInt(Date.now()));
+        while (performance.now() <= deadlineMs) {
+            const current = await this.options.store.readAuthority(key);
+            if (current.kind !== 'snapshot')
+                return;
+            const decoded = (0, service_authority_payload_codec_1.decodeServiceInstanceAuthorityPayload)(current.payload);
+            if (current.allocation.objectKind !== 'instance_spot'
+                || current.allocation.stableType !== target.stableType
+                || decoded?.kind !== 'instance_spot'
+                || decoded.spotId !== target.targetSpotId) {
+                throw new Error('Instance authority changed to a different Spot while closing.');
+            }
+            if (decoded.state !== 'closing')
+                return;
+            await waitForActivationJoin(deadlineMs);
+        }
+        throw new Error(`Instance Spot '${target.targetSpotId}' close did not release authority before deadline.`);
+    }
+    requirePending(reservation) {
+        const pending = this.pending.get(reservation.token);
+        if (pending === undefined
+            || pending.creating.objectGeneration !== reservation.attempt) {
+            throw new Error('Instance activation reservation is stale.');
+        }
+        return pending;
+    }
+}
+exports.ZLinkInstanceActivationAuthority = ZLinkInstanceActivationAuthority;
+function readyRead(snapshot, target) {
+    const decoded = (0, service_authority_payload_codec_1.decodeServiceReadySpotAuthority)(snapshot.payload);
+    const creating = (0, service_authority_payload_codec_1.decodeServiceInstanceAuthorityPayload)(snapshot.payload);
+    if (creating?.state === 'coldActivating'
+        && snapshot.allocation.objectKind === 'instance_spot'
+        && snapshot.allocation.state === 'reserved'
+        && creating.stableType === target.stableType
+        && creating.spotId === target.targetSpotId
+        && creating.ownerId === snapshot.ownerId
+        && creating.ownerLeaseGeneration === snapshot.ownerLeaseGeneration
+        && creating.ownerMeshName === snapshot.allocation.descriptor.meshName
+        && creating.ownerNodeGeneration === snapshot.allocation.descriptorLifecycleGeneration
+        && (0, routing_id_1.routingIdsEqual)(creating.ownerNodeRid, snapshot.allocation.descriptor.rid)
+        && (0, routing_id_1.routingIdsEqual)(target.targetNodeRid, snapshot.allocation.descriptor.rid)
+        && target.targetNodeGeneration === snapshot.allocation.descriptorLifecycleGeneration) {
+        return {
+            kind: 'creating',
+            objectGeneration: snapshot.objectGeneration,
+            authorityOwnerGeneration: snapshot.authorityOwnerGeneration
+        };
+    }
+    if (decoded?.kind !== 'instance_spot'
+        || decoded.stableType !== target.stableType
+        || decoded.spotId !== target.targetSpotId
+        || snapshot.allocation.objectKind !== 'instance_spot'
+        || snapshot.allocation.state !== 'active'
+        || decoded.ownerId !== snapshot.ownerId
+        || decoded.ownerLeaseGeneration !== snapshot.ownerLeaseGeneration
+        || decoded.ownerMeshName !== snapshot.allocation.descriptor.meshName
+        || decoded.ownerNodeGeneration !== snapshot.allocation.descriptorLifecycleGeneration
+        || !(0, routing_id_1.routingIdsEqual)(decoded.ownerNodeRid, snapshot.allocation.descriptor.rid)
+        || !(0, routing_id_1.routingIdsEqual)(target.targetNodeRid, snapshot.allocation.descriptor.rid)
+        || target.targetNodeGeneration !== snapshot.allocation.descriptorLifecycleGeneration) {
+        return { kind: 'missing' };
+    }
+    return { kind: 'ready', route: routeFromSnapshot(snapshot) };
+}
+function readyExisting(snapshot, target) {
+    const decoded = (0, service_authority_payload_codec_1.decodeServiceReadySpotAuthority)(snapshot.payload);
+    if (decoded?.kind !== 'instance_spot'
+        || decoded.stableType !== target.stableType
+        || decoded.spotId !== target.targetSpotId
+        || snapshot.allocation.objectKind !== 'instance_spot'
+        || snapshot.allocation.state !== 'active'
+        || decoded.ownerId !== snapshot.ownerId
+        || decoded.ownerLeaseGeneration !== snapshot.ownerLeaseGeneration
+        || decoded.ownerMeshName !== snapshot.allocation.descriptor.meshName
+        || decoded.ownerNodeGeneration !== snapshot.allocation.descriptorLifecycleGeneration
+        || !(0, routing_id_1.routingIdsEqual)(decoded.ownerNodeRid, snapshot.allocation.descriptor.rid)) {
+        throw new Error('Existing Instance authority is not a matching Ready allocation.');
+    }
+    return { kind: 'ready', route: routeFromSnapshot(snapshot) };
+}
+async function waitForActivationJoin(deadlineMs) {
+    const remaining = deadlineMs - performance.now();
+    if (remaining <= 0)
+        return;
+    await new Promise((resolve) => {
+        setTimeout(resolve, Math.min(ACTIVATION_JOIN_POLL_INTERVAL_MS, remaining));
+    });
+}
+function requireCommitIdentity(target, reservation, creating, spot, meshName) {
+    if (creating.allocation.state !== 'reserved'
+        || creating.allocation.objectKind !== 'instance_spot'
+        || creating.allocation.stableType !== target.stableType
+        || creating.objectGeneration !== reservation.attempt
+        || !(0, routing_id_1.routingIdsEqual)(creating.allocation.descriptor.rid, target.targetNodeRid)
+        || creating.allocation.descriptor.meshName !== meshName
+        || creating.allocation.descriptorLifecycleGeneration !== target.targetNodeGeneration
+        || spot.kind !== 'instance'
+        || spot.stableType !== target.stableType
+        || spot.ref.spotId !== target.targetSpotId
+        || spot.ref.generation !== reservation.attempt
+        || spot.authorityOwnerGeneration !== creating.authorityOwnerGeneration) {
+        throw new Error('Instance activation Ready identity does not match its exact reservation.');
+    }
+}
+function routeFromSnapshot(snapshot) {
+    const decoded = (0, service_authority_payload_codec_1.decodeServiceReadySpotAuthority)(snapshot.payload);
+    if (decoded?.kind !== 'instance_spot') {
+        throw new Error('Instance authority is not Ready.');
+    }
+    return {
+        targetNodeRid: String(snapshot.allocation.descriptor.rid),
+        targetNodeGeneration: snapshot.allocation.descriptorLifecycleGeneration,
+        targetSpotId: decoded.spotId,
+        objectGeneration: snapshot.objectGeneration,
+        ownerId: snapshot.ownerId,
+        authorityOwnerGeneration: snapshot.authorityOwnerGeneration,
+        leaseGeneration: snapshot.ownerLeaseGeneration,
+        storeVersion: snapshot.storeVersion.value
+    };
+}
+function authorityKey(spotId) {
+    return (0, authority_key_codec_1.encodeAuthorityKey)('instance_spot', spotId);
+}

package/dist/runtime/host/location-runtime-owner.d.ts

@@ -0,0 +1,48 @@
+import type { RoutingId } from '../../contracts';
+import type { ZLinkRuntimeEventPublisher } from '../diagnostics';
+import type { ZLinkActorTransferStore } from '../../contracts/Locations/ActorTransfer';
+import type { ZLinkFrameworkRegistration } from '../configuration';
+import type { ZLinkChannelRuntimeManager } from '../channels';
+import { ZLinkLocationLifecycle, ZLinkLocationRuntime, ZLinkOwnerLeaseTracker, ZLinkStoreLocationResolvers, type ZLinkLocationEventSink, type ZLinkLocationRuntimeStores, type ZLinkDomainLocationStore } from '../locations';
+import type { ZLinkSpotNodeRuntimeManager } from '../spots';
+import type { ZLinkSpotRouteResolver } from '../spots/spot-routing-internal';
+export interface ZLinkLocationRuntimeOwnerOptions {
+    readonly registration: ZLinkFrameworkRegistration;
+    readonly runtimeEventPublisher: ZLinkRuntimeEventPublisher;
+    readonly fallbackNodeRid: RoutingId;
+    readonly metrics: import('../diagnostics').ZLinkRuntimeMetrics;
+    readonly rewriteAuthorityPayloadForOwner?: import('../locations').ZLinkLocationRuntimeOptions['rewriteAuthorityPayloadForOwner'];
+}
+export interface ZLinkLocationRuntimeStopSnapshot {
+    readonly runtime?: ZLinkLocationRuntime;
+    readonly lifecycle?: ZLinkLocationLifecycle;
+}
+export declare class ZLinkLocationRuntimeOwner {
+    private readonly options;
+    private stores?;
+    private runtime?;
+    private lifecycle?;
+    private events?;
+    private leaseTrackerState?;
+    private spotRouteInvalidator?;
+    constructor(options: ZLinkLocationRuntimeOwnerOptions);
+    get currentStores(): ZLinkLocationRuntimeStores | undefined;
+    get currentRuntime(): ZLinkLocationRuntime | undefined;
+    get currentLifecycle(): ZLinkLocationLifecycle | undefined;
+    get currentEvents(): ZLinkLocationEventSink | undefined;
+    get currentLeaseTracker(): ZLinkOwnerLeaseTracker | undefined;
+    setSpotRouteInvalidator(invalidator?: (spotId: RoutingId) => void): void;
+    actorTransferStore(): ZLinkActorTransferStore | undefined;
+    locationStore(): ZLinkDomainLocationStore | undefined;
+    ensureRuntime(primaryMeshName: string | undefined): ZLinkLocationRuntime | undefined;
+    createRefResolver(spotMeshNames: readonly string[]): ZLinkStoreLocationResolvers | undefined;
+    createSpotRouteResolver(spotMeshNames: readonly string[], spotRouterChannelIdByMesh: (meshName: string) => string, resolveLocalSpot?: (spotId: RoutingId) => import('../spots/spot-routing-internal').ZLinkSpotRouteTarget | undefined): ZLinkSpotRouteResolver | undefined;
+    createActorLocationResolver(spotMeshNames: readonly string[]): ZLinkStoreLocationResolvers | undefined;
+    ownerNodeRid(spotNodeRuntime?: ZLinkSpotNodeRuntimeManager): RoutingId;
+    startForRuntime(primaryMeshName: string | undefined, spotNodeRuntime: ZLinkSpotNodeRuntimeManager, channelRuntime: ZLinkChannelRuntimeManager): Promise<ZLinkLocationRuntime | undefined>;
+    clearForStop(): ZLinkLocationRuntimeStopSnapshot;
+    private createRuntimeStores;
+    private createAndRememberStores;
+    private leaseTracker;
+    private ensureEvents;
+}