@zlink-systems/framework 0.10.0

package/dist/runtime/foundation/service-relocation-aggregate-committer.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceRelocationAggregateCommitter = void 0;
+const service_relocation_runtime_1 = require("./service-relocation-runtime");
+const MAX_PREPARE_CONFLICT_ATTEMPTS = 8;
+/** Commits every owner and membership row through one Location Store fence. */
+class ServiceRelocationAggregateCommitter {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    async prepare(plan, signal) {
+        const participants = validateAndEncodeParticipants(plan);
+        const aggregateId = aggregateIdentity(plan.envelope.aggregateId);
+        const request = {
+            aggregateId,
+            aggregateGeneration: plan.envelope.aggregateGeneration,
+            participants,
+            inventoryDigest: Buffer.from((0, service_relocation_runtime_1.inventoryDigest)(plan.envelope.participants, plan.envelope.memberships), 'hex'),
+            targetDescriptor: plan.targetDescriptor,
+            targetDescriptorLifecycleGeneration: plan.targetDescriptorLifecycleGeneration,
+            capacity: plan.capacity,
+            targetOwner: plan.targetOwner
+        };
+        let result = await this.store.prepareAggregate(request, signal);
+        for (let attempt = 1; attempt < MAX_PREPARE_CONFLICT_ATTEMPTS && result.kind === 'conflict'; attempt++) {
+            // The provider CAS also fences auxiliary live-owner and capacity rows.
+            // A heartbeat can change one of those versions while every authority
+            // row remains the exact Store-confirmed value in this plan. Retry only
+            // that coordination loss; a changed authority row leaves immediately.
+            if (!await this.authorityStoreVersionsUnchanged(plan, signal))
+                break;
+            signal?.throwIfAborted();
+            result = await this.store.prepareAggregate(request, signal);
+        }
+        if (result.kind !== 'prepared' && result.kind !== 'alreadyPrepared') {
+            throw new Error(`Location Store rejected relocation aggregate prepare: ${result.kind}.`);
+        }
+        if (result.fence.aggregateId.value !== aggregateId.value
+            || result.fence.aggregateGeneration !== plan.envelope.aggregateGeneration) {
+            throw new Error('Location Store returned a different relocation aggregate fence.');
+        }
+        return { fence: result.fence, plan };
+    }
+    async authorityStoreVersionsUnchanged(plan, signal) {
+        for (const participant of plan.participants) {
+            const current = await this.store.readAuthority(participant.key, signal);
+            if (current.kind !== 'snapshot'
+                || current.storeVersion.value !== participant.expected.storeVersion.value) {
+                return false;
+            }
+        }
+        return true;
+    }
+    async commit(prepared, signal) {
+        try {
+            await this.commitFence(prepared.fence, signal);
+        }
+        catch (firstError) {
+            // A lost commit response is reconciled by repeating the exact durable fence.
+            try {
+                await this.commitFence(prepared.fence, signal);
+            }
+            catch {
+                throw firstError;
+            }
+        }
+        return await this.readCommittedParticipants(prepared.plan, signal);
+    }
+    async abort(prepared, signal) {
+        const result = await this.store.abortAggregate(prepared.fence, signal);
+        if (result.kind !== 'aborted' && result.kind !== 'alreadyAborted') {
+            throw new Error(`Location Store rejected relocation aggregate abort: ${result.kind}.`);
+        }
+    }
+    async commitFence(fence, signal) {
+        const result = await this.store.commitAggregate(fence, signal);
+        if (result.kind !== 'committed' && result.kind !== 'alreadyCommitted') {
+            throw new Error(`Location Store rejected relocation aggregate commit: ${result.kind}.`);
+        }
+    }
+    async readCommittedParticipants(plan, signal) {
+        const committed = new Map();
+        for (const participant of plan.participants) {
+            const current = await this.store.readAuthority(participant.key, signal);
+            if (current.kind !== 'snapshot'
+                || current.objectGeneration !== participant.expected.objectGeneration
+                || current.storeVersion.value === participant.expected.storeVersion.value
+                || !Buffer.from(current.payload).equals(Buffer.from(participant.authorityPayload))) {
+                throw new Error('Committed relocation aggregate does not match its exact participant plan.');
+            }
+            if (participant.ownerTransition === 'newOwner') {
+                if (current.ownerId !== plan.targetOwner.ownerId
+                    || current.ownerLeaseGeneration !== plan.targetOwner.leaseGeneration
+                    || current.authorityOwnerGeneration <= participant.expected.authorityOwnerGeneration) {
+                    throw new Error('Committed relocation participant has a different owner fence.');
+                }
+            }
+            else if (current.ownerId !== participant.expected.ownerId
+                || current.ownerLeaseGeneration !== participant.expected.ownerLeaseGeneration
+                || current.authorityOwnerGeneration !== participant.expected.authorityOwnerGeneration) {
+                throw new Error('Preserved relocation participant changed its owner fence.');
+            }
+            committed.set(participant.key.value, current);
+        }
+        return committed;
+    }
+}
+exports.ServiceRelocationAggregateCommitter = ServiceRelocationAggregateCommitter;
+function validateAndEncodeParticipants(plan) {
+    const envelopeByKey = new Map(plan.envelope.participants.map(value => [value.key, value]));
+    const ordered = [...plan.participants].sort((left, right) => left.key.value.localeCompare(right.key.value));
+    if (ordered.length !== plan.envelope.participants.length
+        || new Set(ordered.map(({ key }) => key.value)).size !== ordered.length) {
+        throw new TypeError('Relocation aggregate plan must cover every participant exactly once.');
+    }
+    return ordered.map(participant => {
+        const envelope = envelopeByKey.get(participant.key.value);
+        if (envelope === undefined
+            || envelope.objectGeneration !== participant.expected.objectGeneration
+            || envelope.authorityOwnerGeneration !== participant.expected.authorityOwnerGeneration) {
+            throw new TypeError('Relocation aggregate participant fence differs from its envelope.');
+        }
+        return {
+            authorityKey: participant.key,
+            expectedStoreVersion: participant.expected.storeVersion,
+            ownerTransition: participant.ownerTransition,
+            authorityPayload: Buffer.from(participant.authorityPayload),
+            membershipMutation: Buffer.from(participant.membershipMutation)
+        };
+    });
+}
+function aggregateIdentity(value) {
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(value)
+        || /^0{8}-0{4}-0{4}-0{4}-0{12}$/.test(value)) {
+        throw new TypeError('Relocation aggregate id must be a lowercase non-zero 128-bit identity.');
+    }
+    return { value };
+}

package/dist/runtime/foundation/service-relocation-coordinator.d.ts

@@ -0,0 +1,19 @@
+import type { ZLinkAuthoritySnapshot } from '../locations/internal-location-contracts';
+import type { ServiceRelocationEnvelope } from './service-relocation-runtime';
+export interface ServiceRelocationStaging {
+    readonly id: string;
+}
+export interface ServiceRelocationRestoreOwner<TStaging extends ServiceRelocationStaging> {
+    prepare(envelope: ServiceRelocationEnvelope, signal?: AbortSignal): Promise<TStaging>;
+    publish(staging: TStaging, authority: ZLinkAuthoritySnapshot, signal?: AbortSignal): Promise<void>;
+    restoreSavedWork(staging: TStaging, signal?: AbortSignal): Promise<void>;
+    normalize(staging: TStaging, authority: ZLinkAuthoritySnapshot, signal?: AbortSignal): Promise<void>;
+    openAdmission(staging: TStaging, signal?: AbortSignal): Promise<void>;
+    abort(staging: TStaging): Promise<void> | void;
+}
+export declare class ServiceRelocationPostCommitError extends Error {
+    readonly authority: ZLinkAuthoritySnapshot;
+    readonly staging: ServiceRelocationStaging;
+    readonly cause: unknown;
+    constructor(authority: ZLinkAuthoritySnapshot, staging: ServiceRelocationStaging, cause: unknown);
+}

package/dist/runtime/foundation/service-relocation-coordinator.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceRelocationPostCommitError = void 0;
+class ServiceRelocationPostCommitError extends Error {
+    authority;
+    staging;
+    cause;
+    constructor(authority, staging, cause) {
+        super('Relocation owner committed, but target publication failed.');
+        this.authority = authority;
+        this.staging = staging;
+        this.cause = cause;
+        this.name = 'ServiceRelocationPostCommitError';
+    }
+}
+exports.ServiceRelocationPostCommitError = ServiceRelocationPostCommitError;

package/dist/runtime/foundation/service-relocation-object-owner.d.ts

@@ -0,0 +1,71 @@
+import type { ZLinkAuthorityKey, ZLinkAuthoritySnapshot } from '../locations/internal-location-contracts';
+import type { ServiceRelocationRestoreOwner, ServiceRelocationStaging } from './service-relocation-coordinator';
+import type { ServiceRelocationEnvelope, ServiceRelocationMembership, ServiceRelocationParticipant, ServiceRelocationQueuedMessage, ServiceRelocationTimer } from './service-relocation-runtime';
+export interface ServiceRelocationSealedWork {
+    readonly boundSessionState: Uint8Array;
+    readonly queuedMessages: readonly ServiceRelocationQueuedMessage[];
+    readonly timers: readonly ServiceRelocationTimer[];
+}
+export interface ServiceRelocationCaptureUnit {
+    readonly authorityKey: string;
+    readonly objectKind: 'actor' | 'user_spot' | 'instance_spot';
+    readonly stableType: string;
+    readonly objectGeneration: bigint;
+    readonly authorityOwnerGeneration: bigint;
+    seal(signal?: AbortSignal): Promise<ServiceRelocationSealedWork>;
+    captureApplicationState(signal?: AbortSignal): Promise<Uint8Array>;
+    commitSeal(): Promise<void> | void;
+    abortSeal(): Promise<void> | void;
+}
+export declare class ServiceCapturedObjectRelocation {
+    readonly envelope: ServiceRelocationEnvelope;
+    private readonly units;
+    private terminal;
+    constructor(envelope: ServiceRelocationEnvelope, units: readonly ServiceRelocationCaptureUnit[]);
+    commitSource(): Promise<void>;
+    abortSource(): Promise<void>;
+}
+/** Captures the two valid relocation units: User Spot aggregate or one Actor. */
+export declare class ServiceRelocationObjectCaptureOwner {
+    private readonly maxConcurrentCallbacks;
+    constructor(maxConcurrentCallbacks?: number);
+    captureUserSpotAggregate(aggregateId: string, aggregateGeneration: bigint, spot: ServiceRelocationCaptureUnit, actors: readonly ServiceRelocationCaptureUnit[], memberships: readonly ServiceRelocationMembership[], signal?: AbortSignal): Promise<ServiceCapturedObjectRelocation>;
+    captureStandaloneActor(aggregateId: string, aggregateGeneration: bigint, actor: ServiceRelocationCaptureUnit, membership: ServiceRelocationMembership, signal?: AbortSignal): Promise<ServiceCapturedObjectRelocation>;
+    captureInstanceSpotAggregate(aggregateId: string, aggregateGeneration: bigint, spot: ServiceRelocationCaptureUnit, actors: readonly ServiceRelocationCaptureUnit[], memberships: readonly ServiceRelocationMembership[], signal?: AbortSignal): Promise<ServiceCapturedObjectRelocation>;
+    private capture;
+}
+export interface ServiceRelocationHiddenObject {
+    readonly authorityKey: string;
+}
+export interface ServiceRelocationTargetObjectPort<THidden extends ServiceRelocationHiddenObject> {
+    createHidden(participant: ServiceRelocationParticipant, signal?: AbortSignal): Promise<THidden>;
+    restoreApplicationState(hidden: THidden, payload: Uint8Array, signal?: AbortSignal): Promise<void>;
+    restoreMemberships(hidden: ReadonlyMap<string, THidden>, memberships: readonly ServiceRelocationMembership[], signal?: AbortSignal): Promise<void>;
+    publish(hidden: THidden, authority: ZLinkAuthoritySnapshot, signal?: AbortSignal): Promise<void>;
+    restoreBoundSession(hidden: THidden, payload: Uint8Array, signal?: AbortSignal): Promise<void>;
+    replayQueuedMessage(hidden: THidden, message: ServiceRelocationQueuedMessage, signal?: AbortSignal): Promise<void>;
+    restoreTimer(hidden: THidden, timer: ServiceRelocationTimer, signal?: AbortSignal): Promise<void>;
+    normalize(hidden: THidden, authority: ZLinkAuthoritySnapshot, signal?: AbortSignal): Promise<void>;
+    openAdmission(hidden: THidden, signal?: AbortSignal): Promise<void>;
+    abort(hidden: THidden): Promise<void> | void;
+}
+export interface ServiceObjectRelocationStaging<THidden extends ServiceRelocationHiddenObject> extends ServiceRelocationStaging {
+    readonly primaryAuthorityKey: ZLinkAuthorityKey;
+    readonly envelope: ServiceRelocationEnvelope;
+    readonly hidden: ReadonlyMap<string, THidden>;
+}
+/** Restores an exact User Spot aggregate or standalone Actor into hidden objects. */
+export declare class ServiceRelocationObjectRestoreOwner<THidden extends ServiceRelocationHiddenObject> implements ServiceRelocationRestoreOwner<ServiceObjectRelocationStaging<THidden>> {
+    private readonly target;
+    private readonly authorityKey;
+    private readonly maxConcurrentCallbacks;
+    constructor(target: ServiceRelocationTargetObjectPort<THidden>, authorityKey: (value: string) => ZLinkAuthorityKey, maxConcurrentCallbacks?: number);
+    prepare(envelope: ServiceRelocationEnvelope, signal?: AbortSignal): Promise<ServiceObjectRelocationStaging<THidden>>;
+    publish(staging: ServiceObjectRelocationStaging<THidden>, authority: ZLinkAuthoritySnapshot, signal?: AbortSignal): Promise<void>;
+    restoreSavedWork(staging: ServiceObjectRelocationStaging<THidden>, signal?: AbortSignal): Promise<void>;
+    /** Appends one post-capture relay to the already restored temporary queue. */
+    replayRelayedMessage(staging: ServiceObjectRelocationStaging<THidden>, authorityKey: string, message: ServiceRelocationQueuedMessage, signal?: AbortSignal): Promise<void>;
+    normalize(staging: ServiceObjectRelocationStaging<THidden>, authority: ZLinkAuthoritySnapshot, signal?: AbortSignal): Promise<void>;
+    openAdmission(staging: ServiceObjectRelocationStaging<THidden>, signal?: AbortSignal): Promise<void>;
+    abort(staging: ServiceObjectRelocationStaging<THidden>): Promise<void>;
+}

package/dist/runtime/foundation/service-relocation-object-owner.js

@@ -0,0 +1,242 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceRelocationObjectRestoreOwner = exports.ServiceRelocationObjectCaptureOwner = exports.ServiceCapturedObjectRelocation = void 0;
+class ServiceCapturedObjectRelocation {
+    envelope;
+    units;
+    terminal = 'open';
+    constructor(envelope, units) {
+        this.envelope = envelope;
+        this.units = units;
+    }
+    async commitSource() {
+        if (this.terminal === 'committed')
+            return;
+        if (this.terminal === 'aborted') {
+            throw new Error('Relocation source capture was already aborted.');
+        }
+        for (const unit of this.units)
+            await unit.commitSeal();
+        this.terminal = 'committed';
+    }
+    async abortSource() {
+        if (this.terminal === 'aborted')
+            return;
+        if (this.terminal === 'committed') {
+            throw new Error('Committed relocation source capture cannot be aborted.');
+        }
+        const failures = [];
+        for (const unit of [...this.units].reverse()) {
+            try {
+                await unit.abortSeal();
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        this.terminal = 'aborted';
+        if (failures.length !== 0) {
+            throw new AggregateError(failures, 'Relocation source rollback was incomplete.');
+        }
+    }
+}
+exports.ServiceCapturedObjectRelocation = ServiceCapturedObjectRelocation;
+/** Captures the two valid relocation units: User Spot aggregate or one Actor. */
+class ServiceRelocationObjectCaptureOwner {
+    maxConcurrentCallbacks;
+    constructor(maxConcurrentCallbacks = 8) {
+        this.maxConcurrentCallbacks = maxConcurrentCallbacks;
+        requireCallbackConcurrency(maxConcurrentCallbacks);
+    }
+    async captureUserSpotAggregate(aggregateId, aggregateGeneration, spot, actors, memberships, signal) {
+        if (spot.objectKind !== 'user_spot' || actors.some(actor => actor.objectKind !== 'actor')) {
+            throw new TypeError('User Spot relocation requires one Spot and only Actor participants.');
+        }
+        if (actors.length !== memberships.length) {
+            throw new TypeError('User Spot relocation membership must cover every Actor exactly once.');
+        }
+        return await this.capture(aggregateId, aggregateGeneration, [spot, ...actors], memberships, signal);
+    }
+    async captureStandaloneActor(aggregateId, aggregateGeneration, actor, membership, signal) {
+        if (actor.objectKind !== 'actor' || membership.actorKey !== actor.authorityKey) {
+            throw new TypeError('Standalone Actor relocation has an invalid membership identity.');
+        }
+        return await this.capture(aggregateId, aggregateGeneration, [actor], [membership], signal);
+    }
+    async captureInstanceSpotAggregate(aggregateId, aggregateGeneration, spot, actors, memberships, signal) {
+        if (spot.objectKind !== 'instance_spot'
+            || actors.some(actor => actor.objectKind !== 'actor')) {
+            throw new TypeError('Instance Spot relocation requires one Spot and only Actor participants.');
+        }
+        if (actors.length !== memberships.length) {
+            throw new TypeError('Instance Spot relocation membership must cover every Actor exactly once.');
+        }
+        return await this.capture(aggregateId, aggregateGeneration, [spot, ...actors], memberships, signal);
+    }
+    async capture(aggregateId, aggregateGeneration, units, memberships, signal) {
+        const captured = [];
+        try {
+            for (const unit of units) {
+                signal?.throwIfAborted();
+                const work = await unit.seal(signal);
+                captured.push({ unit, work });
+            }
+            const participants = await mapConcurrentOrdered(captured, this.maxConcurrentCallbacks, async ({ unit, work }) => ({
+                key: unit.authorityKey,
+                objectKind: unit.objectKind,
+                stableType: unit.stableType,
+                objectGeneration: unit.objectGeneration,
+                authorityOwnerGeneration: unit.authorityOwnerGeneration,
+                applicationState: Buffer.from(await unit.captureApplicationState(signal)),
+                boundSessionState: Buffer.from(work.boundSessionState),
+                queuedMessages: work.queuedMessages.map(message => ({
+                    sequence: message.sequence,
+                    payload: Buffer.from(message.payload)
+                })),
+                timers: work.timers.map(timer => ({ ...timer }))
+            }), signal);
+            return new ServiceCapturedObjectRelocation({
+                aggregateId,
+                aggregateGeneration,
+                participants,
+                memberships
+            }, units);
+        }
+        catch (error) {
+            for (const { unit } of captured.reverse())
+                await unit.abortSeal();
+            throw error;
+        }
+    }
+}
+exports.ServiceRelocationObjectCaptureOwner = ServiceRelocationObjectCaptureOwner;
+/** Restores an exact User Spot aggregate or standalone Actor into hidden objects. */
+class ServiceRelocationObjectRestoreOwner {
+    target;
+    authorityKey;
+    maxConcurrentCallbacks;
+    constructor(target, authorityKey, maxConcurrentCallbacks = 8) {
+        this.target = target;
+        this.authorityKey = authorityKey;
+        this.maxConcurrentCallbacks = maxConcurrentCallbacks;
+        requireCallbackConcurrency(maxConcurrentCallbacks);
+    }
+    async prepare(envelope, signal) {
+        validateRelocationShape(envelope);
+        const hidden = new Map();
+        try {
+            const participants = [...envelope.participants].sort((left, right) => {
+                const leftActor = left.objectKind === 'actor' ? 1 : 0;
+                const rightActor = right.objectKind === 'actor' ? 1 : 0;
+                if (leftActor !== rightActor)
+                    return leftActor - rightActor;
+                return left.key.localeCompare(right.key);
+            });
+            for (const participant of participants) {
+                signal?.throwIfAborted();
+                const created = await this.target.createHidden(participant, signal);
+                if (created.authorityKey !== participant.key || hidden.has(created.authorityKey)) {
+                    throw new Error('Target factory returned a different relocation authority identity.');
+                }
+                hidden.set(created.authorityKey, created);
+            }
+            await mapConcurrentOrdered(participants, this.maxConcurrentCallbacks, participant => this.target.restoreApplicationState(hidden.get(participant.key), participant.applicationState, signal), signal);
+            await this.target.restoreMemberships(hidden, envelope.memberships, signal);
+            const spot = envelope.participants.find(({ objectKind }) => objectKind === 'user_spot' || objectKind === 'instance_spot');
+            const primary = spot ?? envelope.participants[0];
+            return {
+                id: `${envelope.aggregateId}:${envelope.aggregateGeneration}`,
+                primaryAuthorityKey: this.authorityKey(primary.key),
+                envelope,
+                hidden
+            };
+        }
+        catch (error) {
+            for (const value of [...hidden.values()].reverse())
+                await this.target.abort(value);
+            throw error;
+        }
+    }
+    async publish(staging, authority, signal) {
+        for (const hidden of staging.hidden.values()) {
+            await this.target.publish(hidden, authority, signal);
+        }
+    }
+    async restoreSavedWork(staging, signal) {
+        for (const participant of staging.envelope.participants) {
+            const hidden = staging.hidden.get(participant.key);
+            await this.target.restoreBoundSession(hidden, participant.boundSessionState, signal);
+            for (const message of participant.queuedMessages) {
+                await this.target.replayQueuedMessage(hidden, message, signal);
+            }
+            for (const timer of participant.timers) {
+                await this.target.restoreTimer(hidden, timer, signal);
+            }
+        }
+    }
+    /** Appends one post-capture relay to the already restored temporary queue. */
+    async replayRelayedMessage(staging, authorityKey, message, signal) {
+        const hidden = staging.hidden.get(authorityKey);
+        if (hidden === undefined) {
+            throw new Error(`Relocation relay target '${authorityKey}' is not staged.`);
+        }
+        await this.target.replayQueuedMessage(hidden, message, signal);
+    }
+    async normalize(staging, authority, signal) {
+        for (const hidden of staging.hidden.values()) {
+            await this.target.normalize(hidden, authority, signal);
+        }
+    }
+    async openAdmission(staging, signal) {
+        for (const hidden of staging.hidden.values()) {
+            await this.target.openAdmission(hidden, signal);
+        }
+    }
+    async abort(staging) {
+        for (const hidden of [...staging.hidden.values()].reverse()) {
+            await this.target.abort(hidden);
+        }
+    }
+}
+exports.ServiceRelocationObjectRestoreOwner = ServiceRelocationObjectRestoreOwner;
+function validateRelocationShape(envelope) {
+    const spots = envelope.participants.filter(({ objectKind }) => objectKind === 'user_spot' || objectKind === 'instance_spot');
+    const actors = envelope.participants.filter(({ objectKind }) => objectKind === 'actor');
+    if (spots.length === 0 && (actors.length !== 1 || envelope.participants.length !== 1)) {
+        throw new TypeError('Standalone relocation must contain exactly one Actor.');
+    }
+    if (spots.length === 1 && actors.length + 1 !== envelope.participants.length) {
+        throw new TypeError('User Spot aggregate contains an unsupported participant kind.');
+    }
+    if (spots.length > 1 || envelope.memberships.length !== actors.length) {
+        throw new TypeError('Relocation membership inventory does not cover its Actor participants.');
+    }
+}
+function requireCallbackConcurrency(value) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new RangeError('Relocation callback concurrency must be a positive safe integer.');
+    }
+}
+async function mapConcurrentOrdered(values, concurrency, callback, signal) {
+    const results = new Array(values.length);
+    let next = 0;
+    let failure;
+    const worker = async () => {
+        while (failure === undefined) {
+            signal?.throwIfAborted();
+            const index = next++;
+            if (index >= values.length)
+                return;
+            try {
+                results[index] = await callback(values[index], index);
+            }
+            catch (error) {
+                failure = error;
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, values.length) }, () => worker()));
+    if (failure !== undefined)
+        throw failure;
+    return results;
+}

package/dist/runtime/foundation/service-relocation-runtime.d.ts

@@ -0,0 +1,143 @@
+import type { ZLinkPlacementObjectKind } from '../locations/internal-location-contracts';
+export interface ServiceRelocationParticipant {
+    /** Wire-local participant ordinal; identity is projected from Location Store. */
+    readonly participantId?: bigint;
+    /** Root projection carried by relocation-envelope-v1, never a participant identity vector. */
+    readonly rootSpotId?: string;
+    readonly rootSpotGeneration?: bigint;
+    readonly rootOwnerGeneration?: bigint;
+    readonly rootObjectKind?: ZLinkPlacementObjectKind;
+    readonly rootStableType?: string;
+    readonly key: string;
+    readonly objectKind: ZLinkPlacementObjectKind;
+    readonly stableType: string;
+    readonly objectGeneration: bigint;
+    readonly authorityOwnerGeneration: bigint;
+    /** Preserves relocation-envelope-v1's absent-state projection on decode. */
+    readonly applicationStatePresent?: boolean;
+    readonly applicationState: Uint8Array;
+    readonly boundSessionState: Uint8Array;
+    readonly queuedMessages: readonly ServiceRelocationQueuedMessage[];
+    readonly timers: readonly ServiceRelocationTimer[];
+}
+export interface ServiceRelocationQueuedMessage {
+    readonly sequence: bigint;
+    readonly payload: Uint8Array;
+}
+export interface ServiceRelocationTimer {
+    readonly timerId: string;
+    readonly handlerType: string;
+    readonly startedAtUnixMs: number;
+    readonly dueAtUnixMs: number;
+    readonly intervalMs: number;
+    readonly deliveryIndex: bigint;
+    readonly lastScheduledIndex: bigint;
+    readonly overrunPolicy: string;
+    readonly maxCatchUpTicks: number;
+    readonly stopOnUnhandledException: boolean;
+    readonly pendingTicks: readonly ServiceRelocationPendingTimerTick[];
+}
+export interface ServiceRelocationPendingTimerTick {
+    /** Wire order retained on decode; local capture assigns it when omitted. */
+    readonly order?: bigint;
+    readonly deliveryIndex: bigint;
+    readonly scheduledIndex: bigint;
+    readonly scheduledAtUnixMs: number;
+    readonly skippedTicks: bigint;
+}
+export interface ServiceRelocationMembership {
+    readonly actorKey: string;
+    readonly spotKey: string;
+    readonly spotObjectGeneration: bigint;
+    readonly membershipEpoch: bigint;
+}
+export interface ServiceRelocationEnvelope {
+    readonly aggregateId: string;
+    readonly aggregateGeneration: bigint;
+    /** Deployment ordinal carried by relocation-envelope-v1, distinct from staging identity. */
+    readonly applicationVersion?: bigint;
+    readonly participants: readonly ServiceRelocationParticipant[];
+    readonly memberships: readonly ServiceRelocationMembership[];
+}
+export interface ServiceRelocationPublication {
+    readonly reference: string;
+    readonly checksumCrc32c: number;
+    readonly aggregateId: string;
+    readonly aggregateGeneration: bigint;
+    readonly inventoryDigest: string;
+    readonly targetOwnerId: string;
+    readonly targetOwnerLeaseGeneration: bigint;
+    /** Canonical authority-slot fields retained when a publication is replaced. */
+    readonly targetAttemptGeneration?: bigint;
+    readonly sourceNodeRid?: string;
+    readonly sourceNodeGeneration?: bigint;
+    readonly sourceOwnerId?: string;
+    readonly sourceOwnerLeaseGeneration?: bigint;
+    readonly targetNodeRid?: string;
+    readonly targetNodeGeneration?: bigint;
+    readonly coordinatorOwnerId?: string;
+    readonly coordinatorLeaseGeneration?: bigint;
+    readonly coordinatorNodeRid?: string;
+    readonly coordinatorNodeGeneration?: bigint;
+    readonly coordinatorExpectedStoreVersion?: string;
+    readonly canonicalPhase?: number;
+    readonly canonicalSourceCleanupState?: number;
+    /** True when the publication lives in the canonical ZLAU relocation slot. */
+    readonly canonical?: boolean;
+    readonly applicationVersion?: bigint;
+}
+export interface ServiceRelocationAuthorityCodec {
+    publish(currentPayload: Uint8Array, publication: ServiceRelocationPublication): Uint8Array;
+    read(payload: Uint8Array): ServiceRelocationPublication | undefined;
+    clear(currentPayload: Uint8Array, expectedReference: string): Uint8Array;
+}
+export interface CanonicalRelocationSlot {
+    readonly aggregateId: string;
+    readonly aggregateGeneration: bigint;
+    readonly targetAttemptGeneration: bigint;
+    readonly reference: string;
+    readonly checksumCrc32c: number;
+    readonly sourceNodeRid: string;
+    readonly sourceNodeGeneration: bigint;
+    readonly sourceOwnerId: string;
+    readonly sourceOwnerLeaseGeneration: bigint;
+    readonly targetNodeRid: string;
+    readonly targetNodeGeneration: bigint;
+    readonly applicationVersion: bigint;
+    readonly targetOwnerId: string;
+    readonly targetOwnerLeaseGeneration: bigint;
+    readonly coordinatorOwnerId: string;
+    readonly coordinatorLeaseGeneration: bigint;
+    readonly coordinatorNodeRid: string;
+    readonly coordinatorNodeGeneration: bigint;
+    readonly coordinatorExpectedStoreVersion: string;
+    readonly phase: number;
+    readonly sourceCleanupState: number;
+}
+/** Deterministic Location authority wrapper for one immutable relocation root. */
+export declare class ServiceRelocationAuthorityPayloadCodec implements ServiceRelocationAuthorityCodec {
+    publish(currentPayload: Uint8Array, publication: ServiceRelocationPublication): Uint8Array;
+    read(payload: Uint8Array): ServiceRelocationPublication | undefined;
+    clear(currentPayload: Uint8Array, expectedReference: string): Uint8Array;
+}
+/** Returns the application authority payload hidden by relocation metadata. */
+export declare function serviceRelocationAuthorityApplicationPayload(payload: Uint8Array): Buffer;
+/** Reads the canonical relocation identity even before its root pointer exists. */
+export declare function serviceRelocationAuthoritySlotIdentity(payload: Uint8Array): Pick<ServiceRelocationPublication, 'aggregateId' | 'aggregateGeneration' | 'applicationVersion'> | undefined;
+/** Replaces the application payload without changing relocation metadata. */
+export declare function replaceServiceRelocationAuthorityApplicationPayload(payload: Uint8Array, applicationPayload: Uint8Array): Buffer;
+/** Projects an embedded canonical relocation slot to the exact target-ready fence. */
+export declare function projectServiceRelocationAuthorityTargetReady(payload: Uint8Array, target: {
+    readonly targetAttemptGeneration: bigint;
+    readonly nodeRid: string;
+    readonly nodeGeneration: bigint;
+    readonly ownerId: string;
+    readonly ownerLeaseGeneration: bigint;
+    readonly coordinatorExpectedStoreVersion: string;
+}): Buffer;
+export declare function decodeCanonicalRelocationSlot(payload: Uint8Array, rootAggregateGeneration?: bigint): CanonicalRelocationSlot | undefined;
+export declare function encodeCanonicalRelocationSlot(value: CanonicalRelocationSlot): Buffer;
+export declare function encodeServiceRelocationEnvelope(envelope: ServiceRelocationEnvelope, applicationVersion: bigint): Buffer;
+export declare function decodeServiceRelocationEnvelope(payload: Uint8Array, aggregateGeneration: bigint): ServiceRelocationEnvelope;
+export declare function inventoryDigest(participants: readonly ServiceRelocationParticipant[], memberships?: readonly ServiceRelocationMembership[]): string;
+export declare function crc32c(payload: Uint8Array): number;