@zlink-systems/framework 0.10.0

package/dist/runtime/execution/serial-execution-queue.js

@@ -0,0 +1,411 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSerialExecutionQueue = exports.ZLINK_DEFAULT_SERIAL_SCHEDULER_OPTIONS = void 0;
+exports.ZLINK_DEFAULT_SERIAL_SCHEDULER_OPTIONS = Object.freeze({
+    applicationMessageCapacity: 1_024,
+    applicationByteCapacity: 64 * 1024 * 1024,
+    lifecycleMessageCapacity: 128,
+    lifecycleByteCapacity: 4 * 1024 * 1024,
+    ownerTimeBudget: 10,
+    lifecycleBurstLimit: 8,
+    fixedWorkByteCost: 256
+});
+const MAX_SAFE_INTEGER = Number.MAX_SAFE_INTEGER;
+/**
+ * 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.
+ */
+class ZLinkSerialExecutionQueue {
+    executeRecord;
+    application;
+    lifecycle;
+    ownerTimeBudget;
+    lifecycleBurstLimit;
+    fixedWorkByteCost;
+    capacityError;
+    nextAcceptedSequence = 1n;
+    draining = false;
+    drainScheduled = false;
+    lifecycleStreak = 0;
+    lifecycleDebt = false;
+    claimStartedAt;
+    closed = false;
+    idleWaiters = [];
+    constructor(executeRecord, options = {}) {
+        this.executeRecord = executeRecord;
+        const configured = { ...exports.ZLINK_DEFAULT_SERIAL_SCHEDULER_OPTIONS, ...options };
+        validatePositive(configured.applicationMessageCapacity, 'applicationMessageCapacity');
+        validatePositive(configured.applicationByteCapacity, 'applicationByteCapacity');
+        validatePositive(configured.lifecycleMessageCapacity, 'lifecycleMessageCapacity');
+        validatePositive(configured.lifecycleByteCapacity, 'lifecycleByteCapacity');
+        validateNonNegative(configured.ownerTimeBudget, 'ownerTimeBudget');
+        validatePositive(configured.lifecycleBurstLimit, 'lifecycleBurstLimit');
+        validatePositive(configured.fixedWorkByteCost, 'fixedWorkByteCost');
+        this.application = createLane(configured.applicationMessageCapacity, configured.applicationByteCapacity);
+        this.lifecycle = createLane(configured.lifecycleMessageCapacity, configured.lifecycleByteCapacity);
+        this.ownerTimeBudget = configured.ownerTimeBudget;
+        this.lifecycleBurstLimit = configured.lifecycleBurstLimit;
+        this.fixedWorkByteCost = configured.fixedWorkByteCost;
+        this.capacityError = options.capacityError
+            ?? (lane => new Error(`The ${lane} execution queue is full.`));
+    }
+    submit(operation, options = {}, context) {
+        try {
+            return this.admit(operation, options, context);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+    submitDetached(operation, onError, options = {}, context) {
+        void this.submit(operation, options, context).catch(onError);
+    }
+    /**
+     * Enqueues a continuation for an already-reserved owner turn. It preserves
+     * application FIFO order without taking a second owner-local reservation.
+     */
+    submitContinuation(operation, context) {
+        try {
+            return this.admit(operation, { lane: 'application' }, context, 'none');
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+    /**
+     * Atomically transfers an already-accepted durable FIFO prefix into this
+     * owner queue. Admission failures remain synchronous so the durable owner
+     * cannot publish a restore linearization point for a prefix that was never
+     * queued.
+     *
+     * @internal
+     */
+    admitDurablePrefix(operation, options = {}, context, preparation) {
+        return this.admit(operation, { ...options, lane: 'application' }, context, 'transferred', preparation);
+    }
+    /**
+     * 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(operation, options = {}, context) {
+        return this.admit(operation, options, context, 'transferred');
+    }
+    snapshot() {
+        return {
+            applicationMessages: this.application.messageCount,
+            applicationBytes: this.application.byteCount,
+            lifecycleMessages: this.lifecycle.messageCount,
+            lifecycleBytes: this.lifecycle.byteCount
+        };
+    }
+    get hasPendingWork() {
+        return this.draining
+            || this.application.records.length > 0
+            || this.lifecycle.records.length > 0;
+    }
+    whenIdle() {
+        if (!this.hasPendingWork)
+            return Promise.resolve();
+        return new Promise(resolve => this.idleWaiters.push(resolve));
+    }
+    /** Stops new submissions while allowing the accepted FIFO to finish. */
+    close() {
+        this.closed = true;
+        return this.whenIdle();
+    }
+    admit(operation, options, context, reservationMode = 'enforce-capacity', preparation) {
+        if (this.closed)
+            throw new Error('The serial execution queue is closed.');
+        const lane = options.lane ?? 'application';
+        const reservationHeld = reservationMode !== 'none';
+        const byteCost = reservationHeld ? this.byteCost(options) : 0;
+        const target = lane === 'application' ? this.application : this.lifecycle;
+        if (reservationMode === 'enforce-capacity' && !reserve(target, byteCost)) {
+            throw this.capacityError(lane);
+        }
+        if (reservationMode === 'transferred')
+            reserveTransferred(target, byteCost);
+        let settled = false;
+        let released = false;
+        let resolveResult;
+        let rejectResult;
+        const result = new Promise((resolve, reject) => {
+            resolveResult = resolve;
+            rejectResult = reject;
+        });
+        const release = () => {
+            if (released)
+                return;
+            released = true;
+            if (reservationHeld)
+                releaseReservation(target, byteCost);
+        };
+        const resolve = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolveResult(value);
+        };
+        const reject = (reason) => {
+            if (settled)
+                return;
+            settled = true;
+            rejectResult(reason);
+        };
+        const record = {
+            acceptedSequence: 0n,
+            lane,
+            byteCost,
+            operation,
+            context,
+            preparation,
+            preparationState: preparation === undefined ? 'ready' : 'idle',
+            resolve,
+            reject,
+            release,
+            fail: (reason) => {
+                reject(reason);
+                release();
+            }
+        };
+        const previousLength = target.records.length;
+        try {
+            record.acceptedSequence = this.nextAcceptedSequence;
+            target.records.push(record);
+            this.nextAcceptedSequence += 1n;
+        }
+        catch (error) {
+            target.records.length = previousLength;
+            record.acceptedSequence = 0n;
+            release();
+            throw error;
+        }
+        this.scheduleDrain();
+        return result;
+    }
+    byteCost(options) {
+        const payloadBytes = options.payloadBytes ?? 0;
+        const metadataBytes = options.metadataBytes ?? 0;
+        validateNonNegative(payloadBytes, 'payloadBytes');
+        validateNonNegative(metadataBytes, 'metadataBytes');
+        if (payloadBytes > MAX_SAFE_INTEGER - metadataBytes)
+            return MAX_SAFE_INTEGER;
+        const payloadAndMetadata = payloadBytes + metadataBytes;
+        return payloadAndMetadata > MAX_SAFE_INTEGER - this.fixedWorkByteCost
+            ? MAX_SAFE_INTEGER
+            : payloadAndMetadata + this.fixedWorkByteCost;
+    }
+    scheduleDrain() {
+        if (this.drainScheduled || this.draining)
+            return;
+        this.drainScheduled = true;
+        queueMicrotask(() => {
+            this.drainScheduled = false;
+            void this.drain();
+        });
+    }
+    async drain() {
+        if (this.draining)
+            return;
+        this.draining = true;
+        let waitingForPreparation = false;
+        try {
+            for (;;) {
+                const selection = this.selectNext();
+                if (selection === undefined)
+                    break;
+                const record = selection.record;
+                if (selection.lane === 'lifecycle') {
+                    const applicationHead = this.application.records[0];
+                    if (this.application.records.length > 0
+                        && !this.cancelPreparationForRearbitration(applicationHead)) {
+                        waitingForPreparation = true;
+                        break;
+                    }
+                }
+                if (record.preparationState === 'idle') {
+                    this.startPreparation(record);
+                    waitingForPreparation = true;
+                    break;
+                }
+                if (record.preparationState === 'pending'
+                    || record.preparationState === 'canceling') {
+                    waitingForPreparation = true;
+                    break;
+                }
+                this.takeSelected(selection);
+                if (record.preparationState === 'failed') {
+                    record.preparation?.cancel();
+                    record.fail(record.preparationError);
+                    continue;
+                }
+                this.claimStartedAt ??= performance.now();
+                try {
+                    await this.executeRecord(record);
+                }
+                catch (error) {
+                    record.fail(error);
+                }
+                finally {
+                    record.preparation?.cancel();
+                }
+                if (this.shouldYield()) {
+                    this.claimStartedAt = undefined;
+                    await macrotaskBoundary();
+                }
+            }
+        }
+        finally {
+            this.draining = false;
+            this.claimStartedAt = undefined;
+            if (!waitingForPreparation
+                && (this.application.records.length > 0 || this.lifecycle.records.length > 0)) {
+                this.scheduleDrain();
+            }
+            else {
+                if (this.application.records.length === 0 && this.lifecycle.records.length === 0) {
+                    this.resolveIdleWaiters();
+                }
+            }
+        }
+    }
+    selectNext() {
+        const applicationReady = this.application.records.length > 0;
+        const lifecycleReady = this.lifecycle.records.length > 0;
+        if (!applicationReady && !lifecycleReady)
+            return undefined;
+        if (!applicationReady) {
+            return { lane: 'lifecycle', record: this.lifecycle.records[0] };
+        }
+        if (!lifecycleReady) {
+            return { lane: 'application', record: this.application.records[0] };
+        }
+        if (!this.lifecycleDebt && this.lifecycleStreak < this.lifecycleBurstLimit) {
+            return { lane: 'lifecycle', record: this.lifecycle.records[0] };
+        }
+        return { lane: 'application', record: this.application.records[0] };
+    }
+    takeSelected(selection) {
+        const record = selection.lane === 'lifecycle'
+            ? this.takeLifecycle()
+            : this.takeApplication();
+        if (record !== selection.record) {
+            throw new Error('The selected serial work record changed before owner claim.');
+        }
+        return record;
+    }
+    takeLifecycle() {
+        this.lifecycleStreak += 1;
+        if (this.application.records.length > 0
+            && this.lifecycleStreak >= this.lifecycleBurstLimit) {
+            this.lifecycleDebt = true;
+        }
+        return this.lifecycle.records.shift();
+    }
+    takeApplication() {
+        this.lifecycleStreak = 0;
+        this.lifecycleDebt = false;
+        return this.application.records.shift();
+    }
+    startPreparation(record) {
+        const preparation = record.preparation;
+        if (preparation === undefined || record.preparationState !== 'idle')
+            return;
+        const controller = new AbortController();
+        record.preparationController = controller;
+        record.preparationError = undefined;
+        record.preparationState = 'pending';
+        void Promise.resolve()
+            .then(() => preparation.prepare(controller.signal))
+            .then(() => {
+            if (record.preparationState === 'canceling' || controller.signal.aborted) {
+                preparation.cancel();
+                record.preparationState = 'idle';
+            }
+            else {
+                record.preparationState = 'ready';
+            }
+            record.preparationController = undefined;
+            this.scheduleDrain();
+        }, error => {
+            if (record.preparationState === 'canceling' || controller.signal.aborted) {
+                preparation.cancel();
+                record.preparationState = 'idle';
+            }
+            else {
+                record.preparationError = error;
+                record.preparationState = 'failed';
+            }
+            record.preparationController = undefined;
+            this.scheduleDrain();
+        });
+    }
+    /** Returns false while an outstanding readiness attempt is being canceled. */
+    cancelPreparationForRearbitration(record) {
+        if (record.preparation === undefined || record.preparationState === 'idle')
+            return true;
+        if (record.preparationState === 'ready') {
+            record.preparation.cancel();
+            record.preparationState = 'idle';
+            return true;
+        }
+        if (record.preparationState === 'failed')
+            return true;
+        if (record.preparationState === 'pending') {
+            record.preparationState = 'canceling';
+            record.preparationController?.abort(new Error('Serial work readiness was re-arbitrated by the lifecycle lane.'));
+        }
+        return false;
+    }
+    shouldYield() {
+        if (this.ownerTimeBudget === 0 || !this.hasPendingWork)
+            return false;
+        return performance.now() - (this.claimStartedAt ?? performance.now()) >= this.ownerTimeBudget;
+    }
+    resolveIdleWaiters() {
+        for (const resolve of this.idleWaiters.splice(0))
+            resolve();
+    }
+}
+exports.ZLinkSerialExecutionQueue = ZLinkSerialExecutionQueue;
+function createLane(messageCapacity, byteCapacity) {
+    return {
+        records: [],
+        messageCapacity,
+        byteCapacity,
+        messageCount: 0,
+        byteCount: 0
+    };
+}
+function reserve(lane, byteCost) {
+    if (lane.messageCount >= lane.messageCapacity
+        || byteCost > lane.byteCapacity - lane.byteCount) {
+        return false;
+    }
+    lane.messageCount += 1;
+    lane.byteCount += byteCost;
+    return true;
+}
+function reserveTransferred(lane, byteCost) {
+    lane.messageCount += 1;
+    lane.byteCount += byteCost;
+}
+function releaseReservation(lane, byteCost) {
+    lane.messageCount -= 1;
+    lane.byteCount -= byteCost;
+}
+function validatePositive(value, field) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new RangeError(`${field} must be a positive safe integer.`);
+    }
+}
+function validateNonNegative(value, field) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError(`${field} must be a non-negative safe integer.`);
+    }
+}
+function macrotaskBoundary() {
+    return new Promise(resolve => setImmediate(resolve));
+}

package/dist/runtime/execution/serial-work-size.d.ts

@@ -0,0 +1,4 @@
+import type { ZLinkSerialWorkOptions } from './serial-execution-queue';
+/** Returns UTF-8 metadata bytes for the owning serial reservation. */
+export declare function zlinkMetadataByteLength(metadata: ReadonlyMap<string, string> | Readonly<Record<string, string>> | undefined): number;
+export declare function zlinkSerialWorkOptions(payloadBytes: number, metadataBytes: number): ZLinkSerialWorkOptions;

package/dist/runtime/execution/serial-work-size.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.zlinkMetadataByteLength = zlinkMetadataByteLength;
+exports.zlinkSerialWorkOptions = zlinkSerialWorkOptions;
+/** Returns UTF-8 metadata bytes for the owning serial reservation. */
+function zlinkMetadataByteLength(metadata) {
+    if (metadata === undefined)
+        return 0;
+    let bytes = 0;
+    if (metadata instanceof Map) {
+        for (const [key, value] of metadata) {
+            bytes += Buffer.byteLength(key, 'utf8') + Buffer.byteLength(value, 'utf8');
+        }
+        return bytes;
+    }
+    //  Iterate keys directly; Object.entries would allocate a pairs array per
+    //  message on the dispatch hot path.
+    const record = metadata;
+    for (const key in record) {
+        if (Object.prototype.hasOwnProperty.call(record, key)) {
+            bytes += Buffer.byteLength(key, 'utf8') + Buffer.byteLength(record[key], 'utf8');
+        }
+    }
+    return bytes;
+}
+function zlinkSerialWorkOptions(payloadBytes, metadataBytes) {
+    return { payloadBytes, metadataBytes };
+}

package/dist/runtime/execution/state-lane.d.ts

@@ -0,0 +1,28 @@
+type ZLinkStateLaneWork<T> = () => Promise<T> | T;
+/**
+ * Single-owner execution lane for a component's mutable state.
+ *
+ * State owned by a lane is accessed only through its turns, so its collections
+ * remain ordinary JavaScript collections. This is separate from the Spot and
+ * Actor serial executors, which also own lifecycle and relocation concerns.
+ */
+export declare class ZLinkStateLane {
+    private static readonly currentLaneStorage;
+    private readonly mailbox;
+    private draining;
+    private drainPromise;
+    private closed;
+    static get current(): ZLinkStateLane | undefined;
+    get isOnLane(): boolean;
+    /** Runs work on the lane and resolves with its result. */
+    run<T>(work: ZLinkStateLaneWork<T>): Promise<T>;
+    /** Queues work without waiting for its result. */
+    tryPost(work: ZLinkStateLaneWork<void>): boolean;
+    /** Fails at the recursive call site instead of waiting for this lane's current turn. */
+    throwIfReentrant(): void;
+    /** Closes admission and waits for work already in the mailbox. */
+    dispose(): Promise<void>;
+    private scheduleDrain;
+    private drain;
+}
+export {};

package/dist/runtime/execution/state-lane.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkStateLane = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+/**
+ * Single-owner execution lane for a component's mutable state.
+ *
+ * State owned by a lane is accessed only through its turns, so its collections
+ * remain ordinary JavaScript collections. This is separate from the Spot and
+ * Actor serial executors, which also own lifecycle and relocation concerns.
+ */
+class ZLinkStateLane {
+    static currentLaneStorage = new node_async_hooks_1.AsyncLocalStorage();
+    mailbox = [];
+    draining = false;
+    drainPromise;
+    closed = false;
+    static get current() {
+        return ZLinkStateLane.currentLaneStorage.getStore();
+    }
+    get isOnLane() {
+        return ZLinkStateLane.current === this;
+    }
+    /** Runs work on the lane and resolves with its result. */
+    run(work) {
+        this.throwIfReentrant();
+        if (this.closed) {
+            throw new Error('ZLink state lane is closed.');
+        }
+        let resolve;
+        let reject;
+        const completion = new Promise((complete, fail) => {
+            resolve = complete;
+            reject = fail;
+        });
+        this.mailbox.push(async () => {
+            try {
+                resolve(await work());
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+        this.scheduleDrain();
+        return completion;
+    }
+    /** Queues work without waiting for its result. */
+    tryPost(work) {
+        if (this.closed) {
+            return false;
+        }
+        this.mailbox.push(async () => {
+            await work();
+        });
+        this.scheduleDrain();
+        return true;
+    }
+    /** Fails at the recursive call site instead of waiting for this lane's current turn. */
+    throwIfReentrant() {
+        if (this.isOnLane) {
+            throw new Error('This code already runs on the state lane it is trying to enter. Call the component\'s '
+                + 'private state method directly instead of re-entering its public surface.');
+        }
+    }
+    /** Closes admission and waits for work already in the mailbox. */
+    async dispose() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.scheduleDrain();
+        await this.drainPromise;
+    }
+    scheduleDrain() {
+        if (this.draining) {
+            return;
+        }
+        this.draining = true;
+        this.drainPromise = this.drain();
+    }
+    async drain() {
+        try {
+            for (;;) {
+                const work = this.mailbox.shift();
+                if (work === undefined) {
+                    return;
+                }
+                try {
+                    await ZLinkStateLane.currentLaneStorage.run(this, work);
+                }
+                catch {
+                    // Posted callbacks own their errors. One failure must not strand later work.
+                }
+            }
+        }
+        finally {
+            this.draining = false;
+            this.drainPromise = undefined;
+            if (this.mailbox.length > 0) {
+                this.scheduleDrain();
+            }
+        }
+    }
+}
+exports.ZLinkStateLane = ZLinkStateLane;

package/dist/runtime/foundation/actor-join-recovery-codec.d.ts

@@ -0,0 +1,72 @@
+import type { RoutingId, ZLinkActorJoinOperationId } from '../../contracts';
+export interface CanonicalActorJoinRecoveryRequest {
+    readonly actorId: string;
+    readonly actorType: string;
+    readonly handoffId: string;
+    readonly sourceSpotId: string;
+    readonly sourceNodeRid: RoutingId;
+    readonly actorGeneration: bigint;
+    readonly actorAuthorityOwnerGeneration: bigint;
+    readonly actorNodeGeneration: bigint;
+    readonly expectedOwnerLeaseGeneration: bigint;
+    readonly relocationId: string;
+    readonly relocationContentType: string;
+    readonly requestContentType: string;
+    readonly request: Uint8Array;
+    readonly targetSpotId: string;
+    readonly targetNodeRid: RoutingId;
+    readonly targetNodeGeneration: bigint;
+    readonly targetSpotGeneration: bigint;
+    readonly targetAuthorityOwnerGeneration: bigint;
+    readonly targetSpotAuthorityOwnerGeneration: bigint;
+    readonly coordinator: {
+        readonly ownerId: string;
+        readonly leaseGeneration: bigint;
+        readonly nodeRid: RoutingId;
+        readonly nodeGeneration: bigint;
+        readonly expectedAuthorityStoreVersion: string;
+    };
+    readonly operationId?: ZLinkActorJoinOperationId;
+    readonly replyContentType?: string;
+    readonly reply?: Uint8Array;
+}
+export interface CanonicalActorJoinRecovery {
+    readonly source: {
+        readonly nodeRid: string;
+        readonly nodeGeneration: bigint;
+        readonly ownerId: string;
+        readonly ownerLeaseGeneration: bigint;
+    };
+    readonly request: {
+        readonly actorId: string;
+        readonly actorType: string;
+        readonly handoffId: string;
+        readonly sourceSpotId: string;
+        readonly sourceNodeRid: Buffer;
+        readonly actorGeneration: bigint;
+        readonly actorAuthorityOwnerGeneration: bigint;
+        readonly relocationAggregateId: string;
+        readonly requestContentType: string;
+        readonly request: Buffer;
+        readonly reservationToken: string;
+        readonly reservedPayloadBytes: bigint;
+    };
+    readonly targetSpotId: string;
+    readonly targetNodeRid: Buffer;
+    readonly targetNodeGeneration: bigint;
+    readonly targetSpotGeneration: bigint;
+    readonly targetAuthorityOwnerGeneration: bigint;
+    readonly operationId?: ZLinkActorJoinOperationId;
+    readonly replyContentType?: string;
+    readonly reply: Buffer;
+}
+export declare function canonicalActorJoinHandoffId(input: {
+    readonly sourceActorNodeRid: Uint8Array;
+    readonly actorId: string;
+    readonly actorGeneration: bigint;
+    readonly sourceActorNodeGeneration: bigint;
+    readonly correlation: bigint;
+}): string;
+export declare function encodeCanonicalActorJoinRecoverySavedWork(input: CanonicalActorJoinRecoveryRequest): Buffer;
+export declare function decodeCanonicalActorJoinRecoverySavedWork(encoded: Uint8Array): CanonicalActorJoinRecovery | undefined;
+export declare function routingIdBytes(value: RoutingId): Buffer;