@zlink-systems/framework 0.10.0

package/dist/runtime/actors/actor-authority-payload-codec.js

@@ -0,0 +1,366 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeCanonicalAuthorityPayload = encodeCanonicalAuthorityPayload;
+exports.decodeCanonicalAuthorityPayload = decodeCanonicalAuthorityPayload;
+exports.encodeActorAuthorityPayload = encodeActorAuthorityPayload;
+exports.decodeActorAuthorityPayload = decodeActorAuthorityPayload;
+exports.actorRelocationAuthorityApplicationPayload = actorRelocationAuthorityApplicationPayload;
+exports.relocatingActorAuthorityApplicationPayload = relocatingActorAuthorityApplicationPayload;
+exports.replaceActorRelocationAuthorityApplicationPayload = replaceActorRelocationAuthorityApplicationPayload;
+const contracts_1 = require("../../contracts");
+const service_relocation_runtime_1 = require("../foundation/service-relocation-runtime");
+const routing_id_1 = require("../routing-id");
+const AUTHORITY_MAGIC = Buffer.from([0x5a, 0x4c, 0x41, 0x55]);
+const AUTHORITY_VERSION = 1;
+const AUTHORITY_FLAGS = 0;
+const ACTOR_RELOCATION_MAGIC = Buffer.from([0x5a, 0x4c, 0x41, 0x50]);
+const MAXIMUM_BYTES = 1024 * 1024;
+const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true });
+/** Encodes the durable authority-payload-v1 envelope around one schema body. */
+function encodeCanonicalAuthorityPayload(value) {
+    const body = Buffer.from(value.body);
+    const envelope = concat(AUTHORITY_MAGIC, Buffer.of(AUTHORITY_VERSION), u16be(AUTHORITY_FLAGS), u32be(body.byteLength), body);
+    const encoded = concat(envelope, u32be((0, service_relocation_runtime_1.crc32c)(envelope)));
+    if (encoded.byteLength > MAXIMUM_BYTES) {
+        throw new RangeError('Actor authority payload exceeds 1 MiB.');
+    }
+    return encoded;
+}
+/** Decodes and checksum-validates the durable authority-payload-v1 envelope. */
+function decodeCanonicalAuthorityPayload(payload) {
+    try {
+        const reader = new BigEndianReader(payload);
+        if (reader.bytes.byteLength < 15 || reader.bytes.byteLength > MAXIMUM_BYTES) {
+            return undefined;
+        }
+        reader.expect(AUTHORITY_MAGIC);
+        if (reader.u8() !== AUTHORITY_VERSION || reader.u16() !== AUTHORITY_FLAGS) {
+            return undefined;
+        }
+        const body = reader.take(reader.u32());
+        const checksumOffset = reader.offset;
+        const checksum = reader.u32();
+        if (!reader.done || (0, service_relocation_runtime_1.crc32c)(reader.bytes.subarray(0, checksumOffset)) !== checksum) {
+            return undefined;
+        }
+        return { body: Buffer.from(body) };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Byte-exact Node counterpart of .NET ZLinkActorAuthorityPayloadCodec.Encode. */
+function encodeActorAuthorityPayload(value) {
+    const spotKind = (0, contracts_1.zlinkSpotKindToWire)(value.currentSpotKind);
+    if (spotKind !== 1 && spotKind !== 2) {
+        throw new RangeError('Actor currentSpotKind must be Entry or User.');
+    }
+    const actor = concat(text8(value.stableType, 'stableType'), text8(value.actorId, 'actorId'), Buffer.of(value.state === 'creating' ? 0 : 1), text8(value.currentSpotId, 'currentSpotId'), nonzeroU64be(value.currentSpotGeneration, 'currentSpotGeneration'), Buffer.of(spotKind));
+    const body = concat(Buffer.of(value.state === 'creating' ? 1 : 0), Buffer.of(1), u16be(actor.byteLength), actor, text8(value.ownerId, 'ownerId'), nonzeroU64be(value.ownerLeaseGeneration, 'ownerLeaseGeneration'), text8(value.meshName, 'meshName'), rid(value.nodeRid, 'nodeRid'), nonzeroU64be(value.nodeGeneration, 'nodeGeneration'), Buffer.of(0), u32be(0), Buffer.of(0), u32be(0));
+    return encodeCanonicalAuthorityPayload({ body });
+}
+/** Byte-exact Node counterpart of .NET ZLinkActorAuthorityPayloadCodec.TryDecodeDirect. */
+function decodeActorAuthorityPayload(payload) {
+    try {
+        const decoded = decodeCanonicalAuthorityPayload(payload);
+        if (decoded === undefined)
+            return undefined;
+        const body = new BigEndianReader(decoded.body);
+        const operation = body.u8();
+        if (body.u8() !== 1)
+            return undefined;
+        const actor = body.reader(body.u16());
+        const stableType = actor.text8();
+        const actorId = actor.text8();
+        const stateValue = actor.u8();
+        const currentSpotId = actor.text8();
+        const currentSpotGeneration = actor.nonzeroU64();
+        const currentSpotKind = (0, contracts_1.zlinkSpotKindFromWire)(actor.u8());
+        const state = stateValue === 0 && operation === 1
+            ? 'creating'
+            : stateValue === 1 && operation === 0
+                ? 'ready'
+                : undefined;
+        if (!actor.done
+            || state === undefined
+            || currentSpotKind !== contracts_1.ZLinkSpotKind.Entry && currentSpotKind !== contracts_1.ZLinkSpotKind.User) {
+            return undefined;
+        }
+        const ownerId = body.text8();
+        const ownerLeaseGeneration = body.nonzeroU64();
+        const meshName = body.text8();
+        const nodeRid = body.rid();
+        const nodeGeneration = body.nonzeroU64();
+        if (body.u8() !== 0
+            || body.u32() !== 0
+            || body.u8() !== 0
+            || body.u32() !== 0
+            || !body.done) {
+            return undefined;
+        }
+        return {
+            state,
+            stableType,
+            actorId,
+            currentSpotId,
+            currentSpotGeneration,
+            currentSpotKind,
+            ownerId,
+            ownerLeaseGeneration,
+            meshName,
+            nodeRid,
+            nodeGeneration
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Returns the ZLAU payload only when a .NET-compatible ZLAP is Steady. */
+function actorRelocationAuthorityApplicationPayload(payload) {
+    const current = decodeActorRelocationEnvelope(payload);
+    return current === undefined
+        ? Buffer.from(payload)
+        : current.phase === 4
+            ? Buffer.from(current.applicationPayload)
+            : undefined;
+}
+/** Returns the ZLAU payload from every valid .NET-compatible ZLAP phase. */
+function relocatingActorAuthorityApplicationPayload(payload) {
+    return Buffer.from(decodeActorRelocationEnvelope(payload)?.applicationPayload ?? payload);
+}
+/** Replaces only the application payload of a valid ZLAP phase envelope. */
+function replaceActorRelocationAuthorityApplicationPayload(payload, applicationPayload) {
+    const current = decodeActorRelocationEnvelope(payload);
+    if (current === undefined)
+        return Buffer.from(applicationPayload);
+    const withoutChecksum = concat(current.prefix, i32le(applicationPayload.byteLength), applicationPayload);
+    const encoded = concat(withoutChecksum, u32le((0, service_relocation_runtime_1.crc32c)(withoutChecksum)));
+    if (encoded.byteLength > MAXIMUM_BYTES) {
+        throw new RangeError('Actor relocation authority payload exceeds 1 MiB.');
+    }
+    return encoded;
+}
+function decodeActorRelocationEnvelope(payload) {
+    try {
+        const bytes = Buffer.from(payload);
+        if (bytes.byteLength < 32 || bytes.byteLength > MAXIMUM_BYTES)
+            return undefined;
+        const checksumOffset = bytes.byteLength - 4;
+        if (bytes.readUInt32LE(checksumOffset) !== (0, service_relocation_runtime_1.crc32c)(bytes.subarray(0, checksumOffset))) {
+            return undefined;
+        }
+        const reader = new LittleEndianReader(bytes.subarray(0, checksumOffset));
+        reader.expect(ACTOR_RELOCATION_MAGIC);
+        const version = reader.u16();
+        if (version !== 5 && version !== 6)
+            return undefined;
+        if (reader.take(16).every(byte => byte === 0))
+            return undefined;
+        const phase = reader.u8();
+        if (phase < 1 || phase > 4)
+            return undefined;
+        const isBound = reader.bool();
+        if (isBound) {
+            reader.bytes8();
+            reader.bytes8();
+            reader.text16();
+            const bindingGeneration = reader.u64();
+            const objectGeneration = reader.u64();
+            const authorityOwnerGeneration = reader.u64();
+            reader.text16();
+            const targetNodeGeneration = reader.u64();
+            const ownerLeaseGeneration = reader.u64();
+            const sessionOwnerNodeGeneration = reader.u64();
+            reader.u64();
+            if (version === 6) {
+                reader.text16();
+                reader.u64();
+            }
+            if (bindingGeneration === 0n
+                || objectGeneration === 0n
+                || authorityOwnerGeneration === 0n
+                || targetNodeGeneration === 0n
+                || ownerLeaseGeneration === 0n
+                || sessionOwnerNodeGeneration === 0n) {
+                return undefined;
+            }
+        }
+        const prefix = Buffer.from(reader.bytes.subarray(0, reader.offset));
+        const applicationLength = reader.i32();
+        if (applicationLength < 1 || applicationLength > MAXIMUM_BYTES)
+            return undefined;
+        const applicationPayload = Buffer.from(reader.take(applicationLength));
+        if (!reader.done)
+            return undefined;
+        return { prefix, phase, applicationPayload };
+    }
+    catch {
+        return undefined;
+    }
+}
+function text8(value, name) {
+    const bytes = Buffer.from(value, 'utf8');
+    if (bytes.byteLength < 1 || bytes.byteLength > 0xff || bytes.includes(0)) {
+        throw new RangeError(`${name} must contain 1..255 UTF-8 bytes without NUL.`);
+    }
+    return concat(Buffer.of(bytes.byteLength), bytes);
+}
+function rid(value, name) {
+    const bytes = Buffer.from((0, routing_id_1.encodeRoutingIdStorageHex)(value), 'hex');
+    if (bytes.byteLength < 1 || bytes.byteLength > 0xff) {
+        throw new RangeError(`${name} must contain 1..255 bytes.`);
+    }
+    return concat(Buffer.of(bytes.byteLength), bytes);
+}
+function nonzeroU64be(value, name) {
+    if (value === 0n || value < 0n || value > 0xffffffffffffffffn) {
+        throw new RangeError(`${name} must be a non-zero u64.`);
+    }
+    const result = Buffer.alloc(8);
+    result.writeBigUInt64BE(value);
+    return result;
+}
+function u16be(value) {
+    const result = Buffer.alloc(2);
+    result.writeUInt16BE(value);
+    return result;
+}
+function u32be(value) {
+    const result = Buffer.alloc(4);
+    result.writeUInt32BE(value);
+    return result;
+}
+function u32le(value) {
+    const result = Buffer.alloc(4);
+    result.writeUInt32LE(value);
+    return result;
+}
+function i32le(value) {
+    const result = Buffer.alloc(4);
+    result.writeInt32LE(value);
+    return result;
+}
+function concat(...parts) {
+    return Buffer.concat(parts.map(part => Buffer.from(part)));
+}
+class BigEndianReader {
+    bytes;
+    offset = 0;
+    constructor(payload) {
+        this.bytes = Buffer.from(payload);
+    }
+    get done() {
+        return this.offset === this.bytes.byteLength;
+    }
+    expect(expected) {
+        if (!this.take(expected.byteLength).equals(Buffer.from(expected))) {
+            throw new Error('Authority payload magic mismatch.');
+        }
+    }
+    u8() {
+        return this.take(1)[0];
+    }
+    u16() {
+        return this.take(2).readUInt16BE(0);
+    }
+    u32() {
+        return this.take(4).readUInt32BE(0);
+    }
+    nonzeroU64() {
+        const value = this.take(8).readBigUInt64BE(0);
+        if (value === 0n)
+            throw new Error('Authority non-zero u64 is zero.');
+        return value;
+    }
+    text8() {
+        const length = this.u8();
+        if (length === 0)
+            throw new Error('Authority text is empty.');
+        const value = this.take(length);
+        if (value.includes(0))
+            throw new Error('Authority text contains NUL.');
+        return FATAL_UTF8.decode(value);
+    }
+    rid() {
+        const length = this.u8();
+        if (length === 0)
+            throw new Error('Authority RID is empty.');
+        const value = this.take(length);
+        let text;
+        try {
+            text = FATAL_UTF8.decode(value);
+        }
+        catch {
+            text = value.toString('hex');
+        }
+        return (0, routing_id_1.decodeRoutingId)(text, value.toString('hex'));
+    }
+    reader(length) {
+        return new BigEndianReader(this.take(length));
+    }
+    take(length) {
+        if (length < 0 || this.offset + length > this.bytes.byteLength) {
+            throw new Error('Authority payload is truncated.');
+        }
+        const result = this.bytes.subarray(this.offset, this.offset + length);
+        this.offset += length;
+        return result;
+    }
+}
+class LittleEndianReader {
+    bytes;
+    offset = 0;
+    constructor(payload) {
+        this.bytes = Buffer.from(payload);
+    }
+    get done() {
+        return this.offset === this.bytes.byteLength;
+    }
+    expect(expected) {
+        if (!this.take(expected.byteLength).equals(Buffer.from(expected))) {
+            throw new Error('Actor relocation payload magic mismatch.');
+        }
+    }
+    u8() {
+        return this.take(1)[0];
+    }
+    bool() {
+        const value = this.u8();
+        if (value !== 0 && value !== 1)
+            throw new Error('Actor relocation bool is invalid.');
+        return value === 1;
+    }
+    u16() {
+        return this.take(2).readUInt16LE(0);
+    }
+    i32() {
+        return this.take(4).readInt32LE(0);
+    }
+    u64() {
+        return this.take(8).readBigUInt64LE(0);
+    }
+    bytes8() {
+        const length = this.u8();
+        if (length === 0)
+            throw new Error('Actor relocation byte field is empty.');
+        return this.take(length);
+    }
+    text16() {
+        const length = this.u16();
+        if (length === 0)
+            throw new Error('Actor relocation text is empty.');
+        const value = this.take(length);
+        if (value.includes(0))
+            throw new Error('Actor relocation text contains NUL.');
+        return FATAL_UTF8.decode(value);
+    }
+    take(length) {
+        if (length < 0 || this.offset + length > this.bytes.byteLength) {
+            throw new Error('Actor relocation payload is truncated.');
+        }
+        const result = this.bytes.subarray(this.offset, this.offset + length);
+        this.offset += length;
+        return result;
+    }
+}

package/dist/runtime/actors/actor-authority-publication.d.ts

@@ -0,0 +1,28 @@
+import type { ActorRef } from '../../contracts';
+import { ZLinkSpotKind } from '../../contracts';
+import type { ZLinkLocationOwnerToken } from '../../contracts/Locations';
+import type { ZLinkAuthoritySnapshot } from '../locations/internal-location-contracts';
+import type { ZLinkObjectCreationStore } from '../locations/internal-store-contracts';
+import { type ZLinkActorAuthorityState } from './actor-authority-payload-codec';
+export interface ZLinkActorAuthorityIdentity {
+    readonly actorType: string;
+    readonly actor: ActorRef;
+    readonly meshName: string;
+    readonly ownerNodeGeneration: bigint;
+    readonly owner: ZLinkLocationOwnerToken;
+    readonly state?: ZLinkActorAuthorityState;
+    readonly spotId: string;
+    readonly spotGeneration: bigint;
+    readonly spotKind: ZLinkSpotKind.Entry | ZLinkSpotKind.User;
+}
+/**
+ * Publishes the authority record that owns durable Actor lifecycle state.
+ * The legacy location row remains the public lookup projection.
+ */
+export declare function publishInitialActorAuthority(store: ZLinkObjectCreationStore, identity: ZLinkActorAuthorityIdentity, signal?: AbortSignal): Promise<ZLinkAuthoritySnapshot>;
+export declare function encodeActorAuthorityIdentity(identity: ZLinkActorAuthorityIdentity): Buffer;
+export declare function decodeActorAuthorityIdentity(payload: Uint8Array, objectGeneration: bigint): ZLinkActorAuthorityIdentity | undefined;
+export declare function decodeRelocatingActorAuthorityIdentity(payload: Uint8Array, objectGeneration: bigint): ZLinkActorAuthorityIdentity | undefined;
+export declare function rewriteActorAuthorityRoute(payload: Uint8Array, actor: ActorRef, spotId: string, spotGeneration: bigint, spotKind: ZLinkSpotKind.Entry | ZLinkSpotKind.User, ownerNodeGeneration?: bigint, owner?: ZLinkLocationOwnerToken): Buffer;
+export declare function rewriteActorAuthorityOwner(payload: Uint8Array, owner: ZLinkLocationOwnerToken): Buffer;
+export declare function isActorAuthorityPayload(payload: Uint8Array): boolean;

package/dist/runtime/actors/actor-authority-publication.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publishInitialActorAuthority = publishInitialActorAuthority;
+exports.encodeActorAuthorityIdentity = encodeActorAuthorityIdentity;
+exports.decodeActorAuthorityIdentity = decodeActorAuthorityIdentity;
+exports.decodeRelocatingActorAuthorityIdentity = decodeRelocatingActorAuthorityIdentity;
+exports.rewriteActorAuthorityRoute = rewriteActorAuthorityRoute;
+exports.rewriteActorAuthorityOwner = rewriteActorAuthorityOwner;
+exports.isActorAuthorityPayload = isActorAuthorityPayload;
+const node_crypto_1 = require("node:crypto");
+const actor_authority_payload_codec_1 = require("./actor-authority-payload-codec");
+const service_relocation_runtime_1 = require("../foundation/service-relocation-runtime");
+const CREATION_OPERATION_TIMEOUT_MS = 30_000;
+/**
+ * Publishes the authority record that owns durable Actor lifecycle state.
+ * The legacy location row remains the public lookup projection.
+ */
+async function publishInitialActorAuthority(store, identity, signal) {
+    const creatingPayload = encodeActorAuthorityIdentity({ ...identity, state: 'creating' });
+    const readyPayload = encodeActorAuthorityIdentity({ ...identity, state: 'ready' });
+    const digest = (0, node_crypto_1.createHash)('sha256').update(readyPayload).digest();
+    const target = {
+        meshName: identity.meshName,
+        nodeRid: identity.actor.nodeRid,
+        nodeLifecycleGeneration: identity.ownerNodeGeneration,
+        owner: identity.owner
+    };
+    const reserved = await store.reserve({
+        key: { kind: 'actor', globalId: identity.actor.actorId },
+        intent: {
+            stableType: identity.actorType,
+            requestContentReference: `sha256:${digest.toString('hex')}`,
+            requestSha256: digest,
+            requestEncodedSize: BigInt(readyPayload.byteLength)
+        },
+        target,
+        creatingPayload,
+        capacity: { actors: 1, spots: 0 }
+    }, signal);
+    if (reserved.kind === 'alreadyExists') {
+        requireActorAuthority(reserved.current, identity);
+        return reserved.current;
+    }
+    if (reserved.kind !== 'reserved') {
+        throw new Error(`Actor '${identity.actor.actorId}' authority reservation failed with '${reserved.kind}'.`);
+    }
+    try {
+        const terminalEnvelope = Buffer.from(JSON.stringify({
+            status: 'created',
+            actorId: identity.actor.actorId,
+            actorGeneration: identity.actor.objectGeneration.toString()
+        }), 'utf8');
+        const operationBytes = (0, node_crypto_1.randomBytes)(16);
+        const completed = await store.completeCreation({
+            key: { kind: 'actor', globalId: identity.actor.actorId },
+            reservationId: reserved.reservationId,
+            expectedStoreVersion: reserved.creating.storeVersion.value,
+            target,
+            completion: {
+                kind: 'created',
+                readyPayload,
+                terminal: {
+                    operation: {
+                        sourceNodeRid: identity.actor.nodeRid,
+                        sourceNodeGeneration: identity.ownerNodeGeneration,
+                        operationId: {
+                            high: operationBytes.readBigUInt64BE(0),
+                            low: operationBytes.readBigUInt64BE(8)
+                        }
+                    },
+                    terminalEnvelope,
+                    terminalEnvelopeSha256: (0, node_crypto_1.createHash)('sha256').update(terminalEnvelope).digest(),
+                    operationDeadline: new Date(Date.now() + CREATION_OPERATION_TIMEOUT_MS)
+                }
+            }
+        }, signal);
+        if (completed.kind !== 'created') {
+            throw new Error(`Actor '${identity.actor.actorId}' authority completion failed with '${completed.kind}'.`);
+        }
+        requireActorAuthority(completed.ready, identity);
+        return completed.ready;
+    }
+    catch (error) {
+        try {
+            await store.abort({
+                key: { kind: 'actor', globalId: identity.actor.actorId },
+                reservationId: reserved.reservationId,
+                expectedStoreVersion: reserved.creating.storeVersion.value,
+                target
+            }, signal);
+        }
+        catch {
+            // A completed creation cannot be aborted; the validated authority remains.
+        }
+        throw error;
+    }
+}
+function encodeActorAuthorityIdentity(identity) {
+    return (0, actor_authority_payload_codec_1.encodeActorAuthorityPayload)({
+        state: identity.state ?? 'ready',
+        stableType: identity.actorType,
+        actorId: identity.actor.actorId,
+        currentSpotId: identity.spotId,
+        currentSpotGeneration: identity.spotGeneration,
+        currentSpotKind: identity.spotKind,
+        ownerId: identity.owner.ownerId,
+        ownerLeaseGeneration: identity.owner.leaseGeneration,
+        meshName: identity.meshName,
+        nodeRid: identity.actor.nodeRid,
+        nodeGeneration: identity.ownerNodeGeneration
+    });
+}
+function decodeActorAuthorityIdentity(payload, objectGeneration) {
+    return decodeActorAuthorityIdentityCore(payload, objectGeneration, false);
+}
+function decodeRelocatingActorAuthorityIdentity(payload, objectGeneration) {
+    return decodeActorAuthorityIdentityCore(payload, objectGeneration, true);
+}
+function decodeActorAuthorityIdentityCore(payload, objectGeneration, relocating) {
+    if (objectGeneration <= 0n)
+        return undefined;
+    const outerApplication = (0, service_relocation_runtime_1.serviceRelocationAuthorityApplicationPayload)(payload);
+    const actorApplication = relocating
+        ? (0, actor_authority_payload_codec_1.relocatingActorAuthorityApplicationPayload)(outerApplication)
+        : (0, actor_authority_payload_codec_1.actorRelocationAuthorityApplicationPayload)(outerApplication);
+    if (actorApplication === undefined)
+        return undefined;
+    const value = (0, actor_authority_payload_codec_1.decodeActorAuthorityPayload)(actorApplication);
+    if (value === undefined)
+        return undefined;
+    return {
+        actorType: value.stableType,
+        actor: {
+            actorId: value.actorId,
+            objectGeneration,
+            meshName: value.meshName,
+            nodeRid: value.nodeRid
+        },
+        meshName: value.meshName,
+        ownerNodeGeneration: value.nodeGeneration,
+        owner: {
+            ownerId: value.ownerId,
+            leaseGeneration: value.ownerLeaseGeneration
+        },
+        state: value.state,
+        spotId: value.currentSpotId,
+        spotGeneration: value.currentSpotGeneration,
+        spotKind: value.currentSpotKind
+    };
+}
+function rewriteActorAuthorityRoute(payload, actor, spotId, spotGeneration, spotKind, ownerNodeGeneration, owner) {
+    return rewriteActorAuthorityPayload(payload, value => {
+        if (value.actorId !== actor.actorId) {
+            throw new Error(`Actor '${actor.actorId}' authority identity is invalid.`);
+        }
+        return (0, actor_authority_payload_codec_1.encodeActorAuthorityPayload)({
+            ...value,
+            currentSpotId: spotId,
+            currentSpotGeneration: spotGeneration,
+            currentSpotKind: spotKind,
+            nodeRid: actor.nodeRid,
+            nodeGeneration: ownerNodeGeneration ?? value.nodeGeneration,
+            ownerId: owner?.ownerId ?? value.ownerId,
+            ownerLeaseGeneration: owner?.leaseGeneration ?? value.ownerLeaseGeneration,
+            meshName: actor.meshName
+        });
+    });
+}
+function rewriteActorAuthorityOwner(payload, owner) {
+    return rewriteActorAuthorityPayload(payload, value => (0, actor_authority_payload_codec_1.encodeActorAuthorityPayload)({
+        ...value,
+        ownerId: owner.ownerId,
+        ownerLeaseGeneration: owner.leaseGeneration
+    }));
+}
+function isActorAuthorityPayload(payload) {
+    const outerApplication = (0, service_relocation_runtime_1.serviceRelocationAuthorityApplicationPayload)(payload);
+    return (0, actor_authority_payload_codec_1.decodeActorAuthorityPayload)((0, actor_authority_payload_codec_1.relocatingActorAuthorityApplicationPayload)(outerApplication)) !== undefined;
+}
+function rewriteActorAuthorityPayload(payload, rewrite) {
+    const outerApplication = (0, service_relocation_runtime_1.serviceRelocationAuthorityApplicationPayload)(payload);
+    const actorApplication = (0, actor_authority_payload_codec_1.relocatingActorAuthorityApplicationPayload)(outerApplication);
+    const value = (0, actor_authority_payload_codec_1.decodeActorAuthorityPayload)(actorApplication);
+    if (value === undefined)
+        throw new Error('Actor authority payload identity is invalid.');
+    const rewrittenActor = rewrite(value);
+    const rewrittenPhase = (0, actor_authority_payload_codec_1.replaceActorRelocationAuthorityApplicationPayload)(outerApplication, rewrittenActor);
+    return (0, service_relocation_runtime_1.replaceServiceRelocationAuthorityApplicationPayload)(payload, rewrittenPhase);
+}
+function requireActorAuthority(snapshot, expected) {
+    const actual = decodeActorAuthorityIdentity(snapshot.payload, snapshot.objectGeneration);
+    if (snapshot.allocation.state !== 'active'
+        || snapshot.allocation.objectKind !== 'actor'
+        || snapshot.allocation.stableType !== expected.actorType
+        || snapshot.allocation.descriptor.meshName !== expected.meshName
+        || String(snapshot.allocation.descriptor.rid) !== String(expected.actor.nodeRid)
+        || snapshot.allocation.descriptorLifecycleGeneration !== expected.ownerNodeGeneration
+        || snapshot.ownerId !== expected.owner.ownerId
+        || snapshot.ownerLeaseGeneration !== expected.owner.leaseGeneration
+        || actual === undefined
+        || actual.actorType !== expected.actorType
+        || actual.actor.actorId !== expected.actor.actorId
+        || actual.actor.objectGeneration !== expected.actor.objectGeneration
+        || String(actual.actor.nodeRid) !== String(expected.actor.nodeRid)) {
+        throw new Error(`Actor '${expected.actor.actorId}' authority fence does not match its ActorRef.`);
+    }
+}

package/dist/runtime/actors/actor-client.d.ts

@@ -0,0 +1,36 @@
+import type { ActorRef, ZLinkActorClient, ZLinkActorRequestCall, ZLinkActorSendCall, ZLinkMessageSerializer } from '../../contracts';
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkBackendMeshNode, ZLinkMeshCompletionTable } from '../backend';
+import type { ZLinkStoreLocationResolvers } from '../locations';
+import type { ZLinkActorRoutedJoinTransport } from './actor-routed-join-transport';
+export interface ZLinkActorClientOptions {
+    readonly nodeProvider: (meshName: string) => ZLinkBackendMeshNode | undefined;
+    readonly completionTableProvider: (meshName: string) => ZLinkMeshCompletionTable | undefined;
+    readonly locationResolver: () => ZLinkStoreLocationResolvers | undefined;
+    readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
+    readonly defaultRequestTimeoutMs?: number;
+    readonly staleActorRefReporter?: (meshName: string, actorId: string) => void;
+    readonly staleActorRefPredicate?: (meshName: string, actor: ActorRef) => boolean;
+    readonly handoffCapture?: (meshName: string, actorId: string, parts: readonly Message[], returnResponse: boolean, actor: ActorRef, deadlineUnixMs?: number) => Promise<unknown> | undefined;
+    readonly sendErrorReporter?: (error: unknown) => void;
+    readonly routeTransport?: ZLinkActorRoutedJoinTransport;
+    readonly transportDeliveryGate?: () => {
+        waitBeforeSubmit(actorId: string, kind: 'oneWay' | 'request', signal?: AbortSignal): Promise<number | void>;
+    } | undefined;
+}
+export declare class DefaultZLinkActorClient implements ZLinkActorClient {
+    private readonly options;
+    constructor(options: ZLinkActorClientOptions);
+    sendToActor(actorId: string, message: unknown): ZLinkActorSendCall;
+    requestToActor(actorId: string, request: unknown): ZLinkActorRequestCall;
+    private send;
+    private request;
+    private resolveActorRoute;
+    private invalidateActorRoute;
+    private throwIfKnownStale;
+    private createPacketParts;
+    private submitActorSend;
+    private submitActorRequest;
+    private requireNode;
+}
+export declare function forwardEncodedActorPacket(node: ZLinkBackendMeshNode, completions: ZLinkMeshCompletionTable, actor: ActorRef, header: Buffer, payload: Buffer, returnResponse: boolean, timeoutMs: number | undefined, serializers?: ReadonlyMap<string, ZLinkMessageSerializer>): Promise<unknown>;