@zlink-systems/framework 0.10.0

package/dist/runtime/actors/actor-join-deferred-scope.d.ts

@@ -0,0 +1,11 @@
+interface DeferredActorJoin {
+    readonly requestBytes: number;
+    /** Starts target admission after the handler terminal, before reply admission. */
+    readonly prepare?: () => Promise<void> | void;
+    readonly execute: () => Promise<void>;
+    readonly discard: () => Promise<void> | void;
+}
+export declare function deferActorJoin(intent: DeferredActorJoin): void;
+export declare function runActorHandlerWithDeferredJoins<T>(handler: () => Promise<T> | T): Promise<T>;
+export declare function runActorHandlerWithDeferredJoins<T, TResult>(handler: () => Promise<T> | T, afterHandler: (result: T) => Promise<TResult> | TResult, beforeJoins?: (result: T) => Promise<void> | void): Promise<TResult>;
+export {};

package/dist/runtime/actors/actor-join-deferred-scope.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deferActorJoin = deferActorJoin;
+exports.runActorHandlerWithDeferredJoins = runActorHandlerWithDeferredJoins;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const node_async_hooks_1 = require("node:async_hooks");
+const configuration_1 = require("../configuration");
+const MAX_DEFERRED_JOINS = 64;
+const MAX_DEFERRED_JOIN_REQUEST_BYTES = 1024 * 1024;
+const MAX_DEFERRED_JOIN_BYTES = 8 * 1024 * 1024;
+class ActorJoinRegistrationScope {
+    intents = [];
+    totalBytes = 0;
+    open = true;
+    prepared = false;
+    // Ledger 2.3: a deferred join runs in registration order right after the
+    // handler terminal and before the next queued turn, matching the C++ serial
+    // queue's deferred-after-active list.
+    register(intent) {
+        if (!this.open) {
+            discardWithoutWaiting(intent);
+            throw new configuration_1.ZLinkConfigurationException('Actor join defer requires an open Framework actor handler scope.');
+        }
+        if (this.intents.length >= MAX_DEFERRED_JOINS) {
+            discardWithoutWaiting(intent);
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidConfiguration, `An actor handler may defer at most ${MAX_DEFERRED_JOINS} joins.`);
+        }
+        if (intent.requestBytes > MAX_DEFERRED_JOIN_REQUEST_BYTES) {
+            discardWithoutWaiting(intent);
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidConfiguration, `A deferred actor join request may use at most ${MAX_DEFERRED_JOIN_REQUEST_BYTES} bytes.`);
+        }
+        if (this.totalBytes + intent.requestBytes > MAX_DEFERRED_JOIN_BYTES) {
+            discardWithoutWaiting(intent);
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidConfiguration, `Deferred actor join requests may use at most ${MAX_DEFERRED_JOIN_BYTES} bytes per handler.`);
+        }
+        this.intents.push(intent);
+        this.totalBytes += intent.requestBytes;
+    }
+    sealAfterHandlerTerminal() {
+        this.open = false;
+    }
+    async prepareSealedJoins() {
+        await this.prepareSealedJoinsCore();
+    }
+    async prepareSealedJoinsCore() {
+        if (this.prepared) {
+            return;
+        }
+        this.prepared = true;
+        for (const intent of this.intents) {
+            await intent.prepare?.();
+        }
+    }
+    async activateSealedJoins() {
+        if (this.intents.length === 0) {
+            return;
+        }
+        await this.prepareSealedJoinsCore();
+        // A deferred callback failure cannot replace the handler result with a
+        // second request outcome. The dispatcher releases that result only after
+        // this terminal work, while the next queued turn remains behind it.
+        await this.execute().catch(() => undefined);
+    }
+    async discard() {
+        this.open = false;
+        await Promise.allSettled(this.intents.map((intent) => intent.discard()));
+    }
+    async execute() {
+        for (const intent of this.intents) {
+            await intent.execute();
+        }
+    }
+}
+const actorJoinScope = new node_async_hooks_1.AsyncLocalStorage();
+function deferActorJoin(intent) {
+    const scope = actorJoinScope.getStore();
+    if (scope === undefined) {
+        discardWithoutWaiting(intent);
+        throw new configuration_1.ZLinkConfigurationException('Actor join defer requires an open Framework actor handler scope.');
+    }
+    scope.register(intent);
+}
+async function runActorHandlerWithDeferredJoins(handler, afterHandler, beforeJoins) {
+    const scope = new ActorJoinRegistrationScope();
+    let joinsPrepared = false;
+    let replyPrepared = false;
+    try {
+        const result = await actorJoinScope.run(scope, async () => handler());
+        // The registration scope ends at the handler terminal. Reply admission
+        // is a separate terminal operation and must not reopen the opportunity
+        // for a detached continuation to register another Join.
+        scope.sealAfterHandlerTerminal();
+        // Encode or otherwise validate the original reply while the Join barrier
+        // is still inactive. A reply encoding failure is a handler failure and
+        // must discard the registered intents before target admission starts.
+        await beforeJoins?.(result);
+        replyPrepared = beforeJoins !== undefined;
+        // Target admission starts at the handler terminal, but its completion
+        // callback remains behind the original request reply and mailbox turn.
+        await scope.prepareSealedJoins();
+        joinsPrepared = true;
+        let afterResult;
+        let afterError;
+        let afterFailed = false;
+        try {
+            afterResult = (afterHandler === undefined
+                ? result
+                : await afterHandler(result));
+        }
+        catch (error) {
+            // A transport failure after reply encoding does not cancel a Join that
+            // has already been admitted. Continue its terminal work, then rethrow
+            // the transport error to the caller.
+            afterError = error;
+            afterFailed = true;
+        }
+        if (afterFailed && !replyPrepared) {
+            await scope.discard();
+            throw afterError;
+        }
+        await scope.activateSealedJoins();
+        if (afterFailed)
+            throw afterError;
+        return afterResult;
+    }
+    catch (error) {
+        if (!joinsPrepared) {
+            await scope.discard();
+        }
+        throw error;
+    }
+}
+function discardWithoutWaiting(intent) {
+    try {
+        const discarded = intent.discard();
+        if (discarded !== undefined && typeof discarded.catch === 'function') {
+            void discarded.catch(() => undefined);
+        }
+    }
+    catch {
+        // The original registration error is the contract-visible failure. The
+        // asynchronous rollback is best effort here because defer() is synchronous.
+    }
+}

package/dist/runtime/actors/actor-join-relocation.d.ts

@@ -0,0 +1,38 @@
+import type { ZLinkActor, ZLinkActorJoinOperationId } from '../../contracts';
+import type { ZLinkBackendActorRef } from '../backend';
+import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
+import type { ZLinkActorRuntimeState } from './actor-runtime-state';
+/** Goal port implemented by the Host relocation aggregate for cross-node Actor Join. */
+export interface ZLinkActorJoinRelocation {
+    relocateActorJoin(input: {
+        readonly meshName: string;
+        readonly actor: ZLinkActor;
+        readonly state: ZLinkActorRuntimeState;
+        readonly target: ZLinkSpotRouteTarget;
+        /** Private RelocationId; never the public Join OperationId. */
+        readonly relocationId: string;
+        readonly completionOperationId?: ZLinkActorJoinOperationId;
+        readonly canonicalRecovery?: {
+            readonly handoffId: string;
+            /** Core command-28 request identity retained by the target admission. */
+            readonly admissionOperationId: ZLinkActorJoinOperationId;
+            readonly requestContentType: string;
+            readonly request: Buffer;
+            readonly replyContentType?: string;
+            readonly reply: Buffer;
+            readonly actorNodeGeneration: bigint;
+            readonly expectedOwnerLeaseGeneration: bigint;
+            readonly targetNodeGeneration: bigint;
+            readonly targetSpotGeneration: bigint;
+            readonly targetAuthorityOwnerGeneration: bigint;
+            readonly targetSpotAuthorityOwnerGeneration: bigint;
+        };
+        /** Target's advertised relocation state chunk cap from the accepted admission reply. */
+        readonly advertisedReceiveChunkLimitBytes?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<{
+        readonly actorRef: ZLinkBackendActorRef;
+        readonly membershipEpoch: bigint;
+        readonly spotGeneration: bigint;
+    }>;
+}

package/dist/runtime/actors/actor-join-relocation.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/runtime/actors/actor-lifecycle-snapshot.d.ts

@@ -0,0 +1,21 @@
+import type { ActorRef, ZLinkActor, ZLinkActorMembership } from '../../contracts';
+export declare const ZLINK_ACTOR_LIFECYCLE_SNAPSHOT: unique symbol;
+export interface ZLinkActorLifecycleSnapshotSource {
+    readonly actorRef: ActorRef;
+    readonly actorType: string;
+    readonly membershipEpoch: bigint;
+}
+interface ZLinkActorJoinRequest {
+    readonly actor: ActorRef;
+    readonly actorType: string;
+    readonly expectedMembershipEpoch: bigint;
+}
+/**
+ * Identity an admission callback observes. Join admission decides on the Actor's
+ * identity alone, so the runtime resolves it from the same framework snapshot the
+ * membership values use instead of handing the application the fencing state.
+ */
+export declare function actorJoinIdentity(actor: ZLinkActor): string;
+export declare function createActorJoinRequest(actor: ZLinkActor, actorRef?: ActorRef, expectedMembershipEpoch?: bigint): ZLinkActorJoinRequest;
+export declare function createActorMembership(actor: ZLinkActor, actorRef?: ActorRef, membershipEpoch?: bigint): ZLinkActorMembership;
+export {};

package/dist/runtime/actors/actor-lifecycle-snapshot.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLINK_ACTOR_LIFECYCLE_SNAPSHOT = void 0;
+exports.actorJoinIdentity = actorJoinIdentity;
+exports.createActorJoinRequest = createActorJoinRequest;
+exports.createActorMembership = createActorMembership;
+const configuration_1 = require("../configuration");
+exports.ZLINK_ACTOR_LIFECYCLE_SNAPSHOT = Symbol('zlink.actor.lifecycle-snapshot');
+/**
+ * Identity an admission callback observes. Join admission decides on the Actor's
+ * identity alone, so the runtime resolves it from the same framework snapshot the
+ * membership values use instead of handing the application the fencing state.
+ */
+function actorJoinIdentity(actor) {
+    return lifecycleSource(actor).actorRef.actorId;
+}
+function createActorJoinRequest(actor, actorRef, expectedMembershipEpoch) {
+    const source = lifecycleSource(actor);
+    return Object.freeze({
+        actor: immutableActorRef(actorRef ?? source.actorRef),
+        actorType: source.actorType,
+        expectedMembershipEpoch: expectedMembershipEpoch ?? source.membershipEpoch
+    });
+}
+function createActorMembership(actor, actorRef, membershipEpoch) {
+    const source = lifecycleSource(actor);
+    return Object.freeze({
+        actor: immutableActorRef(actorRef ?? source.actorRef),
+        actorType: source.actorType,
+        membershipEpoch: membershipEpoch ?? source.membershipEpoch
+    });
+}
+function lifecycleSource(actor) {
+    const rawContext = actor.context;
+    const context = typeof rawContext === 'object' && rawContext !== null
+        ? rawContext
+        : undefined;
+    // A caller can hand in a value that carries no Framework context at all, so the
+    // failure path reports the configuration error instead of dereferencing it.
+    const actorId = context?.actorId ?? '<unknown>';
+    const snapshot = context?.[exports.ZLINK_ACTOR_LIFECYCLE_SNAPSHOT];
+    const source = snapshot === undefined ? undefined : snapshot.call(context);
+    if (source === undefined) {
+        throw new configuration_1.ZLinkConfigurationException(`Actor '${actorId}' does not expose a framework lifecycle identity snapshot.`);
+    }
+    if (source.actorRef.actorId !== actorId || source.actorType.length === 0) {
+        throw new configuration_1.ZLinkConfigurationException(`Actor '${actorId}' lifecycle identity is invalid.`);
+    }
+    return source;
+}
+function immutableActorRef(actorRef) {
+    return Object.freeze({
+        actorId: actorRef.actorId,
+        objectGeneration: actorRef.objectGeneration,
+        meshName: actorRef.meshName,
+        nodeRid: actorRef.nodeRid
+    });
+}

package/dist/runtime/actors/actor-local-native-join.d.ts

@@ -0,0 +1,27 @@
+import type { RoutingId, ZLinkActor, ZLinkActorJoinOperationId, ZLinkMessageSerializer } from '../../contracts';
+import type { ZLinkActorJoinRuntimeResult } from './actor-runtime-contracts';
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkBackendActorRef, ZLinkBackendMeshNode } from '../backend/contracts';
+import { type ZLinkMeshCompletionTable } from '../backend/mesh-completion-table';
+import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
+import { ZLinkActorRuntimeState } from './actor-runtime-state';
+import type { ZLinkPostCommitActorBinder } from './post-commit-actor-binder';
+import type { ZLinkPostCommitActorLocation } from './post-commit-actor-location';
+import type { ZLinkActorJoinRelocation } from './actor-join-relocation';
+export interface ZLinkLocalNativeActorJoinOptions {
+    readonly postCommitLocation?: ZLinkPostCommitActorLocation;
+    readonly postCommitBinder?: ZLinkPostCommitActorBinder;
+    readonly completionTableProvider: () => ZLinkMeshCompletionTable | undefined;
+    readonly actorJoinRelocation?: ZLinkActorJoinRelocation;
+    readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
+}
+/** Owns core-native actor joins and their local runtime state transition. */
+export declare class ZLinkLocalNativeActorJoin {
+    private readonly options;
+    constructor(options: ZLinkLocalNativeActorJoinOptions);
+    joinSpot(node: ZLinkBackendMeshNode, actor: ZLinkActor, state: ZLinkActorRuntimeState, actorRef: ZLinkBackendActorRef, spotId: RoutingId, spotRouteTarget: ZLinkSpotRouteTarget | undefined, request: Message, timeoutMs: number | undefined, signal: AbortSignal | undefined, completionOperationId?: ZLinkActorJoinOperationId): Promise<ZLinkActorJoinRuntimeResult<Message>>;
+    joinEntrySpot(node: ZLinkBackendMeshNode, actor: ZLinkActor, state: ZLinkActorRuntimeState, actorRef: ZLinkBackendActorRef, nodeRid: RoutingId, spotRouteTarget: ZLinkSpotRouteTarget | undefined, request: Message, timeoutMs: number | undefined, signal: AbortSignal | undefined, completionOperationId?: ZLinkActorJoinOperationId): Promise<ZLinkActorJoinRuntimeResult<Message>>;
+    private waitForJoinCompletion;
+    private relocateRemoteActorJoin;
+    private requireCompletions;
+}