@zlink-systems/framework 0.24.0 → 0.26.0

package/dist/runtime/actors/deferred-join-accepted-journal.js

@@ -1,992 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZLinkDeferredJoinAcceptedJournal = void 0;
-exports.isDeferredJoinAcceptedRootPublication = isDeferredJoinAcceptedRootPublication;
-const node_crypto_1 = require("node:crypto");
-const contracts_1 = require("../../contracts");
-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 routing_id_1 = require("../routing-id");
-const actor_authority_publication_1 = require("./actor-authority-publication");
-const actor_authority_payload_codec_1 = require("./actor-authority-payload-codec");
-const runtime_message_1 = require("../backend/runtime-message");
-const payload_codec_1 = require("../messaging/payload-codec");
-const service_wire_pilot_codec_generated_1 = require("../protocol/service_wire_pilot_codec.generated");
-const RETENTION_MS = 24 * 60 * 60 * 1_000;
-const ROOT_VERSION = 2;
-const ROOT_MAGIC = Buffer.from('ZLJR');
-const JOURNAL_INVENTORY_DOMAIN = Buffer.from('zlink-node-deferred-join-authority-v1\0', 'utf8');
-/** Identifies whether an authority slot points at a deferred Join journal root. */
-async function isDeferredJoinAcceptedRootPublication(relocation, reference, checksumCrc32c, expected, signal) {
-    if (expected.objectKind !== 'actor' || expected.aggregateGeneration === 0n)
-        return false;
-    const read = await relocation.read({ value: reference }, signal);
-    if (read.kind !== 'found' || (0, service_relocation_runtime_1.crc32c)(read.bytes) !== checksumCrc32c)
-        return false;
-    if (hasJournalRootMagic(read.bytes)) {
-        try {
-            const root = decodeRoot(read.bytes);
-            return (expected.aggregateId === operationAggregateId(root.operationId) &&
-                expected.aggregateGeneration === root.actor.objectGeneration &&
-                expected.authorityKey === (0, authority_key_codec_1.encodeAuthorityKey)('actor', root.actor.actorId).value &&
-                expected.objectGeneration === root.actor.objectGeneration);
-        }
-        catch {
-            return false;
-        }
-    }
-    const root = await readCanonicalDeferredJoinRoot(relocation, read.bytes, signal);
-    return (root !== undefined &&
-        root.identity.aggregateId === expected.aggregateId &&
-        root.identity.aggregateGeneration === expected.aggregateGeneration &&
-        root.identity.authorityKey === expected.authorityKey &&
-        root.identity.objectKind === expected.objectKind &&
-        root.identity.objectGeneration === expected.objectGeneration);
-}
-/**
- * Keeps a cross-node Accepted Join completion under the Actor authority.
- * Every cursor transition writes and verifies a new immutable root before the
- * authority CAS. A failed callback leaves the committed root available for the
- * next target Actor mailbox retry.
- */
-class ZLinkDeferredJoinAcceptedJournal {
-    authority;
-    relocation;
-    messageSerializers;
-    constructor(authority, relocation, messageSerializers) {
-        this.authority = authority;
-        this.relocation = relocation;
-        this.messageSerializers = messageSerializers;
-    }
-    async prepare(actorId, operationId, actor, rawReply, replyContentType, signal, canonicalInventoryDigest) {
-        validateIdentity(actorId, operationId, actor);
-        if (replyContentType !== undefined && replyContentType.length === 0) {
-            throw new TypeError('Deferred Join reply content type must be non-empty.');
-        }
-        signal?.throwIfAborted();
-        const key = (0, authority_key_codec_1.encodeAuthorityKey)('actor', actorId);
-        const read = await this.authority.readAuthority(key, signal);
-        if (read.kind !== 'snapshot') {
-            throw new Error(`Actor '${actorId}' has no authority for durable Join completion.`);
-        }
-        requireAuthorityActor(read.payload, actor);
-        const existing = await this.readPublished(read, signal);
-        if (existing !== undefined) {
-            if (isSameOperation(existing, operationId, actor)) {
-                return existing;
-            }
-            if (existing.cursor !== 'delivered') {
-                requireSameOperation(existing, operationId, actor);
-            }
-        }
-        const rootValue = {
-            operationId,
-            actor,
-            rawReply: Buffer.from(rawReply),
-            ...(replyContentType === undefined ? {} : { replyContentType }),
-            cursor: 'prepared'
-        };
-        const initialPublication = decodeAuthorityPublication(read.payload);
-        const initialCanonicalIdentity = (0, service_relocation_runtime_1.serviceRelocationAuthoritySlotIdentity)(read.payload);
-        const canonicalPublication = initialPublication?.canonical === true ? initialPublication : undefined;
-        const root = canonicalPublication !== undefined &&
-            (canonicalInventoryDigest !== undefined ||
-                !canonicalPublication.reference.value.startsWith('zlink-direct:'))
-            ? await this.storeCanonicalRoot(rootValue, read, canonicalPublication, signal, canonicalInventoryDigest)
-            : await this.storeRoot(rootValue, signal);
-        if (initialCanonicalIdentity !== undefined && canonicalInventoryDigest !== undefined) {
-            return {
-                ...root,
-                authority: read
-            };
-        }
-        let expected = read;
-        for (let attempt = 0; attempt < 3; attempt++) {
-            const currentPublication = decodeAuthorityPublication(expected.payload);
-            const canonicalIdentity = (0, service_relocation_runtime_1.serviceRelocationAuthoritySlotIdentity)(expected.payload);
-            const publication = {
-                applicationPayload: Buffer.from(currentPublication?.applicationPayload ??
-                    (0, service_relocation_runtime_1.serviceRelocationAuthorityApplicationPayload)(expected.payload)),
-                reference: root.reference,
-                checksumCrc32c: root.checksumCrc32c,
-                aggregateId: canonicalIdentity !== undefined
-                    ? canonicalIdentity.aggregateId
-                    : operationAggregateId(operationId),
-                aggregateGeneration: canonicalIdentity === undefined
-                    ? actor.objectGeneration
-                    : requireCanonicalAggregateGeneration(canonicalIdentity.aggregateGeneration),
-                targetOwnerId: expected.ownerId,
-                targetOwnerLeaseGeneration: expected.ownerLeaseGeneration,
-                ...(currentPublication?.canonicalPublication === undefined
-                    ? {}
-                    : { canonicalPublication: currentPublication.canonicalPublication })
-            };
-            const result = await this.authority.compareExchangeAuthority(key, expected.storeVersion, {
-                kind: 'put',
-                generationTransition: 'preserve',
-                payload: currentPublication === undefined && canonicalIdentity !== undefined
-                    ? new service_relocation_runtime_1.ServiceRelocationAuthorityPayloadCodec().publish(expected.payload, toServiceRelocationPublication(publication))
-                    : replaceDeferredJoinAuthorityPublication(expected.payload, encodeAuthorityPublication(publication))
-            }, signal);
-            if (result.kind === 'stored') {
-                if (existing !== undefined) {
-                    await this.deleteBestEffort(existing.reference);
-                }
-                return {
-                    ...root,
-                    authority: storedSnapshot(result)
-                };
-            }
-            if (result.kind !== 'conflict' || result.current.kind !== 'snapshot')
-                break;
-            const current = await this.readPublished(result.current, signal);
-            if (current !== undefined) {
-                await this.deleteBestEffort(root.reference);
-                requireSameOperation(current, operationId, actor);
-                return current;
-            }
-            requireAuthorityActor(result.current.payload, actor);
-            expected = result.current;
-        }
-        await this.deleteBestEffort(root.reference);
-        throw new Error(`Actor '${actorId}' authority rejected Join completion publication.`);
-    }
-    async recover(actorId, signal) {
-        const read = await this.authority.readAuthority((0, authority_key_codec_1.encodeAuthorityKey)('actor', actorId), signal);
-        return read.kind === 'snapshot' ? await this.readPublished(read, signal) : undefined;
-    }
-    markCommitted(root, actor, signal) {
-        if (actor !== undefined)
-            requireSameActor(root, actor);
-        return this.moveCursor(root, 'committed', actor, signal);
-    }
-    markDelivered(root, signal) {
-        return this.moveCursor(root, 'delivered', undefined, signal);
-    }
-    async discardPrepared(root, signal) {
-        const key = (0, authority_key_codec_1.encodeAuthorityKey)('actor', root.actor.actorId);
-        for (let attempt = 0; attempt < 3; attempt++) {
-            const read = await this.authority.readAuthority(key, signal);
-            if (read.kind !== 'snapshot')
-                return;
-            const current = await this.readPublished(read, signal);
-            if (current === undefined)
-                return;
-            requireSameOperation(current, root.operationId, root.actor);
-            if (current.cursor !== 'prepared')
-                return;
-            const publication = decodeAuthorityPublication(read.payload);
-            if (publication === undefined)
-                return;
-            const result = await this.authority.compareExchangeAuthority(key, read.storeVersion, {
-                kind: 'put',
-                generationTransition: 'preserve',
-                payload: replaceDeferredJoinAuthorityPublication(read.payload, publication.applicationPayload)
-            }, signal);
-            if (result.kind === 'stored') {
-                await this.deleteBestEffort(current.reference);
-                return;
-            }
-        }
-        throw new Error(`Actor '${root.actor.actorId}' deferred Join preparation could not be discarded.`);
-    }
-    async deliver(root, actor, actorRef, submitMailbox, signal) {
-        requireSameActor(root, actorRef);
-        return await submitMailbox(async () => {
-            const current = await this.recover(actorRef.actorId, signal);
-            if (current === undefined) {
-                if (root.cursor === 'delivered')
-                    return root;
-                throw new Error(`Actor '${actorRef.actorId}' lost its deferred Join completion root.`);
-            }
-            requireSameOperation(current, root.operationId, actorRef);
-            if (current.cursor === 'delivered') {
-                await this.releaseDelivered(current, signal);
-                return current;
-            }
-            if (current.cursor !== 'committed') {
-                throw new Error(`Actor '${actorRef.actorId}' Join completion is not committed.`);
-            }
-            const completion = {
-                status: 'accepted',
-                operationId: current.operationId,
-                actor: current.actor,
-                reply: current.rawReply.byteLength === 0
-                    ? undefined
-                    : current.replyContentType === undefined
-                        ? contracts_1.ZLinkMessage.fromEncoded(contracts_1.ZLinkEncodedPayload.from(current.rawReply))
-                        : (0, payload_codec_1.wrapFrameworkPayloadMessage)(runtime_message_1.ZLinkBufferMessage.from(current.rawReply), this.messageSerializers, current.replyContentType, undefined, 'reply')
-            };
-            await actor.onJoinCompleted?.(completion);
-            let delivered = current;
-            for (let attempt = 0; attempt < 3; attempt++) {
-                delivered = await this.markDelivered(delivered, signal);
-                if (delivered.cursor === 'delivered') {
-                    await this.releaseDelivered(delivered, signal);
-                    return delivered;
-                }
-            }
-            throw new Error(`Actor '${actorRef.actorId}' Join completion callback ran but its Delivered cursor could not be stored.`);
-        });
-    }
-    async releaseDelivered(root, signal) {
-        const key = (0, authority_key_codec_1.encodeAuthorityKey)('actor', root.actor.actorId);
-        for (let attempt = 0; attempt < 3; attempt++) {
-            const read = await this.authority.readAuthority(key, signal);
-            if (read.kind !== 'snapshot')
-                return;
-            const current = await this.readPublished(read, signal);
-            if (current === undefined)
-                return;
-            requireSameOperation(current, root.operationId, root.actor);
-            if (current.cursor !== 'delivered') {
-                throw new Error(`Actor '${root.actor.actorId}' Join completion root is not Delivered.`);
-            }
-            const publication = decodeAuthorityPublication(read.payload);
-            if (publication === undefined)
-                return;
-            const result = await this.authority.compareExchangeAuthority(key, read.storeVersion, {
-                kind: 'put',
-                generationTransition: 'preserve',
-                payload: replaceDeferredJoinAuthorityPublication(read.payload, publication.applicationPayload)
-            }, signal);
-            if (result.kind === 'stored') {
-                await this.deleteBestEffort(current.reference);
-                return;
-            }
-        }
-        throw new Error(`Actor '${root.actor.actorId}' Delivered Join completion could not be released.`);
-    }
-    async moveCursor(root, next, actor, signal) {
-        const currentIndex = cursorIndex(root.cursor);
-        const nextIndex = cursorIndex(next);
-        if (nextIndex < currentIndex || nextIndex > currentIndex + 1) {
-            throw new Error('Deferred Join completion cursor transition is invalid.');
-        }
-        if (next === root.cursor)
-            return root;
-        const key = (0, authority_key_codec_1.encodeAuthorityKey)('actor', root.actor.actorId);
-        const read = await this.authority.readAuthority(key, signal);
-        if (read.kind !== 'snapshot') {
-            throw new Error(`Actor '${root.actor.actorId}' authority disappeared during Join completion.`);
-        }
-        let current = await this.readPublished(read, signal);
-        if (current === undefined) {
-            const retainedRoot = await this.relocation.read(root.reference, signal);
-            if (retainedRoot.kind === 'found' && (0, service_relocation_runtime_1.crc32c)(retainedRoot.bytes) === root.checksumCrc32c) {
-                const retained = hasJournalRootMagic(retainedRoot.bytes)
-                    ? decodeRoot(retainedRoot.bytes)
-                    : (await readCanonicalDeferredJoinRoot(this.relocation, retainedRoot.bytes, signal))
-                        ?.completion;
-                if (retained?.cursor === 'delivered' &&
-                    isSameOperation({ ...root, ...retained }, root.operationId, root.actor)) {
-                    current = {
-                        authority: read,
-                        reference: root.reference,
-                        checksumCrc32c: root.checksumCrc32c,
-                        ...retained
-                    };
-                }
-            }
-            if (current === undefined &&
-                next === 'committed' &&
-                actor !== undefined &&
-                authorityMatchesActor(read.payload, actor)) {
-                throw new contracts_1.ZLinkFrameworkException(contracts_1.ZLinkFrameworkErrorKind.Unavailable, `Actor '${root.actor.actorId}' Join completion delivery is indeterminate: ` +
-                    'the authority no longer references the operation and no matching retained root exists.');
-            }
-            if (current === undefined) {
-                throw new Error(`Actor '${root.actor.actorId}' no longer references its Join completion root.`);
-            }
-        }
-        requireSameOperation(current, root.operationId, root.actor);
-        if (cursorIndex(current.cursor) >= nextIndex)
-            return current;
-        const replacement = await this.storeRoot({
-            operationId: current.operationId,
-            actor: actor ?? current.actor,
-            rawReply: current.rawReply,
-            ...(current.replyContentType === undefined
-                ? {}
-                : { replyContentType: current.replyContentType }),
-            cursor: next
-        }, signal);
-        const publication = decodeAuthorityPublication(read.payload);
-        if (publication === undefined) {
-            await this.deleteBestEffort(replacement.reference);
-            throw new Error('Actor authority lost its deferred Join publication.');
-        }
-        const identity = (0, actor_authority_publication_1.decodeRelocatingActorAuthorityIdentity)(publication.applicationPayload, read.objectGeneration);
-        if (identity === undefined) {
-            await this.deleteBestEffort(replacement.reference);
-            throw new Error('Actor authority identity is invalid.');
-        }
-        const result = await this.authority.compareExchangeAuthority(key, read.storeVersion, {
-            kind: 'put',
-            generationTransition: 'preserve',
-            payload: replaceDeferredJoinAuthorityPublication(read.payload, encodeAuthorityPublication({
-                ...publication,
-                applicationPayload: actor === undefined
-                    ? publication.applicationPayload
-                    : (0, actor_authority_payload_codec_1.replaceActorRelocationAuthorityApplicationPayload)(publication.applicationPayload, (0, actor_authority_publication_1.encodeActorAuthorityIdentity)({ ...identity, actor })),
-                reference: replacement.reference,
-                checksumCrc32c: replacement.checksumCrc32c
-            }))
-        }, signal);
-        if (result.kind !== 'stored') {
-            await this.deleteBestEffort(replacement.reference);
-            const recovered = await this.recover(root.actor.actorId, signal);
-            if (recovered === undefined) {
-                throw new Error('Deferred Join cursor CAS conflicted without a recoverable root.');
-            }
-            requireSameOperation(recovered, root.operationId, root.actor);
-            return recovered;
-        }
-        await this.deleteBestEffort(current.reference);
-        return {
-            ...replacement,
-            authority: storedSnapshot(result)
-        };
-    }
-    async readPublished(authority, signal) {
-        const publication = decodeAuthorityPublication(authority.payload);
-        if (publication === undefined)
-            return undefined;
-        // Preparing has no relocation root, while Captured still names the
-        // source-memory direct-transfer payload. Neither pre-target-publication
-        // phase can contain a Relocation Store backed deferred Join root.
-        const canonicalPhase = publication.canonicalPublication?.canonicalPhase;
-        if (canonicalPhase === 1 || canonicalPhase === 2)
-            return undefined;
-        const read = await this.relocation.read(publication.reference, signal);
-        if (read.kind !== 'found' &&
-            publication.canonical === true &&
-            publication.reference.value.startsWith('zlink-direct:')) {
-            return undefined;
-        }
-        if (read.kind !== 'found' || (0, service_relocation_runtime_1.crc32c)(read.bytes) !== publication.checksumCrc32c) {
-            throw new Error('Published deferred Join completion root is missing or corrupt.');
-        }
-        if (publication.canonical === true && !hasJournalRootMagic(read.bytes)) {
-            const root = await readCanonicalDeferredJoinRoot(this.relocation, read.bytes, signal);
-            if (root === undefined) {
-                // A canonical relocation root and the post-commit Join journal share
-                // the embedded slot. A root without a completion remains Host-owned.
-                return undefined;
-            }
-            if (root.identity.aggregateId !== publication.aggregateId ||
-                root.identity.aggregateGeneration !== publication.aggregateGeneration ||
-                root.identity.objectGeneration !== authority.objectGeneration) {
-                throw new Error('Published deferred Join completion root identity does not match its authority slot.');
-            }
-            return {
-                authority,
-                reference: publication.reference,
-                checksumCrc32c: publication.checksumCrc32c,
-                ...root.completion
-            };
-        }
-        return {
-            authority,
-            reference: publication.reference,
-            checksumCrc32c: publication.checksumCrc32c,
-            ...decodeRoot(read.bytes)
-        };
-    }
-    async storeRoot(value, signal) {
-        const payload = encodeRoot(value);
-        const checksumCrc32c = (0, service_relocation_runtime_1.crc32c)(payload);
-        const stored = await (0, relocation_blob_1.putNewRelocationBlob)(this.relocation, payload, RETENTION_MS, signal);
-        if (stored.expiresAt.getTime() <= stored.storeNow.getTime()) {
-            await this.deleteBestEffort(stored.reference);
-            throw new Error('Relocation Store returned an invalid deferred Join root receipt.');
-        }
-        const read = await this.relocation.read(stored.reference, signal);
-        if (read.kind !== 'found' || !Buffer.from(read.bytes).equals(payload)) {
-            await this.deleteBestEffort(stored.reference);
-            throw new Error('Relocation Store failed deferred Join root verification.');
-        }
-        return {
-            ...value,
-            rawReply: Buffer.from(value.rawReply),
-            reference: stored.reference,
-            checksumCrc32c
-        };
-    }
-    async storeCanonicalRoot(value, authority, publication, signal, canonicalInventoryDigest) {
-        let inventory;
-        if (canonicalInventoryDigest !== undefined) {
-            if (!/^[0-9a-f]{64}$/u.test(canonicalInventoryDigest)) {
-                throw new Error('Canonical relocation inventory digest is invalid.');
-            }
-            inventory = Buffer.from(canonicalInventoryDigest, 'hex');
-        }
-        else {
-            const current = await this.relocation.read(publication.reference, signal);
-            if (current.kind !== 'found' || (0, service_relocation_runtime_1.crc32c)(current.bytes) !== publication.checksumCrc32c) {
-                throw new Error('Canonical relocation manifest is missing or corrupt.');
-            }
-            inventory = decodeCanonicalTreeManifest(current.bytes).inventoryDigest;
-        }
-        const logicalRoot = encodeCanonicalDeferredJoinRoot(value, authority, publication, inventory);
-        const stored = await storeCanonicalTree(this.relocation, logicalRoot, inventory, signal);
-        return {
-            ...value,
-            rawReply: Buffer.from(value.rawReply),
-            reference: stored.reference,
-            checksumCrc32c: stored.checksumCrc32c
-        };
-    }
-    async deleteBestEffort(reference) {
-        try {
-            await this.relocation.delete(reference);
-        }
-        catch {
-            // Fixed retention remains the orphan cleanup boundary.
-        }
-    }
-}
-exports.ZLinkDeferredJoinAcceptedJournal = ZLinkDeferredJoinAcceptedJournal;
-function requireAuthorityActor(payload, actor) {
-    if (!authorityMatchesActor(payload, actor)) {
-        throw new Error(`Actor '${actor.actorId}' authority fence does not match its ActorRef.`);
-    }
-}
-function authorityMatchesActor(payload, actor) {
-    const publication = decodeAuthorityPublication(payload);
-    const applications = publication === undefined
-        ? [(0, service_relocation_runtime_1.serviceRelocationAuthorityApplicationPayload)(payload)]
-        : [publication.applicationPayload, (0, service_relocation_runtime_1.serviceRelocationAuthorityApplicationPayload)(payload)];
-    return applications.some((application) => {
-        const identity = (0, actor_authority_publication_1.decodeRelocatingActorAuthorityIdentity)(application, actor.objectGeneration);
-        return (identity !== undefined &&
-            identity.actor.actorId === actor.actorId &&
-            identity.actor.objectGeneration === actor.objectGeneration &&
-            (0, routing_id_1.routingIdWireHex)(identity.actor.nodeRid) === (0, routing_id_1.routingIdWireHex)(actor.nodeRid));
-    });
-}
-function encodeRoot(value) {
-    const nodeRidHex = (0, routing_id_1.routingIdWireHex)(value.actor.nodeRid);
-    const encoded = Buffer.concat([
-        ROOT_MAGIC,
-        Buffer.from(JSON.stringify({
-            version: ROOT_VERSION,
-            operationHigh: value.operationId.high.toString(),
-            operationLow: value.operationId.low.toString(),
-            actorId: value.actor.actorId,
-            actorGeneration: value.actor.objectGeneration.toString(),
-            actorMeshName: value.actor.meshName,
-            actorNodeRid: String(value.actor.nodeRid),
-            actorNodeRidHex: nodeRidHex,
-            rawReply: Buffer.from(value.rawReply).toString('base64'),
-            ...(value.replyContentType === undefined
-                ? {}
-                : { replyContentType: value.replyContentType }),
-            cursor: value.cursor
-        }), 'utf8')
-    ]);
-    return encoded;
-}
-function decodeRoot(payload) {
-    if (payload.byteLength === 0) {
-        throw new Error('Deferred Join completion root is empty.');
-    }
-    const bytes = Buffer.from(payload);
-    const encoded = hasJournalRootMagic(bytes) ? bytes.subarray(ROOT_MAGIC.byteLength) : bytes;
-    const value = JSON.parse(encoded.toString('utf8'));
-    if (value.version !== ROOT_VERSION ||
-        typeof value.operationHigh !== 'string' ||
-        typeof value.operationLow !== 'string' ||
-        typeof value.actorId !== 'string' ||
-        typeof value.actorGeneration !== 'string' ||
-        typeof value.actorMeshName !== 'string' ||
-        typeof value.actorNodeRid !== 'string' ||
-        typeof value.rawReply !== 'string' ||
-        (value.replyContentType !== undefined &&
-            (typeof value.replyContentType !== 'string' || value.replyContentType.length === 0)) ||
-        !isCursor(value.cursor)) {
-        throw new Error('Deferred Join completion root is invalid.');
-    }
-    const rawReply = Buffer.from(value.rawReply, 'base64');
-    if (rawReply.toString('base64') !== value.rawReply) {
-        throw new Error('Deferred Join completion reply is not canonical base64.');
-    }
-    const actorGeneration = BigInt(value.actorGeneration);
-    const operationId = {
-        high: BigInt(value.operationHigh),
-        low: BigInt(value.operationLow)
-    };
-    const actor = {
-        actorId: value.actorId,
-        objectGeneration: actorGeneration,
-        meshName: value.actorMeshName,
-        nodeRid: (0, routing_id_1.decodeRoutingId)(value.actorNodeRid, typeof value.actorNodeRidHex === 'string' ? value.actorNodeRidHex : undefined)
-    };
-    validateIdentity(value.actorId, operationId, actor);
-    return {
-        operationId,
-        actor,
-        rawReply,
-        ...(typeof value.replyContentType === 'string'
-            ? { replyContentType: value.replyContentType }
-            : {}),
-        cursor: value.cursor
-    };
-}
-function encodeAuthorityPublication(value) {
-    return Buffer.from(new service_relocation_runtime_1.ServiceRelocationAuthorityPayloadCodec().publish(value.applicationPayload, toServiceRelocationPublication(value)));
-}
-function toServiceRelocationPublication(value) {
-    return {
-        ...value.canonicalPublication,
-        reference: value.reference.value,
-        checksumCrc32c: value.checksumCrc32c,
-        aggregateId: value.aggregateId,
-        aggregateGeneration: value.aggregateGeneration,
-        inventoryDigest: journalInventoryDigest(value.applicationPayload),
-        targetOwnerId: value.targetOwnerId,
-        targetOwnerLeaseGeneration: value.targetOwnerLeaseGeneration
-    };
-}
-function decodeAuthorityPublication(payload) {
-    const outerApplication = (0, service_relocation_runtime_1.serviceRelocationAuthorityApplicationPayload)(payload);
-    const candidates = Buffer.from(outerApplication).equals(Buffer.from(payload))
-        ? [Buffer.from(payload)]
-        : [Buffer.from(outerApplication), Buffer.from(payload)];
-    for (const candidate of candidates) {
-        const publication = decodeDirectAuthorityPublication(candidate);
-        if (publication !== undefined)
-            return publication;
-    }
-    return undefined;
-}
-function replaceDeferredJoinAuthorityPublication(payload, replacement) {
-    const codec = new service_relocation_runtime_1.ServiceRelocationAuthorityPayloadCodec();
-    const currentPublication = codec.read(payload);
-    const replacementPublication = codec.read(replacement);
-    if (currentPublication?.canonical === true || replacementPublication?.canonical === true) {
-        // Canonical authority has exactly one embedded relocation slot. A journal
-        // cursor replaces that slot atomically; it must never be wrapped or nested
-        // under an older ZLAR/application layer.
-        return Buffer.from(replacement);
-    }
-    const outerApplication = (0, service_relocation_runtime_1.serviceRelocationAuthorityApplicationPayload)(payload);
-    if (!Buffer.from(outerApplication).equals(Buffer.from(payload)) &&
-        decodeDirectAuthorityPublication(outerApplication) !== undefined) {
-        return (0, service_relocation_runtime_1.replaceServiceRelocationAuthorityApplicationPayload)(payload, replacement);
-    }
-    return decodeDirectAuthorityPublication(payload) === undefined
-        ? (0, service_relocation_runtime_1.replaceServiceRelocationAuthorityApplicationPayload)(payload, replacement)
-        : Buffer.from(replacement);
-}
-function decodeDirectAuthorityPublication(payload) {
-    const publication = new service_relocation_runtime_1.ServiceRelocationAuthorityPayloadCodec().read(payload);
-    if (publication === undefined)
-        return undefined;
-    const applicationPayload = (0, service_relocation_runtime_1.serviceRelocationAuthorityApplicationPayload)(payload);
-    return publication.canonical === true ||
-        publication.inventoryDigest === journalInventoryDigest(applicationPayload)
-        ? deferredJoinPublication(applicationPayload, publication)
-        : undefined;
-}
-function deferredJoinPublication(applicationPayload, publication) {
-    return {
-        applicationPayload,
-        reference: { value: publication.reference },
-        checksumCrc32c: publication.checksumCrc32c,
-        aggregateId: publication.aggregateId,
-        aggregateGeneration: publication.aggregateGeneration,
-        targetOwnerId: publication.targetOwnerId,
-        targetOwnerLeaseGeneration: publication.targetOwnerLeaseGeneration,
-        canonical: publication.canonical,
-        ...(publication.canonical === true ? { canonicalPublication: publication } : {})
-    };
-}
-function hasJournalRootMagic(payload) {
-    const bytes = Buffer.from(payload);
-    return (bytes.byteLength >= ROOT_MAGIC.byteLength &&
-        bytes.subarray(0, ROOT_MAGIC.byteLength).equals(ROOT_MAGIC));
-}
-function journalInventoryDigest(applicationPayload) {
-    return (0, node_crypto_1.createHash)('sha256')
-        .update(JOURNAL_INVENTORY_DOMAIN)
-        .update(applicationPayload)
-        .digest('hex');
-}
-function operationAggregateId(operationId) {
-    const encoded = [operationId.high, operationId.low]
-        .map((value) => BigInt.asUintN(64, value).toString(16).padStart(16, '0'))
-        .join('');
-    return (`${encoded.slice(0, 8)}-${encoded.slice(8, 12)}-${encoded.slice(12, 16)}` +
-        `-${encoded.slice(16, 20)}-${encoded.slice(20)}`);
-}
-function requireCanonicalAggregateGeneration(value) {
-    if (value === 0n) {
-        throw new contracts_1.ZLinkFrameworkException(contracts_1.ZLinkFrameworkErrorKind.DataLost, 'Canonical relocation slot has no aggregate generation.');
-    }
-    return value;
-}
-function decodeCanonicalTreeManifest(payload) {
-    const generated = (0, service_wire_pilot_codec_generated_1.decodeRelocationManifestV1)(payload);
-    const chunks = generated.chunks.map((chunk, index) => {
-        if (chunk.order !== index) {
-            throw new Error('Canonical relocation chunk identity is invalid.');
-        }
-        return {
-            order: chunk.order,
-            reference: { value: chunk.reference },
-            length: chunk.length,
-            checksumCrc32c: chunk.checksumCrc32c
-        };
-    });
-    if (chunks.length === 0) {
-        throw new Error('Canonical relocation chunk count is invalid.');
-    }
-    if (chunks.reduce((total, value) => total + value.length, 0n) !== generated.totalLength) {
-        throw new Error('Canonical relocation manifest length is invalid.');
-    }
-    return {
-        inventoryDigest: Buffer.from(generated.inventoryDigestSha256),
-        logicalLength: generated.totalLength,
-        logicalChecksumCrc32c: generated.totalChecksumCrc32c,
-        chunks
-    };
-}
-async function storeCanonicalTree(store, logicalRoot, inventoryDigest, signal) {
-    const logical = Buffer.from(logicalRoot);
-    const logicalChecksumCrc32c = (0, service_relocation_runtime_1.crc32c)(logical);
-    const chunk = Buffer.from((0, service_wire_pilot_codec_generated_1.encodeRelocationDataChunkV1)({
-        order: 0,
-        data: logical
-    }));
-    const storedChunk = await putAndVerifyCanonicalBlob(store, chunk, signal);
-    const manifest = Buffer.from((0, service_wire_pilot_codec_generated_1.encodeRelocationManifestV1)({
-        logicalFormatVersion: 1,
-        totalLength: BigInt(logical.byteLength),
-        totalChecksumCrc32c: logicalChecksumCrc32c,
-        inventoryDigestSha256: Buffer.from(inventoryDigest),
-        chunks: [
-            {
-                order: 0,
-                reference: storedChunk.reference.value,
-                length: BigInt(logical.byteLength),
-                checksumCrc32c: logicalChecksumCrc32c
-            }
-        ]
-    }));
-    const storedManifest = await putAndVerifyCanonicalBlob(store, manifest, signal);
-    return {
-        reference: storedManifest.reference,
-        checksumCrc32c: (0, service_relocation_runtime_1.crc32c)(manifest)
-    };
-}
-async function putAndVerifyCanonicalBlob(store, payload, signal) {
-    const stored = await (0, relocation_blob_1.putNewRelocationBlob)(store, payload, RETENTION_MS, signal);
-    const read = await store.read(stored.reference, signal);
-    if (read.kind !== 'found' || !Buffer.from(read.bytes).equals(Buffer.from(payload))) {
-        await store.delete(stored.reference).catch(() => undefined);
-        throw new Error('Relocation Store failed canonical tree verification.');
-    }
-    return { reference: stored.reference };
-}
-async function readCanonicalDeferredJoinRoot(store, manifestPayload, signal) {
-    let manifest;
-    try {
-        manifest = decodeCanonicalTreeManifest(manifestPayload);
-    }
-    catch {
-        return undefined;
-    }
-    const parts = [];
-    for (const expected of manifest.chunks) {
-        const read = await store.read(expected.reference, signal);
-        if (read.kind !== 'found')
-            throw new Error('Canonical relocation chunk is missing.');
-        const chunk = (0, service_wire_pilot_codec_generated_1.decodeRelocationDataChunkV1)(read.bytes);
-        if (chunk.order !== expected.order || BigInt(chunk.data.byteLength) !== expected.length) {
-            throw new Error('Canonical relocation chunk identity is invalid.');
-        }
-        const data = Buffer.from(chunk.data);
-        if ((0, service_relocation_runtime_1.crc32c)(data) !== expected.checksumCrc32c) {
-            throw new Error('Canonical relocation chunk data checksum is invalid.');
-        }
-        parts.push(data);
-    }
-    const logical = Buffer.concat(parts);
-    if (BigInt(logical.byteLength) !== manifest.logicalLength ||
-        (0, service_relocation_runtime_1.crc32c)(logical) !== manifest.logicalChecksumCrc32c) {
-        throw new Error('Canonical relocation logical root checksum is invalid.');
-    }
-    return decodeCanonicalDeferredJoinRoot(logical);
-}
-function encodeCanonicalDeferredJoinRoot(value, authority, publication, inventoryDigest) {
-    const key = (0, authority_key_codec_1.encodeAuthorityKey)('actor', value.actor.actorId).value;
-    const completion = encodeDotNetDeferredJoinCompletion(value);
-    return Buffer.concat([
-        u32le(0x5a4c5231),
-        u16le(2),
-        dotNetGuidBytes(publication.aggregateId),
-        u64le(publication.aggregateGeneration),
-        bytes32le(inventoryDigest),
-        u32le(1),
-        text16le(key),
-        Buffer.of(1),
-        u64le(authority.objectGeneration),
-        u64le(authority.authorityOwnerGeneration),
-        bytes32le(Buffer.alloc(0)),
-        u32le(0),
-        u32le(0),
-        bytes32le(Buffer.alloc(0)),
-        bytes32le(completion)
-    ]);
-}
-function decodeCanonicalDeferredJoinRoot(payload) {
-    const reader = new LittleEndianReader(payload);
-    if (reader.u32() !== 0x5a4c5231 || reader.u16() !== 2)
-        return undefined;
-    const aggregateId = canonicalUuidFromDotNetBytes(reader.take(16));
-    const aggregateGeneration = reader.u64();
-    reader.bytes32();
-    const count = reader.u32();
-    let completion;
-    let completionIdentity;
-    for (let index = 0; index < count; index++) {
-        const authorityKey = reader.text16();
-        const objectKind = reader.u8();
-        const objectGeneration = reader.u64();
-        reader.u64();
-        reader.bytes32();
-        const jobs = reader.u32();
-        for (let job = 0; job < jobs; job++) {
-            reader.u64();
-            reader.bytes32();
-        }
-        const timers = reader.u32();
-        for (let timer = 0; timer < timers; timer++) {
-            reader.text16();
-            reader.i64();
-            reader.i64();
-            reader.bytes32();
-        }
-        reader.bytes32();
-        const encodedCompletion = reader.bytes32();
-        if (encodedCompletion.byteLength !== 0) {
-            if (completion !== undefined)
-                throw new Error('Canonical relocation root has duplicate completions.');
-            completion = decodeDotNetDeferredJoinCompletion(encodedCompletion);
-            if (objectKind !== 1)
-                return undefined;
-            completionIdentity = {
-                authorityKey,
-                objectKind: 'actor',
-                objectGeneration
-            };
-        }
-    }
-    if (!reader.done)
-        throw new Error('Canonical relocation root has trailing bytes.');
-    if (completion === undefined || completionIdentity === undefined)
-        return undefined;
-    if (completion.actor.objectGeneration !== completionIdentity.objectGeneration ||
-        (0, authority_key_codec_1.encodeAuthorityKey)('actor', completion.actor.actorId).value !== completionIdentity.authorityKey) {
-        return undefined;
-    }
-    return {
-        identity: {
-            ...completionIdentity,
-            aggregateId,
-            aggregateGeneration
-        },
-        completion
-    };
-}
-function encodeDotNetDeferredJoinCompletion(value) {
-    const routingId = Buffer.from((0, routing_id_1.encodeRoutingIdStorageHex)(value.actor.nodeRid), 'hex');
-    return Buffer.concat([
-        u32le(0x5a4c4a43),
-        Buffer.of(2),
-        text16le(value.actor.actorId),
-        u64le(value.actor.objectGeneration),
-        u64le(value.operationId.high),
-        u64le(value.operationId.low),
-        text16le(value.actor.meshName),
-        Buffer.of(routingId.byteLength),
-        routingId,
-        u64le(value.actor.objectGeneration),
-        Buffer.of(value.replyContentType === undefined ? 0 : 1),
-        ...(value.replyContentType === undefined ? [] : [text16le(value.replyContentType)]),
-        bytes32le(value.rawReply),
-        Buffer.of(cursorIndex(value.cursor) + 1)
-    ]);
-}
-function decodeDotNetDeferredJoinCompletion(payload) {
-    const reader = new LittleEndianReader(payload);
-    if (reader.u32() !== 0x5a4c4a43 || reader.u8() !== 2) {
-        throw new Error('Canonical deferred Join completion header is invalid.');
-    }
-    const actorId = reader.text16();
-    const objectGeneration = reader.u64();
-    const operationId = { high: reader.u64(), low: reader.u64() };
-    const meshName = reader.text16();
-    const nodeBytes = reader.take(reader.u8());
-    const actorGeneration = reader.u64();
-    const contentTypePresence = reader.u8();
-    if (contentTypePresence > 1) {
-        throw new Error('Canonical deferred Join completion content type is invalid.');
-    }
-    const replyContentType = contentTypePresence === 1 ? reader.text16() : undefined;
-    const rawReply = reader.bytes32();
-    const cursorValue = reader.u8();
-    if (!reader.done || actorGeneration !== objectGeneration || cursorValue < 1 || cursorValue > 3) {
-        throw new Error('Canonical deferred Join completion is invalid.');
-    }
-    const actor = {
-        actorId,
-        objectGeneration,
-        meshName,
-        nodeRid: (0, routing_id_1.decodeRoutingId)('', nodeBytes.toString('hex'))
-    };
-    validateIdentity(actorId, operationId, actor);
-    return {
-        operationId,
-        actor,
-        rawReply,
-        ...(replyContentType === undefined ? {} : { replyContentType }),
-        cursor: ['prepared', 'committed', 'delivered'][cursorValue - 1]
-    };
-}
-class LittleEndianReader {
-    offset = 0;
-    bytes;
-    constructor(payload) {
-        this.bytes = Buffer.from(payload);
-    }
-    get done() {
-        return this.offset === this.bytes.byteLength;
-    }
-    take(length) {
-        if (length < 0 || this.offset + length > this.bytes.byteLength) {
-            throw new Error('Canonical relocation root is truncated.');
-        }
-        const result = this.bytes.subarray(this.offset, this.offset + length);
-        this.offset += length;
-        return result;
-    }
-    u8() {
-        return this.take(1)[0];
-    }
-    u16() {
-        return this.take(2).readUInt16LE();
-    }
-    u32() {
-        return this.take(4).readUInt32LE();
-    }
-    u64() {
-        return this.take(8).readBigUInt64LE();
-    }
-    i64() {
-        return this.take(8).readBigInt64LE();
-    }
-    text16() {
-        const bytes = this.take(this.u16());
-        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
-    }
-    bytes32() {
-        return this.take(this.u32());
-    }
-}
-function dotNetGuidBytes(value) {
-    const bytes = Buffer.from(value.replaceAll('-', ''), 'hex');
-    return Buffer.from([
-        bytes[3],
-        bytes[2],
-        bytes[1],
-        bytes[0],
-        bytes[5],
-        bytes[4],
-        bytes[7],
-        bytes[6],
-        ...bytes.subarray(8)
-    ]);
-}
-function canonicalUuidFromDotNetBytes(value) {
-    const bytes = Buffer.from(value);
-    if (bytes.byteLength !== 16) {
-        throw new TypeError('Canonical 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)}`);
-}
-function text16le(value) {
-    const bytes = Buffer.from(value, 'utf8');
-    if (bytes.byteLength === 0 || bytes.byteLength > 0xffff)
-        throw new Error('Text16 is invalid.');
-    return Buffer.concat([u16le(bytes.byteLength), bytes]);
-}
-function bytes32le(value) {
-    return Buffer.concat([u32le(value.byteLength), Buffer.from(value)]);
-}
-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 validateIdentity(actorId, operationId, actor) {
-    if (actorId.length === 0 ||
-        actor.actorId !== actorId ||
-        actor.objectGeneration <= 0n ||
-        (operationId.high === 0n && operationId.low === 0n)) {
-        throw new Error('Deferred Join completion identity is invalid.');
-    }
-}
-function requireSameOperation(root, operationId, actor) {
-    if (!isSameOperation(root, operationId, actor)) {
-        throw new Error(`Actor '${actor.actorId}' already has a different durable Join completion.`);
-    }
-}
-function isSameOperation(root, operationId, actor) {
-    return (root.operationId.high === operationId.high &&
-        root.operationId.low === operationId.low &&
-        root.actor.actorId === actor.actorId &&
-        root.actor.objectGeneration === actor.objectGeneration);
-}
-function requireSameActor(root, actor) {
-    if (root.actor.actorId !== actor.actorId ||
-        root.actor.objectGeneration !== actor.objectGeneration) {
-        throw new Error('Deferred Join completion generation fence is stale ' +
-            `(root ${root.actor.actorId}/${root.actor.objectGeneration}, ` +
-            `actor ${actor.actorId}/${actor.objectGeneration}).`);
-    }
-}
-function cursorIndex(cursor) {
-    return cursor === 'prepared' ? 1 : cursor === 'committed' ? 2 : 3;
-}
-function isCursor(value) {
-    return value === 'prepared' || value === 'committed' || value === 'delivered';
-}
-function storedSnapshot(result) {
-    const { kind: _kind, ...snapshot } = result;
-    return { kind: 'snapshot', ...snapshot };
-}