@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,962 @@
+"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 MAX_ROOT_BYTES = 1024 * 1024;
+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')]);
+    if (encoded.byteLength > MAX_ROOT_BYTES) {
+        throw new Error('Deferred Join completion root exceeds 1 MiB.');
+    }
+    return encoded;
+}
+function decodeRoot(payload) {
+    if (payload.byteLength === 0 || payload.byteLength > MAX_ROOT_BYTES) {
+        throw new Error('Deferred Join completion root size is invalid.');
+    }
+    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 };
+}