@zlink-systems/framework 0.27.0 → 0.29.0

package/dist/runtime/locations/domain-store-contract.d.ts

@@ -25,6 +25,7 @@ export interface ZLinkDomainLocationStore {
     reserve(request: ZLinkObjectReserveRequest, signal?: AbortSignal, deadlineUnixMs?: bigint): Promise<ZLinkObjectReserveResult>;
     commit(request: ZLinkObjectCommitRequest, signal?: AbortSignal, deadlineUnixMs?: bigint): Promise<ZLinkObjectCommitResult>;
     completeCreation(request: ZLinkObjectCreationCompleteRequest, signal?: AbortSignal): Promise<ZLinkObjectCreationCompleteResult>;
+    releaseEndedReservation?(key: ZLinkAuthorityKey, expectedStoreVersion: string, signal?: AbortSignal): Promise<boolean>;
     abort(request: ZLinkObjectAbortRequest, signal?: AbortSignal, deadlineUnixMs?: bigint): Promise<ZLinkObjectAbortResult>;
     prepareAggregate(request: ZLinkAggregatePrepareRequest, signal?: AbortSignal): Promise<ZLinkAggregatePrepareResult>;
     commitAggregate(fence: ZLinkAggregateFence, signal?: AbortSignal): Promise<ZLinkAggregateCommitResult>;

package/dist/runtime/locations/in-memory-authority-store.d.ts

@@ -26,6 +26,8 @@ export declare class ZLinkInMemoryAuthorityStore {
     compareExchangeAuthority(key: ZLinkAuthorityKey, expectedStoreVersion: ZLinkAuthorityStoreVersion, mutation: ZLinkAuthorityMutation, signal?: AbortSignal): Promise<ZLinkAuthorityCompareExchangeResult>;
     listAuthorities(prefix: string, cursor: ZLinkAuthorityScanCursor | undefined, limit: number, signal?: AbortSignal): Promise<ZLinkAuthorityScanResult>;
     removeAllByOwner(owner: ZLinkLocationOwnerToken, signal?: AbortSignal): Promise<bigint>;
+    releaseEndedReservation(key: ZLinkAuthorityKey, expectedStoreVersion: string, signal?: AbortSignal): Promise<boolean>;
+    private tryReleaseEndedReservation;
     reserve(request: ZLinkObjectReserveRequest, signal?: AbortSignal): Promise<ZLinkObjectReserveResult>;
     commit(request: ZLinkObjectCommitRequest, signal?: AbortSignal): Promise<ZLinkObjectCommitResult>;
     completeCreation(request: ZLinkObjectCreationCompleteRequest, signal?: AbortSignal): Promise<ZLinkObjectCreationCompleteResult>;

package/dist/runtime/locations/in-memory-authority-store.js

@@ -171,6 +171,27 @@ class ZLinkInMemoryAuthorityStore {
             this.scanRevision++;
         return BigInt(removed);
     }
+    async releaseEndedReservation(key, expectedStoreVersion, signal) {
+        signal?.throwIfAborted();
+        return this.tryReleaseEndedReservation(key, expectedStoreVersion);
+    }
+    tryReleaseEndedReservation(key, expectedStoreVersion) {
+        const current = this.rows.get(key.value);
+        if (current === undefined ||
+            current.snapshot.storeVersion.value !== expectedStoreVersion ||
+            current.snapshot.allocation.state !== 'reserved' ||
+            current.creation === undefined ||
+            this.validation.isTargetLive(current.snapshot.allocation.descriptor, current.snapshot.allocation.descriptorLifecycleGeneration, {
+                ownerId: current.snapshot.ownerId,
+                leaseGeneration: current.snapshot.ownerLeaseGeneration
+            }))
+            return false;
+        this.adjustCapacity(this.pendingCapacity, current.snapshot.allocation, -1);
+        this.rows.delete(key.value);
+        this.creationTerminals.set(current.creation.reservationId, 'aborted');
+        this.scanRevision++;
+        return true;
+    }
     async reserve(request, signal) {
         signal?.throwIfAborted();
         validateReserve(request);
@@ -187,15 +208,8 @@ class ZLinkInMemoryAuthorityStore {
             if (current.snapshot.allocation.state === 'active') {
                 return { kind: 'alreadyExists', current: this.snapshot(current.snapshot) };
             }
-            // An unfinished creation whose owner lease ended is cancellable.
-            // Reclaim it so the key does not stay blocked forever.
-            if (this.isOwnerLive(current.snapshot) || current.creation === undefined) {
+            if (!this.tryReleaseEndedReservation((0, authority_key_codec_1.encodeAuthorityKey)(request.key.kind, request.key.globalId), current.snapshot.storeVersion.value))
                 return { kind: 'conflict', current: this.read(key) };
-            }
-            this.adjustCapacity(this.pendingCapacity, current.snapshot.allocation, -1);
-            this.rows.delete(key);
-            this.creationTerminals.set(current.creation.reservationId, 'aborted');
-            this.scanRevision++;
         }
         const target = creationTarget(request);
         if (!this.validation.isTargetLive(target.descriptor, target.lifecycleGeneration, target.owner)) {

package/dist/runtime/locations/in-memory-location-store.d.ts

@@ -25,6 +25,7 @@ export declare class ZLinkInMemoryLocationStore implements ZLinkDomainLocationSt
     commit(request: ZLinkObjectCommitRequest, signal?: AbortSignal): Promise<ZLinkObjectCommitResult>;
     completeCreation(request: ZLinkObjectCreationCompleteRequest, signal?: AbortSignal): Promise<ZLinkObjectCreationCompleteResult>;
     readCreationTerminal(operation: ZLinkCreationOperationIdentity, signal?: AbortSignal): Promise<ZLinkCreationTerminalReadResult>;
+    releaseEndedReservation(key: ZLinkAuthorityKey, expectedStoreVersion: string, signal?: AbortSignal): Promise<boolean>;
     abort(request: ZLinkObjectAbortRequest, signal?: AbortSignal): Promise<ZLinkObjectAbortResult>;
     prepareAggregate(request: ZLinkAggregatePrepareRequest, signal?: AbortSignal): Promise<ZLinkAggregatePrepareResult>;
     commitAggregate(fence: ZLinkAggregateFence, signal?: AbortSignal): Promise<ZLinkAggregateCommitResult>;

package/dist/runtime/locations/in-memory-location-store.js

@@ -86,6 +86,9 @@ class ZLinkInMemoryLocationStore {
     async readCreationTerminal(operation, signal) {
         return this.authority.readCreationTerminal(operation, signal);
     }
+    async releaseEndedReservation(key, expectedStoreVersion, signal) {
+        return this.authority.releaseEndedReservation(key, expectedStoreVersion, signal);
+    }
     async abort(request, signal) {
         return this.authority.abort(request, signal);
     }

package/dist/runtime/locations/internal-store-contracts.d.ts

@@ -1,7 +1,7 @@
 import type { ZLinkActorLocation, ZLinkActorLocationFilter, ZLinkActorLocationKey, ZLinkLocationOwnerToken, ZLinkLocationPage, ZLinkLocationWriteIntent, ZLinkLocationWriteResult, ZLinkLocationWriteStatus, ZLinkPageRequest, ZLinkPeerLocation, ZLinkPeerLocationFilter, ZLinkPeerLocationKey, ZLinkRouteLocation, ZLinkRouteLocationFilter, ZLinkRouteLocationKey, ZLinkSpotLocation, ZLinkSpotLocationFilter, ZLinkSpotLocationKey } from './internal-location-contracts';
 import type { ZLinkDomainLocationStore } from './domain-store-contract';
 export type ZLinkAuthorityStore = Pick<ZLinkDomainLocationStore, 'readAuthority' | 'compareExchangeAuthority' | 'listAuthorities'>;
-export type ZLinkObjectCreationStore = Pick<ZLinkDomainLocationStore, 'readCreationTerminal' | 'reserve' | 'commit' | 'completeCreation' | 'abort' | 'prepareAggregate' | 'commitAggregate' | 'abortAggregate'>;
+export type ZLinkObjectCreationStore = Pick<ZLinkDomainLocationStore, 'readCreationTerminal' | 'reserve' | 'commit' | 'completeCreation' | 'abort' | 'releaseEndedReservation' | 'prepareAggregate' | 'commitAggregate' | 'abortAggregate'>;
 export type ZLinkOwnerLeaseStore = Pick<ZLinkDomainLocationStore, 'claimOwnerLease' | 'readOwnerLease' | 'renewOwnerLease' | 'releaseOwnerLease'>;
 export type ZLinkMeshNodeLocationStore = Pick<ZLinkDomainLocationStore, 'updateMeshNode' | 'removeMeshNode' | 'listMeshNodes'>;
 export type ZLinkClientServerLocationStore = Pick<ZLinkDomainLocationStore, 'updateClientServer' | 'removeClientServer' | 'listClientServers'>;

package/dist/runtime/locations/location-store-repository.d.ts

@@ -20,6 +20,7 @@ export declare class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationS
     commitAggregate(fence: ZLinkAggregateFence, signal?: AbortSignal): Promise<ZLinkAggregateCommitResult>;
     private commitAggregateCore;
     abortAggregate(fence: ZLinkAggregateFence, signal?: AbortSignal): Promise<ZLinkAggregateAbortResult>;
+    releaseEndedReservation(key: ZLinkAuthorityKey, expectedStoreVersion: string, signal?: AbortSignal): Promise<boolean>;
     reserve(request: ZLinkObjectReserveRequest, signal?: AbortSignal, deadlineUnixMs?: bigint): Promise<ZLinkObjectReserveResult>;
     commit(request: ZLinkObjectCommitRequest, signal?: AbortSignal, deadlineUnixMs?: bigint): Promise<ZLinkObjectCommitResult>;
     abort(request: ZLinkObjectAbortRequest, signal?: AbortSignal, deadlineUnixMs?: bigint): Promise<ZLinkObjectAbortResult>;

package/dist/runtime/locations/location-store-repository.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkLocationStoreRepository = void 0;
+const service_relocation_runtime_1 = require("../foundation/service-relocation-runtime");
 const stream_wire_1 = require("@zlink-systems/stream-wire");
 const node_crypto_1 = require("node:crypto");
 const Options_1 = require("../../contracts/Locations/Options");
@@ -46,7 +47,33 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
     constructor(provider, nowProvider = () => new Date()) {
         super(nowProvider);
         this.nowProvider = nowProvider;
-        this.provider = provider;
+        // Classify only failures of the opaque SPI, before interpreting its records.
+        this.provider = {
+            async read(key, signal) {
+                try {
+                    return await provider.read(key, signal);
+                }
+                catch (error) {
+                    throw locationStoreProviderFailure(error, signal);
+                }
+            },
+            async write(request, signal) {
+                try {
+                    return await provider.write(request, signal);
+                }
+                catch (error) {
+                    throw locationStoreProviderFailure(error, signal);
+                }
+            },
+            async scan(request, signal) {
+                try {
+                    return await provider.scan(request, signal);
+                }
+                catch (error) {
+                    throw locationStoreProviderFailure(error, signal);
+                }
+            }
+        };
         this.aggregateInventory = new aggregate_inventory_store_1.ZLinkAggregateInventoryStore(this.provider);
     }
     async readAuthority(key, signal) {
@@ -787,6 +814,57 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
             return { kind: 'aborted' };
         }
     }
+    async releaseEndedReservation(key, expectedStoreVersion, signal) {
+        const rowKey = authorityKey(key.value);
+        const current = await this.provider.read(rowKey, signal);
+        if (current.kind === 'missing' || current.value.version.value !== expectedStoreVersion)
+            return false;
+        const record = decodeAuthorityRecord(current.value.bytes);
+        const snapshot = record.snapshot;
+        if (snapshot.allocation.state !== 'reserved' ||
+            snapshot.pendingCreation === undefined ||
+            record.aggregate !== undefined ||
+            hasRelocationAuthority(snapshot.payload))
+            return false;
+        const leaseKey = ownerKey(snapshot.ownerId);
+        const descriptorKey = meshKey(snapshot.allocation.descriptor.meshName, snapshot.allocation.descriptor.rid);
+        const capacityRowKey = capacityKey(snapshot.allocation.descriptor.meshName, String(snapshot.allocation.descriptor.rid));
+        const [lease, descriptor, capacity] = await Promise.all([
+            this.provider.read(leaseKey, signal),
+            this.provider.read(descriptorKey, signal),
+            this.provider.read(capacityRowKey, signal)
+        ]);
+        if (lease.kind === 'found' && lease.value.expiresAt === undefined)
+            throw new Error('Location Store owner lease record is invalid.');
+        if (sameLiveOwner(lease, snapshot) &&
+            descriptor.kind === 'found' &&
+            reviveMeshDescriptor(decodeCanonicalDescriptorRecord(descriptor.value.bytes).descriptor).lifecycleGeneration === snapshot.allocation.descriptorLifecycleGeneration)
+            return false;
+        const mutations = [
+            { kind: 'delete', key: rowKey }
+        ];
+        if (capacity.kind === 'found') {
+            const stored = decodeJson(capacity.value.bytes);
+            mutations.push({
+                kind: 'put',
+                key: capacityRowKey,
+                bytes: encodeJson({
+                    active: stored.active,
+                    pending: subtractCapacity(stored.pending, snapshot.allocation.capacity)
+                })
+            });
+        }
+        const result = await this.provider.write({
+            conditions: [
+                { kind: 'version', key: rowKey, expected: current.value.version },
+                conditionFor(leaseKey, lease),
+                conditionFor(descriptorKey, descriptor),
+                conditionFor(capacityRowKey, capacity)
+            ],
+            mutations
+        }, signal);
+        return result.kind === 'applied';
+    }
     async reserve(request, signal, deadlineUnixMs) {
         const encodedAuthorityKey = (0, authority_key_codec_1.encodeAuthorityKey)(request.key.kind, request.key.globalId);
         const reservationId = (0, node_crypto_1.randomUUID)();
@@ -807,51 +885,8 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
                 if (snapshot.allocation.state === 'active') {
                     return { kind: 'alreadyExists', current: snapshot };
                 }
-                if (record.aggregate !== undefined ||
-                    isCanonicalAuthorityPayload(record.snapshot.payload)) {
-                    // A relocation record carries its own recovery protocol. Reserve
-                    // may reclaim only an unfinished plain creation.
+                if (!(await this.releaseEndedReservation(encodedAuthorityKey, current.value.version.value, signal)))
                     return { kind: 'conflict', current: snapshot };
-                }
-                // The row is Reserved by another owner. An unfinished creation
-                // whose owner lease ended is cancellable, so reclaim it and retry
-                // instead of blocking the key forever.
-                const staleOwnerKey = ownerKey(snapshot.ownerId);
-                const staleCapacityKey = capacityKey(snapshot.allocation.descriptor.meshName, String(snapshot.allocation.descriptor.rid));
-                const [staleOwnerRead, staleCapacityRead] = await Promise.all([
-                    this.provider.read(staleOwnerKey, signal),
-                    this.provider.read(staleCapacityKey, signal)
-                ]);
-                if (staleOwnerRead.kind === 'found' && staleOwnerRead.value.expiresAt === undefined) {
-                    // A lease is always written with a positive TTL, so a missing
-                    // expiry is a corrupt record. Reclaiming deletes authority state,
-                    // so refuse rather than read the absence as expiry.
-                    throw new Error('Location Store owner lease record is invalid.');
-                }
-                if (sameLiveOwner(staleOwnerRead, record.snapshot)) {
-                    return { kind: 'conflict', current: snapshot };
-                }
-                const staleCapacity = staleCapacityRead.kind === 'missing'
-                    ? emptyCapacityRecord()
-                    : decodeJson(staleCapacityRead.value.bytes);
-                await this.provider.write({
-                    conditions: [
-                        { kind: 'version', key: rowKey, expected: current.value.version },
-                        versionCondition(staleOwnerKey, staleOwnerRead),
-                        conditionFor(staleCapacityKey, staleCapacityRead)
-                    ],
-                    mutations: [
-                        { kind: 'delete', key: rowKey },
-                        {
-                            kind: 'put',
-                            key: staleCapacityKey,
-                            bytes: encodeJson({
-                                active: staleCapacity.active,
-                                pending: subtractCapacity(staleCapacity.pending, record.snapshot.allocation.capacity)
-                            })
-                        }
-                    ]
-                }, signal);
                 continue;
             }
             const [descriptorRead, leaseRead] = await Promise.all([
@@ -859,7 +894,7 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
                 this.provider.read(leaseKey, signal)
             ]);
             const descriptor = liveTargetDescriptor(descriptorRead, leaseRead, request.target);
-            if (descriptor === undefined) {
+            if (descriptor === undefined || descriptor.state !== contracts_1.ZLinkFrameworkRuntimeState.Serving) {
                 return { kind: 'conflict', current: { kind: 'missing', storeNow: current.storeNow } };
             }
             const [capacityRead, objectGenerationRead, authorityOwnerGenerationRead] = await Promise.all([
@@ -1042,9 +1077,11 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
                 !sameCreationTarget(record.snapshot, request.target)) {
                 return { kind: 'stale' };
             }
+            const descriptorKey = meshKey(request.target.meshName, request.target.nodeRid);
             const leaseKey = ownerKey(request.target.owner.ownerId);
             const capacityRowKey = capacityKey(request.target.meshName, String(request.target.nodeRid));
-            const [leaseRead, capacityRead] = await Promise.all([
+            const [descriptorRead, leaseRead, capacityRead] = await Promise.all([
+                this.provider.read(descriptorKey, signal),
                 this.provider.read(leaseKey, signal),
                 this.provider.read(capacityRowKey, signal)
             ]);
@@ -1054,7 +1091,7 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
                 // rather than read the absence as expiry.
                 throw new Error('Location Store owner lease record is invalid.');
             }
-            if (!sameLiveOwner(leaseRead, record.snapshot))
+            if (liveTargetDescriptor(descriptorRead, leaseRead, request.target) === undefined)
                 return { kind: 'stale' };
             const capacity = capacityRead.kind === 'missing'
                 ? emptyCapacityRecord()
@@ -1062,6 +1099,7 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
             const result = await this.provider.write({
                 conditions: [
                     { kind: 'version', key: rowKey, expected: current.value.version },
+                    versionCondition(descriptorKey, descriptorRead),
                     leaseValueCondition(leaseKey, {
                         ownerId: record.snapshot.ownerId,
                         leaseGeneration: record.snapshot.ownerLeaseGeneration
@@ -2843,7 +2881,6 @@ function liveTargetDescriptor(descriptorRead, leaseRead, target) {
         descriptor.ownerId === target.owner.ownerId &&
         descriptor.leaseGeneration === target.owner.leaseGeneration &&
         descriptor.objectRole === contracts_1.ZLinkObjectRole.Server &&
-        descriptor.state === contracts_1.ZLinkFrameworkRuntimeState.Serving &&
         lease.ownerId === target.owner.ownerId &&
         BigInt(lease.leaseGeneration) === target.owner.leaseGeneration &&
         leaseRead.value.expiresAt !== undefined &&
@@ -2940,10 +2977,9 @@ function sameCreationTarget(snapshot, target) {
         snapshot.ownerId === target.owner.ownerId &&
         snapshot.ownerLeaseGeneration === target.owner.leaseGeneration);
 }
-const CANONICAL_AUTHORITY_MAGIC = Buffer.from('ZLAU');
-function isCanonicalAuthorityPayload(payload) {
-    return (payload.byteLength >= CANONICAL_AUTHORITY_MAGIC.byteLength &&
-        Buffer.from(payload.buffer, payload.byteOffset, CANONICAL_AUTHORITY_MAGIC.byteLength).equals(CANONICAL_AUTHORITY_MAGIC));
+const relocationAuthorityCodec = new service_relocation_runtime_1.ServiceRelocationAuthorityPayloadCodec();
+function hasRelocationAuthority(payload) {
+    return relocationAuthorityCodec.read(payload) !== undefined;
 }
 function sameLiveOwner(lease, snapshot) {
     if (lease.kind === 'missing')
@@ -3237,3 +3273,12 @@ function throwIfOperationExpired(signal, deadlineUnixMs) {
         throw new DOMException('Operation deadline exceeded.', 'TimeoutError');
     }
 }
+// Store SPI §6: preserve caller failures and classify provider failures once.
+function locationStoreProviderFailure(error, signal) {
+    if (error instanceof contracts_1.ZLinkFrameworkException ||
+        error instanceof TypeError ||
+        error instanceof RangeError ||
+        signal?.aborted === true)
+        return error;
+    return new contracts_1.ZLinkFrameworkException(contracts_1.ZLinkFrameworkErrorKind.Unavailable, 'Location Store provider is unavailable.', error);
+}

package/dist/runtime/messaging/request-deadline.d.ts

@@ -0,0 +1,3 @@
+export declare function remainingRequestTimeout(operation: string, deadlineMs: number | undefined): number | undefined;
+/** Bounds caller waiting across outbound admission and reply; late completions stay observed. */
+export declare function waitRequestReply<T>(reply: Promise<T>, operation: string, deadlineMs: number | undefined, signal?: AbortSignal, endWait?: () => void, discardLateReply?: (reply: T) => void): Promise<T>;

package/dist/runtime/messaging/request-deadline.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.remainingRequestTimeout = remainingRequestTimeout;
+exports.waitRequestReply = waitRequestReply;
+const abort_1 = require("../abort");
+const framework_errors_internal_1 = require("../framework-errors-internal");
+function remainingRequestTimeout(operation, deadlineMs) {
+    if (deadlineMs === undefined)
+        return undefined;
+    const remaining = deadlineMs - performance.now();
+    if (remaining <= 0) {
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded, `${operation} exceeded its deadline.`);
+    }
+    return Math.max(1, Math.ceil(remaining));
+}
+/** Bounds caller waiting across outbound admission and reply; late completions stay observed. */
+async function waitRequestReply(reply, operation, deadlineMs, signal, endWait, discardLateReply) {
+    let timer;
+    let waiting = reply;
+    if (deadlineMs !== undefined) {
+        const timeout = new Promise((_resolve, reject) => {
+            const remaining = remainingRequestTimeout(operation, deadlineMs);
+            timer = setTimeout(() => reject((0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded, `${operation} exceeded its deadline.`)), remaining);
+        });
+        waiting = Promise.race([reply, timeout]);
+    }
+    try {
+        return await (0, abort_1.awaitWithAbort)(waiting, signal);
+    }
+    catch (error) {
+        endWait?.();
+        if (discardLateReply !== undefined)
+            void reply.then(discardLateReply, () => undefined);
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/runtime/messaging/submission-result.d.ts

@@ -10,9 +10,10 @@ export declare enum ZLinkSubmitStatus {
 export interface ZLinkSubmitResult {
     readonly status: ZLinkSubmitStatus;
 }
-/** Projects the Core submit result once; phase only determines capacity refusal meaning. */
+/** Projects immediate refusal and pending admission failure from their Core phase. */
 export declare function submitToRequestResult(result: number, phase: 'submit' | 'completion'): number;
 export declare function classifySubmitResult(result: number, operation: string, phase?: 'submit' | 'completion'): ZLinkSubmitResult;
 export declare function requireOneWayCompletion(result: ZLinkSubmitResult, operation: string, notFoundKind?: ZLinkFrameworkInternalErrorKind): void;
 export declare function requirePublishCompletion(result: ZLinkSubmitResult, operation: string): void;
+export declare function requireClassicFanoutCompletion(result: ZLinkSubmitResult, operation: string): void;
 export declare function throwAlreadySubmitted(operation: string): never;

package/dist/runtime/messaging/submission-result.js

@@ -5,6 +5,7 @@ exports.submitToRequestResult = submitToRequestResult;
 exports.classifySubmitResult = classifySubmitResult;
 exports.requireOneWayCompletion = requireOneWayCompletion;
 exports.requirePublishCompletion = requirePublishCompletion;
+exports.requireClassicFanoutCompletion = requireClassicFanoutCompletion;
 exports.throwAlreadySubmitted = throwAlreadySubmitted;
 const framework_errors_internal_1 = require("../framework-errors-internal");
 const contracts_1 = require("../../contracts");
@@ -18,7 +19,7 @@ var ZLinkSubmitStatus;
     ZLinkSubmitStatus["RouteNotConnected"] = "routeNotConnected";
     ZLinkSubmitStatus["Shutdown"] = "shutdown";
 })(ZLinkSubmitStatus || (exports.ZLinkSubmitStatus = ZLinkSubmitStatus = {}));
-/** Projects the Core submit result once; phase only determines capacity refusal meaning. */
+/** Projects immediate refusal and pending admission failure from their Core phase. */
 function submitToRequestResult(result, phase) {
     switch (result) {
         case runtime_values_1.SubmitResult.Ok:
@@ -28,7 +29,7 @@ function submitToRequestResult(result, phase) {
         case runtime_values_1.SubmitResult.NotConnected:
             return runtime_values_1.RequestResult.NotConnected;
         case runtime_values_1.SubmitResult.NotFound:
-            return runtime_values_1.RequestResult.NotFound;
+            return phase === 'submit' ? runtime_values_1.RequestResult.NotFound : runtime_values_1.RequestResult.NotConnected;
         case runtime_values_1.SubmitResult.NotAdmitted:
             return runtime_values_1.RequestResult.Rejected;
         case runtime_values_1.SubmitResult.InvalidHandle:
@@ -45,7 +46,7 @@ function submitToRequestResult(result, phase) {
             return runtime_values_1.RequestResult.InternalError;
     }
 }
-function classifySubmitResult(result, operation, phase = 'completion') {
+function classifySubmitResult(result, operation, phase = 'submit') {
     const terminal = submitToRequestResult(result, phase);
     switch (terminal) {
         case runtime_values_1.RequestResult.Ok:
@@ -67,8 +68,9 @@ function requireOneWayCompletion(result, operation, notFoundKind = framework_err
         case ZLinkSubmitStatus.Submitted:
             return;
         case ZLinkSubmitStatus.TimedOut:
-        case ZLinkSubmitStatus.Backpressured:
             throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded, `${operation} did not obtain admission before its deadline.`, true);
+        case ZLinkSubmitStatus.Backpressured:
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, `${operation} has no admission wait token.`, true);
         case ZLinkSubmitStatus.TargetNotFound:
             throw (0, framework_errors_internal_1.createInternalFrameworkException)(notFoundKind, `${operation} target was not found.`);
         case ZLinkSubmitStatus.RouteNotConnected:
@@ -80,6 +82,11 @@ function requireOneWayCompletion(result, operation, notFoundKind = framework_err
 function requirePublishCompletion(result, operation) {
     requireOneWayCompletion(result, operation);
 }
+function requireClassicFanoutCompletion(result, operation) {
+    requireOneWayCompletion(result.status === ZLinkSubmitStatus.Backpressured
+        ? { status: ZLinkSubmitStatus.TimedOut }
+        : result, operation);
+}
 function throwAlreadySubmitted(operation) {
     throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.AlreadySubmitted, `${operation} has already been submitted.`);
 }

package/dist/runtime/spots/spot-outbound.d.ts

@@ -48,7 +48,7 @@ export interface ZLinkSpotAddressCallOptions {
  * activation. Public callers never handle an owner or generation fence.
  */
 export interface ZLinkSpotAddressTransport {
-    sendToSpotAddress(spotId: RoutingId, message: unknown, options: ZLinkSpotAddressCallOptions): Promise<ZLinkSubmitResult>;
+    sendToSpotAddress(spotId: RoutingId, message: unknown, options: Omit<ZLinkSpotAddressCallOptions, 'timeoutMs' | 'signal'>): Promise<ZLinkSubmitResult>;
     requestToSpotAddress<TReply = unknown>(spotId: RoutingId, request: unknown, options: ZLinkSpotAddressCallOptions): Promise<TReply>;
 }
 export interface ZLinkSpotRoutedTransport {
@@ -60,13 +60,11 @@ export interface ZLinkSpotRoutedTransport {
 export interface ZLinkSpotRoutedSendOptions {
     readonly instanceSpot?: boolean;
     readonly packetName?: string;
-    /** Internal end-to-end budget remaining for route admission. */
-    readonly timeoutMs?: number;
-    readonly signal?: AbortSignal;
     readonly metadata?: ReadonlyMap<string, string>;
 }
 export interface ZLinkSpotRoutedRequestOptions extends ZLinkSpotRoutedSendOptions {
     readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
 }
 export interface ZLinkSpotHandleCallOptions {
     readonly metadata?: ReadonlyMap<string, string>;
@@ -75,5 +73,5 @@ export interface ZLinkSpotHandleCallOptions {
     readonly spotRouterChannelIdForMesh?: (meshName: string) => string;
     readonly sourceSpot?: ZLinkBackendSpot;
 }
-export declare function sendToSpotHandle(transport: ZLinkSpotRoutedTransport, spot: SpotHandle, message: unknown, options?: ZLinkSpotHandleCallOptions): Promise<ZLinkSubmitResult>;
+export declare function sendToSpotHandle(transport: ZLinkSpotRoutedTransport, spot: SpotHandle, message: unknown, options?: Omit<ZLinkSpotHandleCallOptions, 'timeoutMs' | 'signal'>): Promise<ZLinkSubmitResult>;
 export declare function requestToSpotHandle<TReply = unknown>(transport: ZLinkSpotRoutedTransport, spot: SpotHandle, request: unknown, options?: ZLinkSpotHandleCallOptions): Promise<TReply>;

package/dist/runtime/spots/spot-outbound.js

@@ -103,10 +103,10 @@ function createAddressedSpotSendCall(serial, transport, spotId, message, sourceS
             options.initialMeshName = requireAddressValue(meshName, 'Mesh name', CoreTypes_1.ZLINK_MAX_MESH_NAME_BYTES);
             return this;
         },
-        async submit(signal) {
+        async submit() {
             markSubmitted(options);
             const pending = startRequestOnSerial(serial, () => ({
-                pending: transport.sendToSpotAddress(spotId, message, freezeAddressCallOptions(options, signal, sourceSpotProvider?.()))
+                pending: transport.sendToSpotAddress(spotId, message, freezeAddressCallOptions(options, sourceSpotProvider?.()))
             }));
             const result = await (serial.isCurrentTurn ? pending : (0, workers_1.deliverOnSerial)(serial, pending));
             (0, submission_result_1.requireOneWayCompletion)(result, 'Spot send', framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotRouteNotFound);
@@ -119,7 +119,11 @@ function createAddressedSpotRequestCall(serial, transport, spotId, request, sour
         markSubmitted(options);
         rejectSameSpotAsyncRequest(serial, spotId, waitPolicy);
         return startRequestOnSerial(serial, () => ({
-            pending: transport.requestToSpotAddress(spotId, request, freezeAddressCallOptions(options, signal, sourceSpotProvider?.()))
+            pending: transport.requestToSpotAddress(spotId, request, {
+                ...freezeAddressCallOptions(options, sourceSpotProvider?.()),
+                timeoutMs: options.timeoutMs,
+                signal
+            })
         }));
     };
     return {
@@ -200,14 +204,12 @@ function markSubmitted(options) {
     }
     options.submitted = true;
 }
-function freezeAddressCallOptions(options, signal, sourceSpot) {
+function freezeAddressCallOptions(options, sourceSpot) {
     return {
         ...(options.metadataPresent ? { metadata: new Map(options.metadata) } : {}),
         instanceSpot: options.instanceSpot,
         instanceSpotType: options.instanceSpotType,
         initialMeshName: options.initialMeshName,
-        timeoutMs: options.timeoutMs,
-        signal,
         sourceSpot
     };
 }
@@ -227,8 +229,8 @@ function wrapSendCall(serial, inner) {
                 inner.metadata(key);
             return this;
         },
-        async submit(signal) {
-            const result = await runInternalTransportStart(serial, () => inner.submit(signal));
+        async submit() {
+            const result = await runInternalTransportStart(serial, () => inner.submit());
             return result;
         }
     };
@@ -302,11 +304,10 @@ function wrapRoutedSpotSendCall(serial, transport, spot, message, spotRouterChan
             }
             return this;
         },
-        async submit(signal) {
+        async submit() {
             const pending = startRequestOnSerial(serial, () => ({
                 pending: sendToSpotHandle(transport, spot, message, {
                     metadata,
-                    signal,
                     spotRouterChannelIdForMesh,
                     sourceSpot: sourceSpotProvider?.()
                 })
@@ -376,19 +377,15 @@ async function sendToSpotHandle(transport, spot, message, options = {}) {
         if (options.sourceSpot !== undefined && transport.sendFromSpotToSpot !== undefined) {
             return transport.sendFromSpotToSpot(options.sourceSpot, target, message, {
                 packetName,
-                timeoutMs: options.timeoutMs,
-                signal: options.signal,
                 metadata: options.metadata
             });
         }
         return transport.sendToSpot(target, message, {
             packetName,
-            timeoutMs: options.timeoutMs,
-            signal: options.signal,
             metadata: options.metadata
         });
     };
-    return sendResolved(await requireSpotRef(spot, options.signal));
+    return sendResolved(await requireSpotRef(spot));
 }
 async function requestToSpotHandle(transport, spot, request, options = {}) {
     const packetName = (0, packet_name_1.resolveFrameworkPacketName)(request, undefined, 'SPOT');

package/dist/runtime/spots/spot-serial-executor.js

@@ -96,7 +96,10 @@ class ZLinkSpotSerialExecutor {
         this.throwIfClosing();
         let executor = this.actorExecutors.get(actorId);
         if (executor === undefined) {
-            executor = new actors_1.ZLinkActorSerialExecutor(actorId, this.sourceSpotId, this.actorOptions);
+            executor =
+                this.executionMode === contracts_1.ZLinkUserSpotExecutionMode.SpotWide
+                    ? this.spotSerial.createActorExecutor(actorId, this.sourceSpotId, this.actorOptions)
+                    : new actors_1.ZLinkActorSerialExecutor(actorId, this.sourceSpotId, this.actorOptions);
             this.actorExecutors.set(actorId, executor);
         }
         return executor;

package/dist/runtime/spots/spot-serial-turn-executor.d.ts

@@ -3,6 +3,7 @@ import type { SpotId } from '../../contracts';
 import type { ZLinkFrameworkException } from '../../contracts/Errors/ZLinkFrameworkException';
 import { type ZLinkSerialSchedulerOptions, type ZLinkSerialWorkOptions, type ZLinkSerialWorkRecord } from '../execution/serial-execution-queue';
 import type { ZLinkSerialLifecycleContext } from '../execution/serial-execution-queue';
+import { ZLinkActorSerialExecutor } from '../actors/actor-mailbox';
 export type ZLinkSpotApplicationTurnContext = ZLinkExecutionBarrierClaim & {
     readonly replay?: (failure?: unknown) => Promise<unknown> | unknown;
 };
@@ -19,6 +20,8 @@ export declare class ZLinkSpotSerialTurnExecutor {
     activeTurnId: number;
     constructor(yieldAllowed?: boolean, sourceSpotId?: SpotId | undefined, schedulerOptions?: ZLinkSerialSchedulerOptions);
     get isExecuting(): boolean;
+    /** Creates a passive Actor mailbox consumed by this Spot's scheduler. */
+    createActorExecutor(actorId: string, sourceSpotId: unknown, options?: ZLinkSerialSchedulerOptions): ZLinkActorSerialExecutor;
     get isCurrentTurn(): boolean;
     get hasPendingWork(): boolean;
     get lastActivityAt(): number;

package/dist/runtime/spots/spot-serial-turn-executor.js

@@ -4,6 +4,7 @@ exports.ZLinkSpotSerialTurnExecutor = void 0;
 const execution_1 = require("../execution");
 const framework_errors_internal_1 = require("../framework-errors-internal");
 const serial_execution_queue_1 = require("../execution/serial-execution-queue");
+const actor_mailbox_1 = require("../actors/actor-mailbox");
 const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
 class ZLinkSpotSerialTurnExecutor {
     yieldAllowed;
@@ -24,6 +25,10 @@ class ZLinkSpotSerialTurnExecutor {
     get isExecuting() {
         return this.depth > 0;
     }
+    /** Creates a passive Actor mailbox consumed by this Spot's scheduler. */
+    createActorExecutor(actorId, sourceSpotId, options) {
+        return new actor_mailbox_1.ZLinkActorSerialExecutor(actorId, sourceSpotId, options, this.scheduler);
+    }
     get isCurrentTurn() {
         return this.depth > 0 && (0, execution_1.isCurrentZLinkSpotSerialTurn)(this);
     }

package/dist/runtime/streams/bound-actor-relay-sender.d.ts

@@ -12,7 +12,7 @@ export interface ZLinkBoundActorRelaySenderOptions {
     readonly dispatchErrors?: ZLinkDispatchErrorReporter;
     readonly actorBindTimeoutMs?: number;
     readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
-    readonly relay?: (actor: ZLinkSessionActor, header: ZLinkStreamFrameHeader, payload: Message, signal?: AbortSignal) => Promise<boolean>;
+    readonly relay?: (actor: ZLinkSessionActor, header: ZLinkStreamFrameHeader, payload: Message) => Promise<boolean>;
     readonly notifyDisconnected?: (actor: ZLinkSessionActor, signal?: AbortSignal) => Promise<void>;
 }
 export declare class ZLinkBoundActorRelaySender {
@@ -21,7 +21,7 @@ export declare class ZLinkBoundActorRelaySender {
     private readonly options;
     private readonly lifecycle;
     constructor(routes: ZLinkActorSessionBindingRegistry<DefaultZLinkSessionContext, DefaultZLinkSessionActor>, frameMessages: ZLinkStreamFrameMessageFactory, options?: ZLinkBoundActorRelaySenderOptions, lifecycle?: ZLinkActorSessionLifecycleCoordinator);
-    relay(actor: DefaultZLinkSessionActor, payload: ZLinkMessage, signal?: AbortSignal, dispatchHeader?: ZLinkStreamFrameHeader): Promise<ZLinkSubmitResult>;
+    relay(actor: DefaultZLinkSessionActor, payload: ZLinkMessage, dispatchHeader?: ZLinkStreamFrameHeader): Promise<ZLinkSubmitResult>;
     private traceHeldDrop;
     private relayAcceptedFrame;
     private currentHeader;