@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,1080 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceRelocationAuthorityPayloadCodec = void 0;
+exports.serviceRelocationAuthorityApplicationPayload = serviceRelocationAuthorityApplicationPayload;
+exports.serviceRelocationAuthoritySlotIdentity = serviceRelocationAuthoritySlotIdentity;
+exports.replaceServiceRelocationAuthorityApplicationPayload = replaceServiceRelocationAuthorityApplicationPayload;
+exports.projectServiceRelocationAuthorityTargetReady = projectServiceRelocationAuthorityTargetReady;
+exports.decodeCanonicalRelocationSlot = decodeCanonicalRelocationSlot;
+exports.encodeCanonicalRelocationSlot = encodeCanonicalRelocationSlot;
+exports.encodeServiceRelocationEnvelope = encodeServiceRelocationEnvelope;
+exports.decodeServiceRelocationEnvelope = decodeServiceRelocationEnvelope;
+exports.inventoryDigest = inventoryDigest;
+exports.crc32c = crc32c;
+const node_crypto_1 = require("node:crypto");
+const authority_key_codec_1 = require("../locations/authority-key-codec");
+const service_wire_pilot_codec_generated_1 = require("../protocol/service_wire_pilot_codec.generated");
+/** Deterministic Location authority wrapper for one immutable relocation root. */
+class ServiceRelocationAuthorityPayloadCodec {
+    publish(currentPayload, publication) {
+        if (this.read(currentPayload) !== undefined) {
+            throw new TypeError('Location authority already contains a relocation publication.');
+        }
+        const canonical = decodeCanonicalAuthorityLayout(currentPayload);
+        if (canonical !== undefined) {
+            return replaceCanonicalRelocationSlot(canonical, encodeCanonicalRelocationPublicationSlot(canonical, publication));
+        }
+        return encodeAuthorityEnvelope(Buffer.from(currentPayload), publication);
+    }
+    read(payload) {
+        return decodeCanonicalAuthorityPublication(payload)
+            ?? decodeAuthorityEnvelope(payload)?.publication;
+    }
+    clear(currentPayload, expectedReference) {
+        const canonical = decodeCanonicalAuthorityLayout(currentPayload);
+        const canonicalPublication = canonical === undefined
+            ? undefined
+            : decodeCanonicalRelocationSlot(canonical.slot);
+        if (canonical !== undefined && canonicalPublication?.reference !== undefined) {
+            if (canonicalPublication.reference !== requireText(expectedReference, 'relocation reference')) {
+                throw new TypeError('Location authority relocation reference changed.');
+            }
+            return replaceCanonicalRelocationSlot(canonical, Buffer.alloc(0));
+        }
+        const current = decodeAuthorityEnvelope(currentPayload);
+        if (current === undefined
+            || current.publication.reference !== requireText(expectedReference, 'relocation reference')) {
+            throw new TypeError('Location authority relocation reference changed.');
+        }
+        return Buffer.from(current.base);
+    }
+}
+exports.ServiceRelocationAuthorityPayloadCodec = ServiceRelocationAuthorityPayloadCodec;
+/** Returns the application authority payload hidden by relocation metadata. */
+function serviceRelocationAuthorityApplicationPayload(payload) {
+    const canonical = decodeCanonicalAuthorityLayout(payload);
+    if (canonical !== undefined && canonical.slot.byteLength !== 0) {
+        if (decodeCanonicalRelocationSlot(canonical.slot) === undefined) {
+            throw new TypeError('Canonical authority relocation slot is invalid.');
+        }
+        return replaceCanonicalRelocationSlot(canonical, Buffer.alloc(0));
+    }
+    return Buffer.from(decodeAuthorityEnvelope(payload)?.base ?? payload);
+}
+/** Reads the canonical relocation identity even before its root pointer exists. */
+function serviceRelocationAuthoritySlotIdentity(payload) {
+    const layout = decodeCanonicalAuthorityLayout(payload);
+    const slot = layout === undefined || layout.slot.byteLength === 0
+        ? undefined
+        : decodeCanonicalRelocationSlot(layout.slot);
+    return slot === undefined
+        ? undefined
+        : {
+            aggregateId: slot.aggregateId,
+            aggregateGeneration: slot.aggregateGeneration,
+            applicationVersion: slot.applicationVersion
+        };
+}
+/** Replaces the application payload without changing relocation metadata. */
+function replaceServiceRelocationAuthorityApplicationPayload(payload, applicationPayload) {
+    const canonical = decodeCanonicalAuthorityLayout(payload);
+    if (canonical !== undefined && canonical.slot.byteLength !== 0) {
+        const replacement = decodeCanonicalAuthorityLayout(applicationPayload);
+        if (replacement === undefined || replacement.slot.byteLength !== 0) {
+            throw new TypeError('Canonical authority application replacement is not steady ZLAU.');
+        }
+        return replaceCanonicalRelocationSlot(replacement, canonical.slot);
+    }
+    const current = decodeAuthorityEnvelope(payload);
+    return current === undefined
+        ? Buffer.from(applicationPayload)
+        : encodeAuthorityEnvelope(Buffer.from(applicationPayload), current.publication);
+}
+/** Projects an embedded canonical relocation slot to the exact target-ready fence. */
+function projectServiceRelocationAuthorityTargetReady(payload, target) {
+    const layout = decodeCanonicalAuthorityLayout(payload);
+    if (layout === undefined || layout.slot.byteLength === 0) {
+        throw new TypeError('Canonical authority relocation slot is missing.');
+    }
+    const current = decodeCanonicalRelocationSlot(layout.slot);
+    if (current === undefined) {
+        throw new TypeError('Canonical authority relocation slot is invalid.');
+    }
+    const slot = encodeCanonicalRelocationSlot({
+        ...current,
+        targetAttemptGeneration: target.targetAttemptGeneration,
+        targetNodeRid: target.nodeRid,
+        targetNodeGeneration: target.nodeGeneration,
+        targetOwnerId: target.ownerId,
+        targetOwnerLeaseGeneration: target.ownerLeaseGeneration,
+        coordinatorOwnerId: target.ownerId,
+        coordinatorLeaseGeneration: target.ownerLeaseGeneration,
+        coordinatorNodeRid: target.nodeRid,
+        coordinatorNodeGeneration: target.nodeGeneration,
+        coordinatorExpectedStoreVersion: target.coordinatorExpectedStoreVersion,
+        phase: 5,
+        sourceCleanupState: 0
+    });
+    return replaceCanonicalRelocationSlot(layout, slot);
+}
+function decodeCanonicalAuthorityPublication(payload) {
+    const layout = decodeCanonicalAuthorityLayout(payload);
+    if (layout === undefined || layout.slot.byteLength === 0)
+        return undefined;
+    const slot = decodeCanonicalRelocationSlot(layout.slot);
+    if (slot === undefined)
+        return undefined;
+    return {
+        reference: slot.reference,
+        checksumCrc32c: slot.checksumCrc32c,
+        aggregateId: slot.aggregateId,
+        aggregateGeneration: slot.aggregateGeneration,
+        inventoryDigest: '0'.repeat(64),
+        targetOwnerId: slot.targetOwnerId,
+        targetOwnerLeaseGeneration: slot.targetOwnerLeaseGeneration,
+        targetAttemptGeneration: slot.targetAttemptGeneration,
+        sourceNodeRid: slot.sourceNodeRid,
+        sourceNodeGeneration: slot.sourceNodeGeneration,
+        sourceOwnerId: slot.sourceOwnerId,
+        sourceOwnerLeaseGeneration: slot.sourceOwnerLeaseGeneration,
+        targetNodeRid: slot.targetNodeRid,
+        targetNodeGeneration: slot.targetNodeGeneration,
+        coordinatorOwnerId: slot.coordinatorOwnerId,
+        coordinatorLeaseGeneration: slot.coordinatorLeaseGeneration,
+        coordinatorNodeRid: slot.coordinatorNodeRid,
+        coordinatorNodeGeneration: slot.coordinatorNodeGeneration,
+        coordinatorExpectedStoreVersion: slot.coordinatorExpectedStoreVersion,
+        canonicalPhase: slot.phase,
+        canonicalSourceCleanupState: slot.sourceCleanupState,
+        canonical: true,
+        applicationVersion: slot.applicationVersion
+    };
+}
+function decodeCanonicalAuthorityLayout(payload) {
+    try {
+        const bytes = Buffer.from(payload);
+        if (bytes.byteLength < 20 || bytes.byteLength > 1024 * 1024)
+            return undefined;
+        const reader = new CanonicalReader(bytes);
+        reader.expect(Buffer.from('ZLAU'));
+        if (reader.u8() !== 1)
+            return undefined;
+        const flags = reader.u16();
+        const body = reader.take(reader.u32());
+        const checksumOffset = reader.offset;
+        if (reader.u32() !== crc32c(bytes.subarray(0, checksumOffset)) || !reader.done) {
+            return undefined;
+        }
+        const bodyReader = new CanonicalReader(body);
+        bodyReader.u8();
+        bodyReader.u8();
+        bodyReader.take(bodyReader.u16());
+        const ownerId = bodyReader.text8(false);
+        const ownerLeaseGeneration = bodyReader.u64();
+        bodyReader.text8(false);
+        const nodeRid = bodyReader.text8(false);
+        const nodeGeneration = bodyReader.u64();
+        const slotStart = bodyReader.offset;
+        const presence = bodyReader.u8();
+        if (presence > 1)
+            return undefined;
+        const slot = bodyReader.take(bodyReader.u32());
+        const slotEnd = bodyReader.offset;
+        if ((presence === 0) !== (slot.byteLength === 0))
+            return undefined;
+        return {
+            flags,
+            body: Buffer.from(body),
+            slotStart,
+            slotEnd,
+            slot: Buffer.from(slot),
+            ownerId,
+            ownerLeaseGeneration,
+            nodeRid,
+            nodeGeneration
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function decodeCanonicalRelocationSlot(payload, rootAggregateGeneration) {
+    try {
+        const reader = new CanonicalReader(payload);
+        const aggregateId = uuid(reader.u64(), reader.u64());
+        if (aggregateId === undefined)
+            return undefined;
+        const aggregateGeneration = reader.u64();
+        const targetAttemptGeneration = reader.u64();
+        const reference = reader.text16();
+        const checksumCrc32c = reader.u32();
+        const sourceNodeRid = reader.text8(false);
+        const sourceNodeGeneration = reader.u64();
+        const sourceOwnerId = reader.text8(false);
+        const sourceOwnerLeaseGeneration = reader.u64();
+        const targetNodeRid = reader.text8(true);
+        const targetNodeGeneration = reader.u64();
+        const targetOwnerId = reader.text8(true);
+        const targetOwnerLeaseGeneration = reader.u64();
+        const coordinatorOwnerId = reader.text8(false);
+        const coordinatorLeaseGeneration = reader.u64();
+        const coordinatorNodeRid = reader.text8(false);
+        const coordinatorNodeGeneration = reader.u64();
+        const coordinatorExpectedStoreVersion = reader.text8(true);
+        const phase = reader.u8();
+        const applicationVersion = reader.i64();
+        const sourceCleanupState = reader.u8();
+        if (!reader.done
+            || aggregateGeneration > 0x7ffffffffffffffen
+            || (aggregateGeneration === 0n && phase !== 1)
+            || (rootAggregateGeneration !== undefined
+                && aggregateGeneration !== rootAggregateGeneration)
+            || targetAttemptGeneration > 0x7fffffffffffffffn
+            || sourceNodeGeneration === 0n
+            || sourceNodeGeneration > 0x7fffffffffffffffn
+            || sourceOwnerLeaseGeneration === 0n
+            || sourceOwnerLeaseGeneration > 0x7fffffffffffffffn
+            || targetNodeGeneration > 0x7fffffffffffffffn
+            || targetOwnerLeaseGeneration > 0x7fffffffffffffffn
+            || coordinatorLeaseGeneration === 0n
+            || coordinatorLeaseGeneration > 0x7fffffffffffffffn
+            || coordinatorNodeGeneration === 0n
+            || coordinatorNodeGeneration > 0x7fffffffffffffffn
+            || phase < 1 || phase > 9
+            || applicationVersion < 0n
+            || sourceCleanupState > 2)
+            return undefined;
+        return {
+            aggregateId,
+            aggregateGeneration,
+            targetAttemptGeneration,
+            reference,
+            checksumCrc32c,
+            sourceNodeRid,
+            sourceNodeGeneration,
+            sourceOwnerId,
+            sourceOwnerLeaseGeneration,
+            targetNodeRid,
+            targetNodeGeneration,
+            applicationVersion,
+            targetOwnerId,
+            targetOwnerLeaseGeneration,
+            coordinatorOwnerId,
+            coordinatorLeaseGeneration,
+            coordinatorNodeRid,
+            coordinatorNodeGeneration,
+            coordinatorExpectedStoreVersion,
+            phase,
+            sourceCleanupState
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function encodeCanonicalRelocationSlot(value) {
+    const id = relocationId(canonicalUuid(value.aggregateId, 'aggregate id'));
+    const aggregateGeneration = nonNegativeBigInt(value.aggregateGeneration, 'aggregate generation');
+    const targetAttemptGeneration = nonNegativeBigInt(value.targetAttemptGeneration, 'target attempt generation');
+    if (aggregateGeneration > 0x7ffffffffffffffen) {
+        throw new TypeError('Aggregate generation exceeds the issued range.');
+    }
+    if (aggregateGeneration === 0n && value.phase !== 1) {
+        throw new TypeError('Zero aggregate generation is only valid while preparing.');
+    }
+    if (targetAttemptGeneration > 0x7fffffffffffffffn) {
+        throw new TypeError('Target attempt generation exceeds the ordinal range.');
+    }
+    const sourceNodeGeneration = canonicalNonZeroOrdinal(value.sourceNodeGeneration, 'source node generation');
+    const sourceOwnerLeaseGeneration = canonicalNonZeroOrdinal(value.sourceOwnerLeaseGeneration, 'source owner lease generation');
+    const targetNodeGeneration = canonicalOrdinal(value.targetNodeGeneration, 'target node generation');
+    const targetOwnerLeaseGeneration = canonicalOrdinal(value.targetOwnerLeaseGeneration, 'target owner lease generation');
+    const coordinatorLeaseGeneration = canonicalNonZeroOrdinal(value.coordinatorLeaseGeneration, 'coordinator lease generation');
+    const coordinatorNodeGeneration = canonicalNonZeroOrdinal(value.coordinatorNodeGeneration, 'coordinator node generation');
+    if (!Number.isInteger(value.phase) || value.phase < 1 || value.phase > 9) {
+        throw new TypeError('Canonical relocation phase is invalid.');
+    }
+    if (!Number.isInteger(value.sourceCleanupState)
+        || value.sourceCleanupState < 0
+        || value.sourceCleanupState > 2) {
+        throw new TypeError('Canonical source cleanup state is invalid.');
+    }
+    return Buffer.concat([
+        canonicalU64(id.high), canonicalU64(id.low),
+        canonicalU64(aggregateGeneration), canonicalU64(targetAttemptGeneration),
+        canonicalText16(value.reference), canonicalU32(value.checksumCrc32c),
+        canonicalText8(value.sourceNodeRid), canonicalU64(sourceNodeGeneration),
+        canonicalText8(value.sourceOwnerId), canonicalU64(sourceOwnerLeaseGeneration),
+        canonicalOptionalText8(value.targetNodeRid), canonicalU64(targetNodeGeneration),
+        canonicalOptionalText8(value.targetOwnerId), canonicalU64(targetOwnerLeaseGeneration),
+        canonicalText8(value.coordinatorOwnerId), canonicalU64(coordinatorLeaseGeneration),
+        canonicalText8(value.coordinatorNodeRid), canonicalU64(coordinatorNodeGeneration),
+        canonicalOptionalText8(value.coordinatorExpectedStoreVersion),
+        Buffer.of(value.phase), canonicalI64(value.applicationVersion),
+        Buffer.of(value.sourceCleanupState)
+    ]);
+}
+function encodeCanonicalRelocationPublicationSlot(layout, publication) {
+    validatePublication(publication);
+    if (layout.slot.byteLength !== 0) {
+        throw new TypeError('Canonical authority relocation slot is already published.');
+    }
+    const nodeRid = requireText(layout.nodeRid, 'canonical authority node rid');
+    const ownerId = requireText(layout.ownerId, 'canonical authority owner id');
+    const applicationVersion = nonNegativeBigInt(publication.applicationVersion ?? 0n, 'application version');
+    return encodeCanonicalRelocationSlot({
+        aggregateId: publication.aggregateId,
+        aggregateGeneration: publication.aggregateGeneration,
+        targetAttemptGeneration: publication.targetAttemptGeneration ?? 0n,
+        reference: publication.reference,
+        checksumCrc32c: publication.checksumCrc32c,
+        sourceNodeRid: publication.sourceNodeRid ?? nodeRid,
+        sourceNodeGeneration: publication.sourceNodeGeneration ?? layout.nodeGeneration,
+        sourceOwnerId: publication.sourceOwnerId ?? ownerId,
+        sourceOwnerLeaseGeneration: publication.sourceOwnerLeaseGeneration ?? layout.ownerLeaseGeneration,
+        targetNodeRid: publication.targetNodeRid ?? nodeRid,
+        targetNodeGeneration: publication.targetNodeGeneration ?? layout.nodeGeneration,
+        targetOwnerId: publication.targetOwnerId,
+        targetOwnerLeaseGeneration: publication.targetOwnerLeaseGeneration,
+        coordinatorOwnerId: publication.coordinatorOwnerId ?? ownerId,
+        coordinatorLeaseGeneration: publication.coordinatorLeaseGeneration ?? layout.ownerLeaseGeneration,
+        coordinatorNodeRid: publication.coordinatorNodeRid ?? nodeRid,
+        coordinatorNodeGeneration: publication.coordinatorNodeGeneration ?? layout.nodeGeneration,
+        coordinatorExpectedStoreVersion: publication.coordinatorExpectedStoreVersion ?? '',
+        phase: publication.canonicalPhase ?? 8,
+        applicationVersion,
+        sourceCleanupState: publication.canonicalSourceCleanupState ?? 0
+    });
+}
+function replaceCanonicalRelocationSlot(layout, slot) {
+    const encodedSlot = Buffer.from(slot);
+    const body = Buffer.concat([
+        layout.body.subarray(0, layout.slotStart),
+        Buffer.of(encodedSlot.byteLength === 0 ? 0 : 1),
+        canonicalU32(encodedSlot.byteLength),
+        encodedSlot,
+        layout.body.subarray(layout.slotEnd)
+    ]);
+    const envelope = Buffer.concat([
+        Buffer.from('ZLAU'), Buffer.of(1), canonicalU16(layout.flags),
+        canonicalU32(body.byteLength), body
+    ]);
+    const result = Buffer.concat([envelope, canonicalU32(crc32c(envelope))]);
+    if (result.byteLength > 1024 * 1024) {
+        throw new TypeError('Canonical authority payload exceeds 1 MiB.');
+    }
+    return result;
+}
+function validatePublication(publication) {
+    requireText(publication.reference, 'relocation reference');
+    canonicalUuid(publication.aggregateId, 'aggregate id');
+    const checksum = safeInteger(publication.checksumCrc32c, 'relocation checksum');
+    if (checksum < 0 || checksum > 0xffff_ffff) {
+        throw new TypeError('Relocation checksum must be an unsigned 32-bit integer.');
+    }
+    positiveBigInt(publication.aggregateGeneration, 'aggregate generation');
+    requireText(publication.targetOwnerId, 'target owner id');
+    positiveBigInt(publication.targetOwnerLeaseGeneration, 'target owner lease generation');
+}
+function encodeServiceRelocationEnvelope(envelope, applicationVersion) {
+    const aggregate = relocationId(canonicalUuid(envelope.aggregateId, 'aggregate id'));
+    const encodedApplicationVersion = nonNegativeBigInt(applicationVersion, 'application version');
+    const participants = canonicalParticipants(envelope.participants);
+    const root = participants.find(value => value.rootSpotId !== undefined)
+        ?? participants.find(value => value.objectKind !== 'actor')
+        ?? participants[0];
+    const rootObjectKind = root.rootObjectKind ?? root.objectKind;
+    if (rootObjectKind === 'actor' && participants.length !== 1) {
+        throw new TypeError('Standalone Actor relocation requires one participant.');
+    }
+    const applicationStates = participants.map((participant, index) => {
+        const hasState = participant.applicationStatePresent !== false;
+        if (!hasState && participant.applicationState.byteLength !== 0) {
+            throw new TypeError('Absent relocation application state must have an empty payload.');
+        }
+        return {
+            participantId: BigInt(index + 1),
+            hasState,
+            payload: Buffer.from(participant.applicationState)
+        };
+    });
+    const saved = participants.flatMap((participant, index) => participant.queuedMessages.map(message => ({
+        participantId: BigInt(index + 1),
+        order: positiveBigInt(message.sequence, 'queue sequence'),
+        frozenRecord: Buffer.from(message.payload)
+    }))).sort(compareParticipantOrder);
+    if (saved.some((value, index) => index > 0
+        && compareParticipantOrder(saved[index - 1], value) === 0)) {
+        throw new TypeError('Relocation queue sequences must be unique per participant.');
+    }
+    const timers = participants.flatMap((participant, index) => participant.timers.map(timer => ({
+        participantId: BigInt(index + 1), timer
+    }))).sort((a, b) => a.participantId === b.participantId
+        ? Buffer.compare(Buffer.from(a.timer.timerId), Buffer.from(b.timer.timerId))
+        : a.participantId < b.participantId ? -1 : 1);
+    if (timers.some((value, index) => index > 0
+        && timers[index - 1].participantId === value.participantId
+        && timers[index - 1].timer.timerId === value.timer.timerId)) {
+        throw new TypeError('Relocation timer ids must be unique per participant.');
+    }
+    const nextOrder = new Map();
+    for (const value of saved) {
+        const current = nextOrder.get(value.participantId) ?? 0n;
+        if (value.order > current)
+            nextOrder.set(value.participantId, value.order);
+    }
+    const pending = timers.flatMap(({ participantId, timer }) => timer.pendingTicks.map(tick => {
+        const current = nextOrder.get(participantId) ?? 0n;
+        const order = tick.order === undefined
+            ? current + 1n
+            : positiveBigInt(tick.order, 'pending timer order');
+        if (order > current)
+            nextOrder.set(participantId, order);
+        return { participantId, order, timerName: timer.timerId, tick };
+    })).sort(compareParticipantOrder);
+    return Buffer.from((0, service_wire_pilot_codec_generated_1.encodeRelocationEnvelopeV1)({
+        relocationHigh: aggregate.high,
+        relocationLow: aggregate.low,
+        object: toGeneratedRelocationObject(root, rootObjectKind),
+        applicationVersion: encodedApplicationVersion,
+        applicationStates,
+        savedWork: saved,
+        timerRegistrations: timers.map(({ participantId, timer }) => ({
+            participantId,
+            name: timer.timerId,
+            handlerType: timer.handlerType,
+            periodMilliseconds: BigInt(positiveInteger(timer.intervalMs, 'timer interval')),
+            overrunPolicy: timerPolicy(timer.overrunPolicy),
+            maxCatchUpTicks: BigInt(positiveInteger(timer.maxCatchUpTicks, 'timer catch-up limit')),
+            stopOnUnhandledException: requireBoolean(timer.stopOnUnhandledException, 'timer stop-on-error flag'),
+            lastCompletedDeliveryIndex: nonNegativeBigInt(timer.deliveryIndex, 'timer delivery index'),
+            lastCompletedScheduledIndex: nonNegativeBigInt(timer.lastScheduledIndex, 'timer scheduled index'),
+            nextScheduledAtUnixMilliseconds: nonNegativeUnixMilliseconds(timer.dueAtUnixMs, 'timer due time')
+        })),
+        pendingTimerTicks: pending.map(value => ({
+            participantId: value.participantId,
+            order: value.order,
+            timerName: value.timerName,
+            deliveryIndex: nonNegativeBigInt(value.tick.deliveryIndex, 'pending timer delivery index'),
+            scheduledIndex: nonNegativeBigInt(value.tick.scheduledIndex, 'pending timer scheduled index'),
+            scheduledAtUnixMilliseconds: nonNegativeUnixMilliseconds(value.tick.scheduledAtUnixMs, 'pending timer scheduled time'),
+            skippedTicks: nonNegativeBigInt(value.tick.skippedTicks, 'pending timer skipped ticks')
+        }))
+    }));
+}
+function decodeServiceRelocationEnvelope(payload, aggregateGeneration) {
+    let generated;
+    try {
+        generated = (0, service_wire_pilot_codec_generated_1.decodeRelocationEnvelopeV1)([payload]);
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : '';
+        if (message === 'object kind') {
+            throw new TypeError('relocation-envelope-v1 root object kind is invalid.', { cause });
+        }
+        if (message === 'relocation envelope trailing') {
+            throw new TypeError('Trailing relocation envelope bytes.', { cause });
+        }
+        throw new TypeError('Invalid relocation envelope.', { cause });
+    }
+    const aggregateId = uuid(generated.relocationHigh, generated.relocationLow);
+    if (aggregateId === undefined)
+        throw new TypeError('Invalid relocation identity.');
+    positiveBigInt(aggregateGeneration, 'aggregate generation');
+    const participants = generated.applicationStates.map((state, index) => {
+        if (state.participantId !== BigInt(index + 1)) {
+            throw new TypeError('Application state participant order is invalid.');
+        }
+        return wireParticipant(state.participantId, state.hasState, Buffer.from(state.payload));
+    });
+    const byId = new Map(participants.map(value => [value.participantId, value]));
+    for (const work of generated.savedWork) {
+        byId.get(work.participantId).queuedMessages.push({
+            sequence: work.order,
+            payload: Buffer.from(work.frozenRecord)
+        });
+    }
+    for (const timer of generated.timerRegistrations) {
+        byId.get(timer.participantId).timers.push({
+            timerId: timer.name,
+            handlerType: timer.handlerType,
+            startedAtUnixMs: 0,
+            dueAtUnixMs: unixMilliseconds(timer.nextScheduledAtUnixMilliseconds),
+            intervalMs: unixMilliseconds(timer.periodMilliseconds),
+            overrunPolicy: timerPolicyName(timer.overrunPolicy),
+            maxCatchUpTicks: unixMilliseconds(timer.maxCatchUpTicks),
+            stopOnUnhandledException: timer.stopOnUnhandledException,
+            deliveryIndex: timer.lastCompletedDeliveryIndex,
+            lastScheduledIndex: timer.lastCompletedScheduledIndex,
+            pendingTicks: []
+        });
+    }
+    for (const tick of generated.pendingTimerTicks) {
+        const timer = byId.get(tick.participantId).timers.find(value => value.timerId === tick.timerName);
+        timer.pendingTicks.push({
+            order: tick.order,
+            deliveryIndex: tick.deliveryIndex,
+            scheduledIndex: tick.scheduledIndex,
+            scheduledAtUnixMs: unixMilliseconds(tick.scheduledAtUnixMilliseconds),
+            skippedTicks: tick.skippedTicks
+        });
+    }
+    const rootParticipant = participants[0];
+    const rootProjection = fromGeneratedRelocationObject(generated.object);
+    return {
+        aggregateId,
+        aggregateGeneration,
+        applicationVersion: generated.applicationVersion,
+        participants: participants.map(value => value === rootParticipant
+            ? { ...value, ...rootProjection }
+            : value),
+        memberships: []
+    };
+}
+function toGeneratedRelocationObject(root, objectKind) {
+    const objectId = root.rootSpotId ?? authorityGlobalId(root.key);
+    const objectGeneration = root.rootSpotGeneration ?? root.objectGeneration;
+    if (objectKind === 'actor') {
+        return {
+            objectKind: 'actor',
+            actorId: objectId,
+            objectGeneration,
+            expectedAuthorityOwnerGeneration: root.rootOwnerGeneration ?? root.authorityOwnerGeneration
+        };
+    }
+    if (objectKind === 'user_spot') {
+        return {
+            objectKind: 'userSpot',
+            spotId: objectId,
+            objectGeneration,
+            expectedAuthorityOwnerGeneration: root.rootOwnerGeneration ?? root.authorityOwnerGeneration
+        };
+    }
+    return {
+        objectKind: 'instanceSpot',
+        instanceType: root.rootStableType ?? root.stableType,
+        spotId: objectId,
+        objectGeneration
+    };
+}
+function fromGeneratedRelocationObject(object) {
+    if (object.objectKind === 'actor') {
+        return {
+            rootSpotId: object.actorId,
+            rootSpotGeneration: object.objectGeneration,
+            rootOwnerGeneration: object.expectedAuthorityOwnerGeneration,
+            rootObjectKind: 'actor'
+        };
+    }
+    if (object.objectKind === 'userSpot') {
+        return {
+            rootSpotId: object.spotId,
+            rootSpotGeneration: object.objectGeneration,
+            rootOwnerGeneration: object.expectedAuthorityOwnerGeneration,
+            rootObjectKind: 'user_spot'
+        };
+    }
+    return {
+        rootSpotId: object.spotId,
+        rootSpotGeneration: object.objectGeneration,
+        rootObjectKind: 'instance_spot',
+        rootStableType: object.instanceType
+    };
+}
+function canonicalParticipants(values) {
+    if (values.length === 0)
+        throw new TypeError('Relocation participant count is outside its bound.');
+    const participants = [...values].sort((a, b) => Buffer.compare(Buffer.from(a.key), Buffer.from(b.key)));
+    if (new Set(participants.map(value => value.key)).size !== participants.length) {
+        throw new TypeError('Relocation participants must have unique keys.');
+    }
+    return participants;
+}
+function authorityGlobalId(key) {
+    try {
+        return (0, authority_key_codec_1.decodeAuthorityKey)({ value: key }).globalId;
+    }
+    catch {
+        const marker = key.indexOf(':');
+        return marker < 0 ? requireText(key, 'participant key') : requireText(key.slice(marker + 1), 'participant key');
+    }
+}
+function relocationId(value) {
+    const hex = value.replaceAll('-', '');
+    return { high: BigInt(`0x${hex.slice(0, 16)}`), low: BigInt(`0x${hex.slice(16)}`) };
+}
+function uuid(high, low) {
+    if (high === 0n && low === 0n)
+        return undefined;
+    const hex = high.toString(16).padStart(16, '0') + low.toString(16).padStart(16, '0');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function compareParticipantOrder(a, b) {
+    return a.participantId === b.participantId
+        ? a.order < b.order ? -1 : a.order > b.order ? 1 : 0
+        : a.participantId < b.participantId ? -1 : 1;
+}
+function timerPolicy(value) {
+    if (value === 'skipLateTicks')
+        return 1;
+    if (value === 'catchUpBounded')
+        return 2;
+    if (value === 'delayNextTick')
+        return 3;
+    throw new TypeError('Timer overrun policy is invalid.');
+}
+function timerPolicyName(value) {
+    if (value === 1)
+        return 'skipLateTicks';
+    if (value === 2)
+        return 'catchUpBounded';
+    if (value === 3)
+        return 'delayNextTick';
+    throw new TypeError('Timer overrun policy is invalid.');
+}
+function nonNegativeUnixMilliseconds(value, label) {
+    const parsed = safeInteger(value, label);
+    if (parsed < 0)
+        throw new TypeError(`${label} must not be negative.`);
+    return BigInt(parsed);
+}
+function unixMilliseconds(value) {
+    if (value > BigInt(Number.MAX_SAFE_INTEGER))
+        throw new TypeError('Unix milliseconds exceed Node safe integer range.');
+    return Number(value);
+}
+function wireParticipant(participantId, applicationStatePresent, applicationState) {
+    return {
+        participantId,
+        key: `wire:${participantId}`,
+        objectKind: 'actor',
+        stableType: 'wire',
+        objectGeneration: 1n,
+        authorityOwnerGeneration: 1n,
+        applicationStatePresent,
+        applicationState,
+        boundSessionState: Buffer.alloc(0),
+        queuedMessages: [],
+        timers: []
+    };
+}
+function objectKind(value) {
+    if (value !== 'actor' && value !== 'user_spot' && value !== 'instance_spot') {
+        throw new TypeError('Relocation object kind is invalid.');
+    }
+    return value;
+}
+function inventoryDigest(participants, memberships = []) {
+    const identities = participants.map(participant => ({
+        key: requireText(participant.key, 'participant key'),
+        objectKind: objectKind(participant.objectKind),
+        stableType: requireText(participant.stableType, 'participant stable type'),
+        objectGeneration: positiveBigInt(participant.objectGeneration, 'object generation').toString(),
+        authorityOwnerGeneration: positiveBigInt(participant.authorityOwnerGeneration, 'authority owner generation').toString()
+    })).sort((left, right) => left.key.localeCompare(right.key));
+    if (new Set(identities.map(({ key }) => key)).size !== identities.length) {
+        throw new TypeError('Relocation participants must have unique keys.');
+    }
+    const canonicalMemberships = encodeMemberships(memberships, participants);
+    return (0, node_crypto_1.createHash)('sha256').update(JSON.stringify({
+        participants: identities,
+        memberships: canonicalMemberships
+    }), 'utf8').digest('hex');
+}
+function encodeAuthorityEnvelope(base, publication) {
+    const checksum = safeInteger(publication.checksumCrc32c, 'relocation checksum');
+    if (checksum < 0 || checksum > 0xffff_ffff) {
+        throw new TypeError('Relocation checksum must be an unsigned 32-bit integer.');
+    }
+    if (!/^[a-f0-9]{64}$/u.test(publication.inventoryDigest)) {
+        throw new TypeError('Relocation inventory digest must be lowercase SHA-256.');
+    }
+    const aggregateGeneration = positiveBigInt(publication.aggregateGeneration, 'aggregate generation');
+    const targetOwnerLeaseGeneration = positiveBigInt(publication.targetOwnerLeaseGeneration, 'target owner lease generation');
+    if (aggregateGeneration > 0x7fffffffffffffffn
+        || targetOwnerLeaseGeneration > 0x7fffffffffffffffn) {
+        throw new TypeError('Relocation publication generations must fit signed 64-bit storage.');
+    }
+    const payload = Buffer.concat([
+        // BinaryWriter.Write(0x5a4c4152u) is little-endian in the .NET reference codec.
+        Buffer.from([0x52, 0x41, 0x4c, 0x5a]),
+        u16le(1),
+        text16le(requireText(publication.reference, 'relocation reference')),
+        u32le(checksum),
+        dotnetGuidBytes(canonicalUuid(publication.aggregateId, 'aggregate id')),
+        u64le(aggregateGeneration),
+        bytes32le(Buffer.from(publication.inventoryDigest, 'hex')),
+        text16le(requireText(publication.targetOwnerId, 'target owner id')),
+        i64le(targetOwnerLeaseGeneration),
+        bytes32le(base)
+    ]);
+    if (payload.byteLength > 1024 * 1024) {
+        throw new TypeError('Location authority relocation payload exceeds 1 MiB.');
+    }
+    return payload;
+}
+function decodeAuthorityEnvelope(payload) {
+    try {
+        const reader = new DotnetBinaryReader(payload);
+        reader.expect(Buffer.from([0x52, 0x41, 0x4c, 0x5a]));
+        if (reader.u16() !== 1)
+            return undefined;
+        const reference = requireText(reader.text16(), 'relocation reference');
+        const checksumCrc32c = reader.u32();
+        const aggregateId = canonicalUuid(canonicalUuidFromDotnetBytes(reader.take(16)), 'aggregate id');
+        const aggregateGeneration = reader.u64();
+        const inventoryDigestBytes = reader.bytes32();
+        const targetOwnerId = requireText(reader.text16(), 'target owner id');
+        const targetOwnerLeaseGeneration = reader.i64();
+        const base = reader.bytes32();
+        if (!reader.done
+            || aggregateGeneration === 0n
+            || aggregateGeneration > 0x7fffffffffffffffn
+            || inventoryDigestBytes.byteLength !== 32
+            || targetOwnerLeaseGeneration <= 0n) {
+            return undefined;
+        }
+        return {
+            base,
+            publication: {
+                reference,
+                checksumCrc32c,
+                aggregateId,
+                aggregateGeneration,
+                inventoryDigest: inventoryDigestBytes.toString('hex'),
+                targetOwnerId,
+                targetOwnerLeaseGeneration
+            }
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function encodeMemberships(memberships, participants) {
+    validateMemberships(memberships, participants);
+    return memberships.map(membership => ({
+        actorKey: requireText(membership.actorKey, 'membership actor key'),
+        spotKey: requireText(membership.spotKey, 'membership spot key'),
+        spotObjectGeneration: positiveBigInt(membership.spotObjectGeneration, 'membership Spot generation').toString(),
+        membershipEpoch: positiveBigInt(membership.membershipEpoch, 'membership epoch').toString()
+    })).sort((left, right) => left.actorKey.localeCompare(right.actorKey));
+}
+function validateMemberships(memberships, participants) {
+    const byKey = new Map(participants.map(participant => [participant.key, participant]));
+    const actorKeys = new Set();
+    for (const membership of memberships) {
+        const actorKey = requireText(membership.actorKey, 'membership actor key');
+        if (actorKeys.has(actorKey)) {
+            throw new TypeError('Relocation membership Actor keys must be unique.');
+        }
+        actorKeys.add(actorKey);
+        const actor = byKey.get(actorKey);
+        if (actor?.objectKind !== 'actor') {
+            throw new TypeError('Relocation membership must reference an Actor participant.');
+        }
+        const spot = byKey.get(requireText(membership.spotKey, 'membership spot key'));
+        if (spot !== undefined
+            && (spot.objectKind !== 'user_spot'
+                || spot.objectGeneration !== positiveBigInt(membership.spotObjectGeneration, 'membership Spot generation'))) {
+            throw new TypeError('Relocation membership Spot fence does not match its participant.');
+        }
+        positiveBigInt(membership.membershipEpoch, 'membership epoch');
+    }
+}
+const CRC32C_TABLE = Uint32Array.from({ length: 256 }, (_, value) => {
+    let crc = value;
+    for (let bit = 0; bit < 8; bit++) {
+        crc = (crc >>> 1) ^ ((crc & 1) === 0 ? 0 : 0x82f6_3b78);
+    }
+    return crc >>> 0;
+});
+function crc32c(payload) {
+    let crc = 0xffff_ffff;
+    for (const byte of payload) {
+        crc = CRC32C_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffff_ffff) >>> 0;
+}
+function requireText(value, label) {
+    if (typeof value !== 'string' || value.length === 0 || value.includes('\0')) {
+        throw new TypeError(`${label} must be non-empty text without NUL.`);
+    }
+    return value;
+}
+function canonicalUuid(value, label) {
+    const text = requireText(value, label);
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u.test(text)
+        || /^0{8}-0{4}-0{4}-0{4}-0{12}$/u.test(text)) {
+        throw new TypeError(`${label} must be a lowercase non-zero 128-bit identity.`);
+    }
+    return text;
+}
+function text16le(value) {
+    const bytes = Buffer.from(value, 'utf8');
+    if (bytes.byteLength < 1 || bytes.byteLength > 0xffff) {
+        throw new TypeError('Relocation text must contain 1..65535 UTF-8 bytes.');
+    }
+    return Buffer.concat([u16le(bytes.byteLength), bytes]);
+}
+function bytes32le(value) {
+    const bytes = Buffer.from(value);
+    if (bytes.byteLength > 1024 * 1024) {
+        throw new TypeError('Relocation byte field exceeds 1 MiB.');
+    }
+    const length = Buffer.alloc(4);
+    length.writeInt32LE(bytes.byteLength);
+    return Buffer.concat([length, bytes]);
+}
+function u16le(value) {
+    const result = Buffer.alloc(2);
+    result.writeUInt16LE(value);
+    return result;
+}
+function u32le(value) {
+    const result = Buffer.alloc(4);
+    result.writeUInt32LE(value);
+    return result;
+}
+function u64le(value) {
+    const result = Buffer.alloc(8);
+    result.writeBigUInt64LE(value);
+    return result;
+}
+function i64le(value) {
+    const result = Buffer.alloc(8);
+    result.writeBigInt64LE(value);
+    return result;
+}
+function dotnetGuidBytes(value) {
+    const canonical = Buffer.from(value.replaceAll('-', ''), 'hex');
+    return Buffer.from([
+        canonical[3], canonical[2], canonical[1], canonical[0],
+        canonical[5], canonical[4],
+        canonical[7], canonical[6],
+        ...canonical.subarray(8)
+    ]);
+}
+function canonicalUuidFromDotnetBytes(value) {
+    const bytes = Buffer.from(value);
+    if (bytes.byteLength !== 16)
+        throw new TypeError('Relocation aggregate id is invalid.');
+    const canonical = Buffer.from([
+        bytes[3], bytes[2], bytes[1], bytes[0],
+        bytes[5], bytes[4],
+        bytes[7], bytes[6],
+        ...bytes.subarray(8)
+    ]).toString('hex');
+    return `${canonical.slice(0, 8)}-${canonical.slice(8, 12)}-${canonical.slice(12, 16)}`
+        + `-${canonical.slice(16, 20)}-${canonical.slice(20)}`;
+}
+class CanonicalReader {
+    bytes;
+    offset = 0;
+    constructor(payload) {
+        this.bytes = Buffer.from(payload);
+    }
+    get done() {
+        return this.offset === this.bytes.byteLength;
+    }
+    expect(expected) {
+        if (!this.take(expected.byteLength).equals(Buffer.from(expected))) {
+            throw new TypeError('Canonical authority magic is invalid.');
+        }
+    }
+    u8() {
+        return this.take(1)[0];
+    }
+    u16() {
+        return this.take(2).readUInt16BE(0);
+    }
+    u32() {
+        return this.take(4).readUInt32BE(0);
+    }
+    u64() {
+        return this.take(8).readBigUInt64BE(0);
+    }
+    i64() {
+        return this.take(8).readBigInt64BE(0);
+    }
+    text8(optional) {
+        const length = this.u8();
+        if (length === 0) {
+            if (optional)
+                return '';
+            throw new TypeError('Canonical authority text is empty.');
+        }
+        return canonicalText(this.take(length));
+    }
+    text16() {
+        const length = this.u16();
+        if (length === 0)
+            throw new TypeError('Canonical authority text is empty.');
+        return canonicalText(this.take(length));
+    }
+    take(length) {
+        if (length < 0 || this.offset + length > this.bytes.byteLength) {
+            throw new TypeError('Canonical authority payload is truncated.');
+        }
+        const result = this.bytes.subarray(this.offset, this.offset + length);
+        this.offset += length;
+        return result;
+    }
+}
+function canonicalText(value) {
+    const bytes = Buffer.from(value);
+    if (bytes.includes(0))
+        throw new TypeError('Canonical authority text contains NUL.');
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+}
+function canonicalText8(value) {
+    const bytes = Buffer.from(requireText(value, 'canonical authority text'), 'utf8');
+    if (bytes.byteLength > 0xff)
+        throw new TypeError('Canonical authority text8 is too long.');
+    return Buffer.concat([Buffer.of(bytes.byteLength), bytes]);
+}
+function canonicalOptionalText8(value) {
+    if (value.length === 0)
+        return Buffer.of(0);
+    return canonicalText8(value);
+}
+function canonicalText16(value) {
+    const bytes = Buffer.from(requireText(value, 'canonical authority text'), 'utf8');
+    if (bytes.byteLength > 4096)
+        throw new TypeError('Canonical authority text16 is too long.');
+    return Buffer.concat([canonicalU16(bytes.byteLength), bytes]);
+}
+function canonicalU16(value) {
+    const result = Buffer.alloc(2);
+    result.writeUInt16BE(value);
+    return result;
+}
+function canonicalU32(value) {
+    if (!Number.isInteger(value) || value < 0 || value > 0xffff_ffff) {
+        throw new TypeError('Canonical authority u32 is invalid.');
+    }
+    const result = Buffer.alloc(4);
+    result.writeUInt32BE(value);
+    return result;
+}
+function canonicalU64(value) {
+    if (value < 0n || value > 0xffffffffffffffffn) {
+        throw new TypeError('Canonical authority u64 is invalid.');
+    }
+    const result = Buffer.alloc(8);
+    result.writeBigUInt64BE(value);
+    return result;
+}
+function canonicalOrdinal(value, name) {
+    const ordinal = nonNegativeBigInt(value, name);
+    if (ordinal > 0x7fffffffffffffffn) {
+        throw new TypeError(`${name} exceeds the ordinal range.`);
+    }
+    return ordinal;
+}
+function canonicalNonZeroOrdinal(value, name) {
+    const ordinal = canonicalOrdinal(value, name);
+    if (ordinal === 0n)
+        throw new TypeError(`${name} must be positive.`);
+    return ordinal;
+}
+function canonicalI64(value) {
+    if (value < 0n || value > 0x7fffffffffffffffn) {
+        throw new TypeError('Canonical authority i64 is invalid.');
+    }
+    const result = Buffer.alloc(8);
+    result.writeBigInt64BE(value);
+    return result;
+}
+class DotnetBinaryReader {
+    bytes;
+    offset = 0;
+    constructor(payload) {
+        this.bytes = Buffer.from(payload);
+        if (this.bytes.byteLength > 1024 * 1024) {
+            throw new TypeError('Location authority relocation payload exceeds 1 MiB.');
+        }
+    }
+    get done() {
+        return this.offset === this.bytes.byteLength;
+    }
+    expect(expected) {
+        if (!this.take(expected.byteLength).equals(Buffer.from(expected))) {
+            throw new TypeError('Location authority relocation magic is invalid.');
+        }
+    }
+    u16() {
+        return this.take(2).readUInt16LE(0);
+    }
+    u32() {
+        return this.take(4).readUInt32LE(0);
+    }
+    u64() {
+        return this.take(8).readBigUInt64LE(0);
+    }
+    i64() {
+        return this.take(8).readBigInt64LE(0);
+    }
+    text16() {
+        const length = this.u16();
+        if (length === 0)
+            throw new TypeError('Location authority relocation text is empty.');
+        return this.take(length).toString('utf8');
+    }
+    bytes32() {
+        const length = this.take(4).readInt32LE(0);
+        if (length < 0 || length > 1024 * 1024) {
+            throw new TypeError('Location authority relocation byte field is invalid.');
+        }
+        return Buffer.from(this.take(length));
+    }
+    take(length) {
+        if (length < 0 || this.offset + length > this.bytes.byteLength) {
+            throw new TypeError('Location authority relocation payload is truncated.');
+        }
+        const result = this.bytes.subarray(this.offset, this.offset + length);
+        this.offset += length;
+        return result;
+    }
+}
+function positiveBigInt(value, label) {
+    let parsed;
+    try {
+        parsed = typeof value === 'bigint' ? value : BigInt(requireText(value, label));
+    }
+    catch {
+        throw new TypeError(`${label} must be a positive integer.`);
+    }
+    if (parsed <= 0n)
+        throw new TypeError(`${label} must be a positive integer.`);
+    return parsed;
+}
+function nonNegativeBigInt(value, label) {
+    let parsed;
+    try {
+        parsed = typeof value === 'bigint' ? value : BigInt(requireText(value, label));
+    }
+    catch {
+        throw new TypeError(`${label} must be a non-negative integer.`);
+    }
+    if (parsed < 0n)
+        throw new TypeError(`${label} must be a non-negative integer.`);
+    return parsed;
+}
+function safeInteger(value, label) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value)) {
+        throw new TypeError(`${label} must be a safe integer.`);
+    }
+    return value;
+}
+function positiveInteger(value, label) {
+    const parsed = safeInteger(value, label);
+    if (parsed <= 0)
+        throw new TypeError(`${label} must be positive.`);
+    return parsed;
+}
+function requireBoolean(value, label) {
+    if (typeof value !== 'boolean')
+        throw new TypeError(`${label} must be boolean.`);
+    return value;
+}