@zlink-systems/framework 0.25.0 → 0.27.0

package/dist/runtime/host/runtime-shutdown.d.ts

@@ -15,10 +15,12 @@ export interface ZLinkRuntimeStartRollbackParts {
     readonly spotNodeRuntime?: ZLinkSpotNodeRuntimeManager;
     readonly channelRuntime?: ZLinkChannelRuntimeManager;
     readonly ownedStores?: readonly ZLinkRuntimeOwnedStore[];
+    readonly shutdownSignal?: AbortSignal;
 }
 export interface ZLinkRuntimeStopParts {
     readonly state: ZLinkFrameworkExecutionState;
     readonly cleanupDeadline?: Date;
+    readonly shutdownSignal?: AbortSignal;
     readonly locationSnapshot: ZLinkLocationRuntimeStopSnapshot;
     readonly streamRuntime?: ZLinkStreamRuntimeManager;
     readonly spotNodeRuntime?: ZLinkSpotNodeRuntimeManager;

package/dist/runtime/host/runtime-shutdown.js

@@ -4,29 +4,36 @@ exports.rollbackRuntimeStart = rollbackRuntimeStart;
 exports.stopRuntimeParts = stopRuntimeParts;
 const abort_1 = require("../abort");
 async function rollbackRuntimeStart(parts) {
-    await Promise.allSettled([
-        parts.streamRuntime?.dispose(),
-        parts.spotNodeRuntime?.dispose(),
-        parts.channelRuntime?.dispose()
-    ]);
-    await parts.startedLocationRuntime?.stop().catch(() => undefined);
-    await parts.context.dispose().catch(() => undefined);
-    await disposeOwnedStores(parts.ownedStores);
+    const errors = [];
+    await runShutdownStep(errors, () => parts.streamRuntime?.dispose());
+    await runShutdownStep(errors, () => parts.spotNodeRuntime?.dispose());
+    await runShutdownStep(errors, () => parts.channelRuntime?.dispose());
+    await runShutdownStep(errors, () => parts.startedLocationRuntime?.stop(parts.shutdownSignal));
+    if (errors.length === 0)
+        await runShutdownStep(errors, () => parts.context.dispose());
+    await disposeOwnedStores(parts.ownedStores, errors);
+    if (errors.length === 1)
+        throw errors[0];
+    if (errors.length > 1)
+        throw new AggregateError(errors, 'Framework start rollback failed.');
 }
 async function stopRuntimeParts(parts) {
     const state = parts.state;
-    state.abortController.abort();
     const errors = [];
     await runShutdownStep(errors, () => parts.streamRuntime?.dispose());
     await runShutdownStep(errors, () => parts.spotNodeRuntime?.dispose(undefined, parts.cleanupDeadline));
     await runShutdownStep(errors, () => parts.channelRuntime?.dispose());
     await runShutdownStep(errors, () => parts.serviceRelocation?.dispose());
     await runShutdownStep(errors, () => parts.locationSnapshot.lifecycle?.dispose());
-    await runShutdownStep(errors, () => parts.locationSnapshot.runtime?.stop());
+    await runShutdownStep(errors, () => parts.locationSnapshot.runtime?.stop(parts.shutdownSignal));
     await Promise.allSettled(state.listenerTasks);
-    await runShutdownStep(errors, () => state.dispose());
+    if (errors.every(isShutdownAbort))
+        await runShutdownStep(errors, () => state.dispose());
     await disposeOwnedStores(parts.ownedStores, errors);
     const failures = errors.filter((error) => !isShutdownAbort(error));
+    for (const failure of failures) {
+        state.errorSink.reportRuntimeTaskException('framework shutdown', failure);
+    }
     if (failures.length === 1)
         throw failures[0];
     if (failures.length > 1) {
@@ -39,16 +46,6 @@ async function disposeOwnedStores(stores, errors) {
         if (disposed.has(store))
             continue;
         disposed.add(store);
-        if (errors === undefined) {
-            try {
-                await store.dispose?.();
-            }
-            catch {
-                // Rollback is already handling the original start failure. Store
-                // cleanup remains best effort in this path.
-            }
-            continue;
-        }
         await runShutdownStep(errors, () => store.dispose?.());
     }
 }

package/dist/runtime/host/service-relocation-control.js

@@ -4,6 +4,8 @@ exports.encodeServiceRelocationControlRequest = encodeServiceRelocationControlRe
 exports.decodeServiceRelocationControlRequest = decodeServiceRelocationControlRequest;
 exports.encodeServiceRelocationControlResponse = encodeServiceRelocationControlResponse;
 exports.decodeServiceRelocationControlResponse = decodeServiceRelocationControlResponse;
+const service_wire_binary_primitives_1 = require("../foundation/service-wire-binary-primitives");
+const service_wire_constants_generated_1 = require("../foundation/service-wire-constants.generated");
 const service_stateful_wire_codec_1 = require("../foundation/service-stateful-wire-codec");
 function encodeServiceRelocationControlRequest(request) {
     return (0, service_stateful_wire_codec_1.encodeMaintenanceRelocationControl)(request);
@@ -12,7 +14,10 @@ function decodeServiceRelocationControlRequest(payload) {
     const bytes = Buffer.isBuffer(payload)
         ? payload
         : Buffer.from(payload.buffer, payload.byteOffset, payload.byteLength);
-    if (bytes.byteLength < 5 || bytes[0] !== 0x5a || bytes[1] !== 0x4d || bytes[2] !== 1)
+    if (bytes.byteLength < service_wire_binary_primitives_1.SERVICE_WIRE_PREFIX_SIZE ||
+        bytes[0] !== service_wire_constants_generated_1.SERVICE_WIRE_MAGIC[0] ||
+        bytes[1] !== service_wire_constants_generated_1.SERVICE_WIRE_MAGIC[1] ||
+        bytes[service_wire_binary_primitives_1.SERVICE_WIRE_MAJOR_OFFSET] !== service_wire_constants_generated_1.SERVICE_WIRE_MAJOR)
         return undefined;
     return (0, service_stateful_wire_codec_1.decodeMaintenanceRelocationControl)(bytes);
 }

package/dist/runtime/host/service-relocation-host-runtime.d.ts

@@ -1,19 +1,20 @@
-import type { RoutingId, ZLinkMeshNodeDescriptor } from '../../contracts';
-import type { ZLinkLocationOwnerToken } from '../locations/internal-location-contracts';
-import type { ZLinkDomainLocationStore as ZLinkLocationStore } from '../locations/domain-store-contract';
-import type { ZLinkTrackedInstanceAuthority } from '../locations/spot-location-claims';
+import { type RoutingId, type ZLinkMeshNodeDescriptor } from '../../contracts';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
-import type { ZLinkRuntimeEventPublisher, ZLinkRuntimeMetrics } from '../diagnostics';
-import type { ZLinkFrameworkRegistration } from '../configuration';
+import type { ZLinkActivationAdmission } from '../activation-admission';
+import type { DefaultZLinkActorManager } from '../actors';
+import { type ZLinkActorHandoffPacket } from '../actors/actor-handoff';
+import type { ZLinkActorJoinRelocation } from '../actors/actor-join-relocation';
 import type { ZLinkBackendMeshNode, ZLinkMeshCompletionTable } from '../backend';
-import { type ReceiveRecord } from '../foundation/service-runtime-contracts';
+import type { ZLinkFrameworkRegistration } from '../configuration';
+import { type ZLinkRuntimeEventPublisher, type ZLinkRuntimeMetrics } from '../diagnostics';
 import { type ServiceRelocationQueuedMessage } from '../foundation/service-relocation-runtime';
+import { type ReceiveRecord } from '../foundation/service-runtime-contracts';
+import { type ServiceSessionRelocationRoute, type ServiceSessionRelocationSeal, type ServiceSessionRelocationSealed } from '../foundation/service-stateful-wire-codec';
+import type { ZLinkDomainLocationStore as ZLinkLocationStore } from '../locations/domain-store-contract';
+import type { ZLinkLocationOwnerToken } from '../locations/internal-location-contracts';
+import type { ZLinkTrackedInstanceAuthority } from '../locations/spot-location-claims';
 import type { DefaultZLinkSpotManager, ZLinkSpotNodeRuntimeManager } from '../spots';
-import type { DefaultZLinkActorManager } from '../actors';
-import { type ZLinkActorHandoffPacket } from '../actors/actor-handoff';
 import { type ZLinkActorTransferRuntime } from './actor-transfer-runtime';
-import { type ServiceSessionRelocationRoute, type ServiceSessionRelocationSeal, type ServiceSessionRelocationSealed, type ServiceWireRelocationObject } from '../foundation/service-stateful-wire-codec';
-import type { ZLinkActorJoinRelocation } from '../actors/actor-join-relocation';
 export declare class ZLinkRelocationStateIncompatibleError extends Error {
     constructor(message: string);
 }
@@ -22,6 +23,7 @@ interface ZLinkHostRelocationOptions {
     readonly providerResolver?: ZLinkProviderResolver;
     readonly locationStore: () => ZLinkLocationStore | undefined;
     readonly currentOwner: () => ZLinkLocationOwnerToken | undefined;
+    readonly targetAdmissionSealed?: () => boolean;
     readonly liveDescriptors: (meshName: string, signal?: AbortSignal) => Promise<readonly ZLinkMeshNodeDescriptor[]>;
     readonly localDescriptor?: (meshName: string) => ZLinkMeshNodeDescriptor | undefined;
     readonly meshNode: (meshName: string) => ZLinkBackendMeshNode | undefined;
@@ -40,6 +42,7 @@ interface ZLinkHostRelocationOptions {
     readonly reconcileStatefulAuthorityRoutes?: (signal?: AbortSignal) => Promise<void>;
     readonly runtimeEventPublisher?: ZLinkRuntimeEventPublisher;
     readonly metrics?: ZLinkRuntimeMetrics;
+    readonly activationAdmission?: ZLinkActivationAdmission;
 }
 /** Production host bridge from Retire inventory to remote RouteMesh owners. */
 export declare class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocation {
@@ -63,8 +66,7 @@ export declare class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoin
      * Terminal restore failures (assembly/checksum/factory/restore error): the
      * target already sent relocationFailed (command 53) once. An exact-identity
      * Prepare resend replays the stored response rather than retrying the
-     * restore; a different exact identity reusing the same RelocationId+attempt
-     * key supersedes the stale entry (spec 28 §3, §9).
+     * restore. A different exact identity never changes this entry (spec 28 §4.3).
      */
     private readonly targetReadyFailures;
     /**
@@ -88,7 +90,12 @@ export declare class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoin
     constructor(options: ZLinkHostRelocationOptions);
     relocateActorJoin(input: Parameters<ZLinkActorJoinRelocation['relocateActorJoin']>[0]): ReturnType<ZLinkActorJoinRelocation['relocateActorJoin']>;
     dispose(): Promise<void>;
+    /** Host shutdown waits for the existing attempt terminal before releasing its lease. */
+    drainTargetAttempts(): Promise<void>;
+    /** Spec 28 §4.4: the target owner alone orders shutdown seal and verified cutover. */
+    private targetStageSealed;
     completeActorJoinSourceCleanup(actorId: string): void;
+    private finalizeActorJoinSource;
     relocateMesh(meshName: string, targetApplicationVersion?: bigint, signal?: AbortSignal, stopStartingSignal?: AbortSignal): Promise<void>;
     tryHandleControl(meshName: string, record: ReceiveRecord, signal?: AbortSignal): Promise<boolean>;
     /** Sends the Ready reply once the async restore finished; failures replay on resend. */
@@ -116,8 +123,10 @@ export declare class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoin
     private validateSessionOwnerFence;
     private sendSessionRelocationResponse;
     private relocateSpotAggregate;
+    private relocateSpotAggregateCore;
     private relocateStandaloneActor;
     private relocatePerActorSpotShell;
+    private relocatePerActorSpotShellCore;
     private actorCaptureUnit;
     private reserveRelocationId;
     private reserveExactRelocationId;
@@ -134,15 +143,35 @@ export declare class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoin
     private requireNodePayloadBudget;
     private requirePeerPayloadBudget;
     /**
-     * Starts the source retransmission window after the cutover submit
-     * terminal. The boundary batch and cutover copies live in framework memory
-     * (not charged to the in-flight budget) and are cleaned exactly once when
-     * the window ends. While the window is open a failed submit retries the
-     * whole batch on the (re-established) connection. S4 — the Message Follow
-     * route removal point — closes the unit for SafeToShutdown.
+     * Starts the source cutover window after the cutover submit terminal. The
+     * boundary batch and cutover copies live in framework memory (not charged
+     * to the in-flight budget) until the authority settlement closes the
+     * window. S4 — the Message Follow route removal point — closes the unit for
+     * SafeToShutdown.
      */
     private beginSourceCutoverWindow;
-    private scheduleCutoverRetransmit;
+    /** The authority settlement ended: the retained batch copy is released. */
+    private closeSourceCutoverWindow;
+    private releaseSourceCutoverWindow;
+    /**
+     * Sends the whole boundary batch and cutover again after a failed submit
+     * or an observed loss of the target connection (spec 28 §4.4). The target
+     * replaces its partial span with the whole batch.
+     */
+    private resendSourceCutover;
+    /**
+     * The one source authority settlement after Ready (Location runtime
+     * §6.1·§10, spec 28 §4.4). It reads the Store until the target commit or
+     * the Restore deadline. From the Restore deadline it runs the source
+     * Preserve fence: a CAS on the StoreVersion expected by target NewOwner
+     * excludes a late target commit. `target`: the
+     * target committed. `source`: Preserve fenced the target out while the
+     * source owner lease was valid. `lost`: the source owner lease ended first
+     * or another authority owns the object. An uncertain Store or lease result
+     * keeps the work retained and repeats the same decision.
+     */
+    private settleSourceAuthority;
+    private readSourceSettlement;
     /**
      * True when every relocation this source started reached its Message
      * Follow route removal point (S4) and its cutover retransmission window
@@ -152,6 +181,13 @@ export declare class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoin
     private releaseParticipantAuthorities;
     /** Restores the hidden object and its saved-work prefix before Ready. */
     private handlePrepareControl;
+    /**
+     * The cutover wait of a Ready stage (spec 28 §4.4) is a Warning only: it
+     * records `cutover_timeout` and never submits the target CAS or opens
+     * dispatch. From then on the target settlement reads the Location Store so
+     * a source Preserve fence or a lost target lease ends the staging; only a
+     * verified cutover lets that settlement submit the CAS.
+     */
     private armTargetCutoverFallback;
     private handleOneWayControl;
     /** Validates one boundary relay record and buffers it until cutover applies it. */
@@ -172,7 +208,6 @@ export declare class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoin
     private acceptActorJoinSourceLeave;
     private sendControlOneWay;
     private submitControlFrame;
-    private waitForTargetAuthorities;
     private clearTargetRelocationPublication;
     private handleReplyRelay;
     private sendReplyRelay;
@@ -189,7 +224,19 @@ export declare class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoin
     private authorityPayloadForPublication;
     private abortTargetReservation;
     private abortTargetStage;
+    private discardTargetStage;
     private commitTargetReservation;
+    /**
+     * The one target authority settlement (Location runtime §10, spec 28
+     * §4.4-§4.5). Only a verified cutover lets the target submit its NewOwner
+     * CAS; a transient or indeterminate result resubmits the same RelocationId
+     * and expected StoreVersion while the target owner lease is valid (no
+     * separate timeout, no fixed count). Before a verified cutover the target
+     * only reads. It returns the committed authority, or undefined when a
+     * definitive Conflict excludes this commit after reconciliation, a source
+     * Preserve fence moved the source row, or the target lease ended; the
+     * caller then discards the staging.
+     */
     private commitTargetAggregate;
     private readAggregateForCommitRetry;
     private materializeTargetEnvelope;
@@ -205,6 +252,7 @@ export declare class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoin
     private commitSpotMessageFollow;
     private requireLocationStore;
     private requireSpotManager;
+    private afterSpotCloseDecision;
     private requireActorManager;
     private relocationLimits;
     private requireMeshNode;
@@ -220,22 +268,7 @@ export declare function createServiceRelocationId(isInUse: (candidate: string) =
  */
 export declare class ServiceRelocationDataLostError extends Error {
 }
-/**
- * Maps a target-side relocation Prepare failure to the closest wire
- * framework-error code the generated schema
- * ({@link ServiceWireFrameworkErrorCode}) defines — mirrors the java
- * reference mapping (commit 97fc074058) and the dotnet/cpp ports. The wire
- * vocabulary predates the framework's typed error kinds and has no
- * one-to-one code for every kind, so several kinds share the nearest fit
- * (documented per case below); unresolvable vocabulary gaps belong at the
- * schema level, not invented here. {@link ServiceRelocationDataLostError}
- * is this runtime's dedicated tag for a verified checksum/assembly/digest
- * integrity failure — the case that keeps relocationDataLost(35). An
- * unclassified error carries no evidence of integrity loss and takes the
- * generic opaque requestFailed(17). `objectKind` (the Prepare's
- * ObjectFence.kind, spec 28 §4.2) picks between an Actor- and
- * Spot-specific code where the schema splits by object kind.
- */
-export declare function relocationFailedFailureCode(error: unknown, objectKind: ServiceWireRelocationObject['kind']): number;
+/** Classifies relocation failure with the error model §2.1 mapping. */
+export declare function relocationFailedFailureCode(error: unknown): number;
 export declare function encodeHandoffQueuedMessages(backlog: readonly ZLinkActorHandoffPacket[]): readonly ServiceRelocationQueuedMessage[];
 export {};