@zlink-systems/framework 0.10.0

package/dist/runtime/execution/index.d.ts

@@ -0,0 +1,114 @@
+export { ZLinkStateLane } from './state-lane';
+export interface ZLinkRuntimeTaskFailure {
+    readonly taskName: string;
+    readonly error: unknown;
+}
+interface ZLinkSpotSerialTurnExecutorLike {
+    readonly activeTurnId: number;
+    readonly sourceSpotId?: unknown;
+    isActiveTurn(turn: ZLinkSpotSerialTurn, turnId: number): boolean;
+    post<T>(operation: () => Promise<T> | T): Promise<T>;
+}
+export type ZLinkExecutionArea = 'application' | 'infrastructure';
+export declare function runZLinkExecutionArea<T>(area: ZLinkExecutionArea, operation: () => T): T;
+export declare function currentZLinkExecutionArea(): ZLinkExecutionArea | undefined;
+export declare function requireZLinkInfrastructureExecutionArea(): void;
+export declare class ZLinkSpotSerialTurn {
+    private readonly postResume;
+    private executionClaim;
+    readonly yieldAllowed: boolean;
+    private suspendedResolve;
+    private suspendedPromise;
+    private suspendSignaled;
+    private owner;
+    private frameworkOperationsBlocked;
+    constructor(postResume: (turn: ZLinkSpotSerialTurn, resume: () => void, reject: (reason: unknown) => void) => boolean, executionClaim: ZLinkExecutionBarrierClaim | undefined, yieldAllowed: boolean);
+    bindExecutionClaim(claim: ZLinkExecutionBarrierClaim | undefined): void;
+    get isSuspended(): boolean;
+    releaseBoundExecutionClaim(): void;
+    get suspended(): Promise<void>;
+    bindOwner(owner: Promise<unknown>): void;
+    blockFrameworkOperations(): void;
+    ensureFrameworkOperationAllowed(): void;
+    resetSuspension(): void;
+    yieldPromise<T>(pending: Promise<T>): Promise<T>;
+    /** Suspends a turn only for a Framework-owned lifecycle boundary. */
+    yieldFrameworkPromise<T>(pending: Promise<T>): Promise<T>;
+    resumeOwnerUntilNextYield(): Promise<void>;
+    private signalSuspended;
+    private awaitResumePermit;
+}
+export declare function runZLinkSpotSerialTurn<T>(executor: ZLinkSpotSerialTurnExecutorLike, turnId: number, turn: ZLinkSpotSerialTurn, operation: () => Promise<T> | T): Promise<T>;
+export declare function captureZLinkSpotSerialTurn(executor?: ZLinkSpotSerialTurnExecutorLike): ZLinkSpotSerialTurn | undefined;
+/** Returns the physical Spot owner only while its captured turn owns the gate. */
+export declare function currentZLinkSpotSerialSourceId(): unknown;
+export declare function requireZLinkYieldTurn(capturedTurn?: ZLinkSpotSerialTurn): ZLinkSpotSerialTurn;
+export interface ZLinkCapturedExecutionTurn {
+    yieldPromise<T>(pending: Promise<T>): Promise<T>;
+    post(callback: () => void): void;
+}
+export declare function captureZLinkExecutionTurn(): ZLinkCapturedExecutionTurn | undefined;
+export declare function isCurrentZLinkSpotSerialTurn(executor: ZLinkSpotSerialTurnExecutorLike): boolean;
+export interface ZLinkExecutionBarrierSeal {
+    readonly generation: bigint;
+}
+export interface ZLinkExecutionBarrierClaim {
+    release(): void;
+}
+/**
+ * Seals application-lane admission and waits for every active Promise turn to
+ * finish. A seal generation prevents a stale abort from reopening a newer
+ * lifecycle barrier.
+ */
+export declare class ZLinkExecutionBarrier {
+    private generation;
+    private activeClaims;
+    private currentSeal;
+    private readonly admissionWaiters;
+    private readonly quiescenceWaiters;
+    private committed;
+    enter(): Promise<ZLinkExecutionBarrierClaim>;
+    /**
+     * Re-enters a previously yielded application turn only while admission is
+     * open. A continuation must fail instead of waiting behind a relocation
+     * seal that already won the turn-boundary race.
+     */
+    tryEnter(): ZLinkExecutionBarrierClaim | undefined;
+    seal(): ZLinkExecutionBarrierSeal;
+    waitForQuiescence(seal: ZLinkExecutionBarrierSeal, signal?: AbortSignal): Promise<void>;
+    abort(seal: ZLinkExecutionBarrierSeal): boolean;
+    commit(seal: ZLinkExecutionBarrierSeal): boolean;
+    isCurrent(seal: ZLinkExecutionBarrierSeal): boolean;
+    private createClaim;
+    private requireCurrent;
+}
+export type ZLinkRuntimeTaskFailureHandler = (failure: ZLinkRuntimeTaskFailure) => void;
+export type ZLinkRuntimeTaskCallback = (signal: AbortSignal) => Promise<void> | void;
+export declare class ZLinkRuntimeTaskErrorSink {
+    private readonly handlers;
+    onRuntimeTaskException(handler: ZLinkRuntimeTaskFailureHandler): () => void;
+    reportHandlerException(error: unknown): void;
+    reportRuntimeTaskException(taskName: string, error: unknown): void;
+}
+export declare class ZLinkRuntimeTaskRunner {
+    readonly errorSink: ZLinkRuntimeTaskErrorSink;
+    private readonly shutdownSignal;
+    constructor(errorSink: ZLinkRuntimeTaskErrorSink, shutdownSignal: AbortSignal);
+    runDetached(taskName: string, callback: ZLinkRuntimeTaskCallback): void;
+    run(taskName: string, callback: ZLinkRuntimeTaskCallback): Promise<void>;
+    reportErrorSinkFailure(_taskName: string, _error: unknown): void;
+}
+export declare class ZLinkFrameworkExecutionState {
+    readonly context: {
+        dispose(): Promise<void>;
+    };
+    readonly abortController: AbortController;
+    readonly errorSink: ZLinkRuntimeTaskErrorSink;
+    readonly taskRunner: ZLinkRuntimeTaskRunner;
+    readonly listenerTasks: Promise<void>[];
+    constructor(context: {
+        dispose(): Promise<void>;
+    });
+    dispose(): Promise<void>;
+    private waitForListenerTasks;
+}

package/dist/runtime/execution/index.js

@@ -0,0 +1,363 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkFrameworkExecutionState = exports.ZLinkRuntimeTaskRunner = exports.ZLinkRuntimeTaskErrorSink = exports.ZLinkExecutionBarrier = exports.ZLinkSpotSerialTurn = exports.ZLinkStateLane = void 0;
+exports.runZLinkExecutionArea = runZLinkExecutionArea;
+exports.currentZLinkExecutionArea = currentZLinkExecutionArea;
+exports.requireZLinkInfrastructureExecutionArea = requireZLinkInfrastructureExecutionArea;
+exports.runZLinkSpotSerialTurn = runZLinkSpotSerialTurn;
+exports.captureZLinkSpotSerialTurn = captureZLinkSpotSerialTurn;
+exports.currentZLinkSpotSerialSourceId = currentZLinkSpotSerialSourceId;
+exports.requireZLinkYieldTurn = requireZLinkYieldTurn;
+exports.captureZLinkExecutionTurn = captureZLinkExecutionTurn;
+exports.isCurrentZLinkSpotSerialTurn = isCurrentZLinkSpotSerialTurn;
+const node_async_hooks_1 = require("node:async_hooks");
+const configuration_1 = require("../configuration");
+const abort_1 = require("../abort");
+const framework_errors_internal_1 = require("../framework-errors-internal");
+var state_lane_1 = require("./state-lane");
+Object.defineProperty(exports, "ZLinkStateLane", { enumerable: true, get: function () { return state_lane_1.ZLinkStateLane; } });
+const spotSerialTurnStorage = new node_async_hooks_1.AsyncLocalStorage();
+const executionAreaStorage = new node_async_hooks_1.AsyncLocalStorage();
+function runZLinkExecutionArea(area, operation) {
+    return executionAreaStorage.run(area, operation);
+}
+function currentZLinkExecutionArea() {
+    return executionAreaStorage.getStore();
+}
+function requireZLinkInfrastructureExecutionArea() {
+    if (currentZLinkExecutionArea() !== 'infrastructure') {
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, 'Infrastructure-only work requires the infrastructure execution area.');
+    }
+}
+class ZLinkSpotSerialTurn {
+    postResume;
+    executionClaim;
+    yieldAllowed;
+    suspendedResolve;
+    suspendedPromise;
+    suspendSignaled = false;
+    owner;
+    frameworkOperationsBlocked = false;
+    constructor(postResume, executionClaim, yieldAllowed) {
+        this.postResume = postResume;
+        this.executionClaim = executionClaim;
+        this.yieldAllowed = yieldAllowed;
+    }
+    bindExecutionClaim(claim) {
+        if (this.executionClaim !== undefined) {
+            throw new Error('ZLink Spot serial turn already owns an execution claim.');
+        }
+        this.executionClaim = claim;
+    }
+    get isSuspended() {
+        return this.suspendSignaled;
+    }
+    releaseBoundExecutionClaim() {
+        this.executionClaim?.release();
+        this.executionClaim = undefined;
+    }
+    get suspended() {
+        if (this.suspendSignaled) {
+            return Promise.resolve();
+        }
+        this.suspendedPromise ??= new Promise((resolve) => {
+            this.suspendedResolve = resolve;
+        });
+        return this.suspendedPromise;
+    }
+    bindOwner(owner) {
+        this.owner = owner;
+    }
+    blockFrameworkOperations() {
+        this.frameworkOperationsBlocked = true;
+    }
+    ensureFrameworkOperationAllowed() {
+        if (this.frameworkOperationsBlocked) {
+            throw new Error('A Spot handler cannot start another Framework operation after relocationReady().defer().');
+        }
+    }
+    resetSuspension() {
+        this.suspendSignaled = false;
+        this.suspendedResolve = undefined;
+        this.suspendedPromise = undefined;
+    }
+    async yieldPromise(pending) {
+        if (!this.yieldAllowed) {
+            throw new configuration_1.ZLinkConfigurationException('yield requires a SpotWide User Spot or Instance Spot application handler.');
+        }
+        return await this.yieldFrameworkPromise(pending);
+    }
+    /** Suspends a turn only for a Framework-owned lifecycle boundary. */
+    async yieldFrameworkPromise(pending) {
+        this.signalSuspended();
+        const result = await pending;
+        await this.awaitResumePermit();
+        return result;
+    }
+    async resumeOwnerUntilNextYield() {
+        const owner = this.owner;
+        if (owner === undefined) {
+            return;
+        }
+        await Promise.race([
+            owner.then(() => undefined, () => undefined),
+            this.suspended
+        ]);
+    }
+    signalSuspended() {
+        if (this.suspendSignaled) {
+            return;
+        }
+        this.suspendSignaled = true;
+        this.releaseBoundExecutionClaim();
+        this.suspendedResolve?.();
+    }
+    awaitResumePermit() {
+        return new Promise((resolve, reject) => {
+            if (!this.postResume(this, resolve, reject)) {
+                reject(new Error('ZLink Spot serial executor is closed.'));
+            }
+        });
+    }
+}
+exports.ZLinkSpotSerialTurn = ZLinkSpotSerialTurn;
+function runZLinkSpotSerialTurn(executor, turnId, turn, operation) {
+    return runZLinkExecutionArea('application', () => spotSerialTurnStorage.run({ executor, turnId, turn }, async () => operation()));
+}
+function captureZLinkSpotSerialTurn(executor) {
+    const current = spotSerialTurnStorage.getStore();
+    if (current === undefined) {
+        return undefined;
+    }
+    if (executor !== undefined && current.executor !== executor) {
+        return undefined;
+    }
+    return current.turn;
+}
+/** Returns the physical Spot owner only while its captured turn owns the gate. */
+function currentZLinkSpotSerialSourceId() {
+    const current = spotSerialTurnStorage.getStore();
+    if (current === undefined
+        || !current.executor.isActiveTurn(current.turn, current.turnId)) {
+        return undefined;
+    }
+    return current.executor.sourceSpotId;
+}
+function requireZLinkYieldTurn(capturedTurn) {
+    const turn = capturedTurn ?? captureZLinkSpotSerialTurn();
+    if (turn === undefined || !turn.yieldAllowed) {
+        throw new configuration_1.ZLinkConfigurationException('yield requires a SpotWide User Spot or Instance Spot application handler.');
+    }
+    return turn;
+}
+function captureZLinkExecutionTurn() {
+    const current = spotSerialTurnStorage.getStore();
+    if (current === undefined) {
+        return undefined;
+    }
+    return {
+        yieldPromise: (pending) => current.turn.yieldPromise(pending),
+        post: (callback) => { void current.executor.post(callback); }
+    };
+}
+function isCurrentZLinkSpotSerialTurn(executor) {
+    const current = spotSerialTurnStorage.getStore();
+    return current !== undefined
+        && current.executor === executor
+        && executor.isActiveTurn(current.turn, current.turnId);
+}
+/**
+ * Seals application-lane admission and waits for every active Promise turn to
+ * finish. A seal generation prevents a stale abort from reopening a newer
+ * lifecycle barrier.
+ */
+class ZLinkExecutionBarrier {
+    generation = 0n;
+    activeClaims = 0;
+    currentSeal;
+    admissionWaiters = [];
+    quiescenceWaiters = new Set();
+    committed = false;
+    async enter() {
+        if (this.committed) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotMoving, 'ZLink execution barrier is committed.');
+        }
+        if (this.currentSeal !== undefined) {
+            return await new Promise((resolve, reject) => {
+                this.admissionWaiters.push({ resolve, reject });
+            });
+        }
+        return this.createClaim();
+    }
+    /**
+     * Re-enters a previously yielded application turn only while admission is
+     * open. A continuation must fail instead of waiting behind a relocation
+     * seal that already won the turn-boundary race.
+     */
+    tryEnter() {
+        if (this.committed || this.currentSeal !== undefined) {
+            return undefined;
+        }
+        return this.createClaim();
+    }
+    seal() {
+        if (this.committed) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotMoving, 'ZLink execution barrier is committed.');
+        }
+        if (this.currentSeal !== undefined) {
+            throw new Error('ZLink execution barrier is already sealed.');
+        }
+        const seal = Object.freeze({ generation: ++this.generation });
+        this.currentSeal = seal;
+        return seal;
+    }
+    async waitForQuiescence(seal, signal) {
+        this.requireCurrent(seal);
+        if (this.activeClaims === 0)
+            return;
+        if (signal?.aborted === true)
+            throw signal.reason;
+        await new Promise((resolve, reject) => {
+            const complete = () => {
+                signal?.removeEventListener('abort', abort);
+                resolve();
+            };
+            const abort = () => {
+                this.quiescenceWaiters.delete(complete);
+                reject(signal?.reason);
+            };
+            this.quiescenceWaiters.add(complete);
+            signal?.addEventListener('abort', abort, { once: true });
+        });
+        this.requireCurrent(seal);
+    }
+    abort(seal) {
+        if (!this.isCurrent(seal))
+            return false;
+        this.currentSeal = undefined;
+        for (const waiter of this.admissionWaiters)
+            waiter.resolve(this.createClaim());
+        this.admissionWaiters.length = 0;
+        return true;
+    }
+    commit(seal) {
+        if (!this.isCurrent(seal))
+            return false;
+        this.currentSeal = undefined;
+        this.committed = true;
+        const error = (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotMoving, 'ZLink execution barrier is committed.');
+        for (const waiter of this.admissionWaiters)
+            waiter.reject(error);
+        this.admissionWaiters.length = 0;
+        return true;
+    }
+    isCurrent(seal) {
+        return this.currentSeal?.generation === seal.generation;
+    }
+    createClaim() {
+        this.activeClaims++;
+        let released = false;
+        return {
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                this.activeClaims--;
+                if (this.activeClaims === 0) {
+                    for (const waiter of this.quiescenceWaiters)
+                        waiter();
+                    this.quiescenceWaiters.clear();
+                }
+            }
+        };
+    }
+    requireCurrent(seal) {
+        if (!this.isCurrent(seal)) {
+            throw new Error(`ZLink execution barrier generation '${seal.generation}' is stale.`);
+        }
+    }
+}
+exports.ZLinkExecutionBarrier = ZLinkExecutionBarrier;
+class ZLinkRuntimeTaskErrorSink {
+    handlers = new Set();
+    onRuntimeTaskException(handler) {
+        this.handlers.add(handler);
+        return () => {
+            this.handlers.delete(handler);
+        };
+    }
+    reportHandlerException(error) {
+        this.reportRuntimeTaskException('handler', error);
+    }
+    reportRuntimeTaskException(taskName, error) {
+        for (const handler of this.handlers) {
+            try {
+                handler({ taskName, error });
+            }
+            catch {
+                // Error sinks must not create a second unhandled failure path.
+            }
+        }
+    }
+}
+exports.ZLinkRuntimeTaskErrorSink = ZLinkRuntimeTaskErrorSink;
+class ZLinkRuntimeTaskRunner {
+    errorSink;
+    shutdownSignal;
+    constructor(errorSink, shutdownSignal) {
+        this.errorSink = errorSink;
+        this.shutdownSignal = shutdownSignal;
+    }
+    runDetached(taskName, callback) {
+        void this.run(taskName, callback);
+    }
+    run(taskName, callback) {
+        return Promise.resolve()
+            .then(() => callback(this.shutdownSignal))
+            .catch((error) => {
+            if (isCancellationError(error, this.shutdownSignal)) {
+                return;
+            }
+            this.errorSink.reportRuntimeTaskException(taskName, error);
+        });
+    }
+    reportErrorSinkFailure(_taskName, _error) {
+        // Mirrors the dotnet no-op: a broken error sink must not fail the runtime.
+    }
+}
+exports.ZLinkRuntimeTaskRunner = ZLinkRuntimeTaskRunner;
+class ZLinkFrameworkExecutionState {
+    context;
+    abortController = new AbortController();
+    errorSink = new ZLinkRuntimeTaskErrorSink();
+    taskRunner = new ZLinkRuntimeTaskRunner(this.errorSink, this.abortController.signal);
+    listenerTasks = [];
+    constructor(context) {
+        this.context = context;
+    }
+    async dispose() {
+        this.abortController.abort();
+        await this.waitForListenerTasks();
+        await this.context.dispose();
+    }
+    async waitForListenerTasks() {
+        if (this.listenerTasks.length === 0) {
+            return;
+        }
+        try {
+            await Promise.all(this.listenerTasks);
+        }
+        catch (error) {
+            if (!isCancellationError(error, this.abortController.signal)) {
+                this.errorSink.reportRuntimeTaskException('listener', error);
+            }
+        }
+    }
+}
+exports.ZLinkFrameworkExecutionState = ZLinkFrameworkExecutionState;
+function isCancellationError(error, signal) {
+    if ((0, abort_1.isAbortError)(error)) {
+        return true;
+    }
+    return signal?.aborted === true && error === signal.reason;
+}

package/dist/runtime/execution/serial-execution-queue.d.ts

@@ -0,0 +1,94 @@
+export type ZLinkSerialWorkLane = 'application' | 'lifecycle';
+export interface ZLinkSerialWorkOptions {
+    readonly lane?: ZLinkSerialWorkLane;
+    readonly payloadBytes?: number;
+    readonly metadataBytes?: number;
+}
+/** Internal per-owner reservation limits, never a shared ingress budget. */
+export interface ZLinkSerialSchedulerOptions {
+    readonly applicationMessageCapacity?: number;
+    readonly applicationByteCapacity?: number;
+    readonly lifecycleMessageCapacity?: number;
+    readonly lifecycleByteCapacity?: number;
+    readonly ownerTimeBudget?: number;
+    readonly lifecycleBurstLimit?: number;
+    readonly fixedWorkByteCost?: number;
+    readonly capacityError?: (lane: ZLinkSerialWorkLane) => unknown;
+}
+export declare const ZLINK_DEFAULT_SERIAL_SCHEDULER_OPTIONS: Required<Omit<ZLinkSerialSchedulerOptions, 'capacityError'>>;
+export interface ZLinkSerialWorkRecord<T> {
+    readonly acceptedSequence: bigint;
+    readonly lane: ZLinkSerialWorkLane;
+    readonly byteCost: number;
+    readonly operation: () => Promise<T> | T;
+    readonly context?: unknown;
+    resolve(value: T): void;
+    reject(reason: unknown): void;
+    /** Releases this owner's reservation exactly once after the real terminal. */
+    release(): void;
+    fail(reason: unknown): void;
+}
+/** Readiness work that must complete without claiming the serial owner. */
+export interface ZLinkSerialWorkPreparation {
+    prepare(signal: AbortSignal): Promise<void>;
+    cancel(): void;
+}
+/**
+ * One event-loop serial execution queue per Spot, Actor mailbox, or Stream session.
+ * Its reservations are owner-local and span queued plus running work until the
+ * execution owner reaches its terminal transition.
+ */
+export declare class ZLinkSerialExecutionQueue {
+    private readonly executeRecord;
+    private readonly application;
+    private readonly lifecycle;
+    private readonly ownerTimeBudget;
+    private readonly lifecycleBurstLimit;
+    private readonly fixedWorkByteCost;
+    private readonly capacityError;
+    private nextAcceptedSequence;
+    private draining;
+    private drainScheduled;
+    private lifecycleStreak;
+    private lifecycleDebt;
+    private claimStartedAt?;
+    private closed;
+    private readonly idleWaiters;
+    constructor(executeRecord: (record: ZLinkSerialWorkRecord<unknown>) => Promise<void>, options?: ZLinkSerialSchedulerOptions);
+    submit<T>(operation: () => Promise<T> | T, options?: ZLinkSerialWorkOptions, context?: unknown): Promise<T>;
+    submitDetached<T>(operation: () => Promise<T> | T, onError: (error: unknown) => void, options?: ZLinkSerialWorkOptions, context?: unknown): void;
+    /**
+     * Enqueues a continuation for an already-reserved owner turn. It preserves
+     * application FIFO order without taking a second owner-local reservation.
+     */
+    submitContinuation<T>(operation: () => Promise<T> | T, context?: unknown): Promise<T>;
+    /**
+     * Enqueues work that already owns the host-wide application job permit.
+     * Its owner-local reservation transfers from the mailbox without a second
+     * capacity decision and remains held through handler terminal completion.
+     */
+    submitPreAdmitted<T>(operation: () => Promise<T> | T, options?: ZLinkSerialWorkOptions, context?: unknown): Promise<T>;
+    snapshot(): {
+        readonly applicationMessages: number;
+        readonly applicationBytes: number;
+        readonly lifecycleMessages: number;
+        readonly lifecycleBytes: number;
+    };
+    get hasPendingWork(): boolean;
+    whenIdle(): Promise<void>;
+    /** Stops new submissions while allowing the accepted FIFO to finish. */
+    close(): Promise<void>;
+    private admit;
+    private byteCost;
+    private scheduleDrain;
+    private drain;
+    private selectNext;
+    private takeSelected;
+    private takeLifecycle;
+    private takeApplication;
+    private startPreparation;
+    /** Returns false while an outstanding readiness attempt is being canceled. */
+    private cancelPreparationForRearbitration;
+    private shouldYield;
+    private resolveIdleWaiters;
+}