@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,33 @@
+import type { ZLinkBackendContext } from '../backend';
+import type { ZLinkChannelRuntimeManager } from '../channels';
+import type { ZLinkFrameworkExecutionState } from '../execution';
+import type { ZLinkLocationRuntime } from '../locations';
+import type { ZLinkSpotNodeRuntimeManager } from '../spots';
+import type { ZLinkStreamRuntimeManager } from '../streams';
+import type { ZLinkLocationRuntimeStopSnapshot } from './location-runtime-owner';
+interface ZLinkRuntimeOwnedStore {
+    dispose?(): void | Promise<void>;
+}
+export interface ZLinkRuntimeStartRollbackParts {
+    readonly context: ZLinkBackendContext;
+    readonly startedLocationRuntime?: ZLinkLocationRuntime;
+    readonly streamRuntime?: ZLinkStreamRuntimeManager;
+    readonly spotNodeRuntime?: ZLinkSpotNodeRuntimeManager;
+    readonly channelRuntime?: ZLinkChannelRuntimeManager;
+    readonly ownedStores?: readonly ZLinkRuntimeOwnedStore[];
+}
+export interface ZLinkRuntimeStopParts {
+    readonly state: ZLinkFrameworkExecutionState;
+    readonly cleanupDeadline?: Date;
+    readonly locationSnapshot: ZLinkLocationRuntimeStopSnapshot;
+    readonly streamRuntime?: ZLinkStreamRuntimeManager;
+    readonly spotNodeRuntime?: ZLinkSpotNodeRuntimeManager;
+    readonly channelRuntime?: ZLinkChannelRuntimeManager;
+    readonly serviceRelocation?: {
+        dispose(): Promise<void>;
+    };
+    readonly ownedStores?: readonly ZLinkRuntimeOwnedStore[];
+}
+export declare function rollbackRuntimeStart(parts: ZLinkRuntimeStartRollbackParts): Promise<void>;
+export declare function stopRuntimeParts(parts: ZLinkRuntimeStopParts): Promise<void>;
+export {};

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

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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);
+}
+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 Promise.allSettled(state.listenerTasks);
+    await runShutdownStep(errors, () => state.dispose());
+    await disposeOwnedStores(parts.ownedStores, errors);
+    const failures = errors.filter((error) => !isShutdownAbort(error));
+    if (failures.length === 1)
+        throw failures[0];
+    if (failures.length > 1) {
+        throw new AggregateError(failures, 'Framework runtime shutdown failed.');
+    }
+}
+async function disposeOwnedStores(stores, errors) {
+    const disposed = new Set();
+    for (const store of stores ?? []) {
+        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?.());
+    }
+}
+async function runShutdownStep(errors, step) {
+    try {
+        await step();
+    }
+    catch (error) {
+        errors.push(error);
+    }
+}
+function isShutdownAbort(error) {
+    if ((0, abort_1.isAbortError)(error))
+        return true;
+    return error instanceof AggregateError
+        && error.errors.every((nested) => isShutdownAbort(nested));
+}

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

@@ -0,0 +1,7 @@
+import { type ServiceMaintenanceRelocationControl } from '../foundation/service-stateful-wire-codec';
+export type ZLinkServiceRelocationControlRequest = ServiceMaintenanceRelocationControl;
+export type ZLinkServiceRelocationControlResponse = ServiceMaintenanceRelocationControl;
+export declare function encodeServiceRelocationControlRequest(request: ZLinkServiceRelocationControlRequest): Buffer;
+export declare function decodeServiceRelocationControlRequest(payload: Uint8Array): ZLinkServiceRelocationControlRequest | undefined;
+export declare function encodeServiceRelocationControlResponse(response: ZLinkServiceRelocationControlResponse): Buffer;
+export declare function decodeServiceRelocationControlResponse(payload: Uint8Array): ZLinkServiceRelocationControlResponse;

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

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeServiceRelocationControlRequest = encodeServiceRelocationControlRequest;
+exports.decodeServiceRelocationControlRequest = decodeServiceRelocationControlRequest;
+exports.encodeServiceRelocationControlResponse = encodeServiceRelocationControlResponse;
+exports.decodeServiceRelocationControlResponse = decodeServiceRelocationControlResponse;
+const service_stateful_wire_codec_1 = require("../foundation/service-stateful-wire-codec");
+function encodeServiceRelocationControlRequest(request) {
+    return (0, service_stateful_wire_codec_1.encodeMaintenanceRelocationControl)(request);
+}
+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)
+        return undefined;
+    return (0, service_stateful_wire_codec_1.decodeMaintenanceRelocationControl)(bytes);
+}
+function encodeServiceRelocationControlResponse(response) {
+    return (0, service_stateful_wire_codec_1.encodeMaintenanceRelocationControl)(response);
+}
+function decodeServiceRelocationControlResponse(payload) {
+    return (0, service_stateful_wire_codec_1.decodeMaintenanceRelocationControl)(payload);
+}

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

@@ -0,0 +1,241 @@
+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 { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import type { ZLinkRuntimeEventPublisher, ZLinkRuntimeMetrics } from '../diagnostics';
+import type { ZLinkFrameworkRegistration } from '../configuration';
+import type { ZLinkBackendMeshNode, ZLinkMeshCompletionTable } from '../backend';
+import { type ReceiveRecord } from '../foundation/service-runtime-contracts';
+import { type ServiceRelocationQueuedMessage } from '../foundation/service-relocation-runtime';
+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);
+}
+interface ZLinkHostRelocationOptions {
+    readonly registration: ZLinkFrameworkRegistration;
+    readonly providerResolver?: ZLinkProviderResolver;
+    readonly locationStore: () => ZLinkLocationStore | undefined;
+    readonly currentOwner: () => ZLinkLocationOwnerToken | undefined;
+    readonly liveDescriptors: (meshName: string, signal?: AbortSignal) => Promise<readonly ZLinkMeshNodeDescriptor[]>;
+    readonly localDescriptor?: (meshName: string) => ZLinkMeshNodeDescriptor | undefined;
+    readonly meshNode: (meshName: string) => ZLinkBackendMeshNode | undefined;
+    readonly completions: (meshName: string) => ZLinkMeshCompletionTable | undefined;
+    readonly spotManager: () => DefaultZLinkSpotManager | undefined;
+    readonly spotNodeRuntime: () => ZLinkSpotNodeRuntimeManager | undefined;
+    readonly actorManager: () => DefaultZLinkActorManager | undefined;
+    readonly actorTransfer: ZLinkActorTransferRuntime;
+    readonly boundSessionRelocation?: {
+        receiveSeal(value: ServiceSessionRelocationSeal, signal?: AbortSignal): Promise<ServiceSessionRelocationSealed>;
+        receiveRoute(value: ServiceSessionRelocationRoute): Promise<void>;
+        clear?(): void;
+    };
+    readonly trackInstanceSpot?: (input: ZLinkTrackedInstanceAuthority) => void;
+    readonly invalidateActorRoute?: (actorId: string) => void;
+    readonly reconcileStatefulAuthorityRoutes?: (signal?: AbortSignal) => Promise<void>;
+    readonly runtimeEventPublisher?: ZLinkRuntimeEventPublisher;
+    readonly metrics?: ZLinkRuntimeMetrics;
+}
+/** Production host bridge from Retire inventory to remote RouteMesh owners. */
+export declare class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocation {
+    private readonly options;
+    private readonly targetStages;
+    private readonly terminalTargets;
+    private readonly relocationAuthorityKeys;
+    private readonly targetPrepareOperations;
+    private readonly pendingReplyRelays;
+    private readonly pendingSessionRelocations;
+    private readonly terminalSessionRelocations;
+    /**
+     * A command 44 submit has no response path. Keep a bounded record of a
+     * rejected one-way attempt without turning the committed relocation into a
+     * retry loop.
+     */
+    private readonly failedSessionRouteSubmits;
+    private readonly sourceRelocationIds;
+    private readonly targetAssemblies;
+    /**
+     * 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).
+     */
+    private readonly targetReadyFailures;
+    /**
+     * Successful restores retained across a Ready delivery retry: an
+     * exact-identity Prepare resend re-submits Ready against this retained
+     * staging instead of redoing the restore (spec 28).
+     */
+    private readonly targetReadyResponses;
+    private readonly sourceCutoverWindows;
+    private readonly peerPayloadBudgets;
+    private nodePayloadBudget?;
+    private readonly sourceActorJoinProfiles;
+    private readonly terminalActorJoinSourceLeaves;
+    private readonly codec;
+    /**
+     * Set once dispose() starts tearing assemblies down. A payload() rejection
+     * observed after this point is the shutdown itself, not a chunk-assembly or
+     * checksum integrity failure — it must not be reported as DataLost(35).
+     */
+    private disposed;
+    constructor(options: ZLinkHostRelocationOptions);
+    relocateActorJoin(input: Parameters<ZLinkActorJoinRelocation['relocateActorJoin']>[0]): ReturnType<ZLinkActorJoinRelocation['relocateActorJoin']>;
+    dispose(): Promise<void>;
+    completeActorJoinSourceCleanup(actorId: string): void;
+    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. */
+    private deliverTargetReady;
+    /** Cleans up a Ready reply that never delivered within the Restore validity window. */
+    private expireTargetReadyResponse;
+    /**
+     * Submits one Ready reply. A failed submit is left for the next identical
+     * Prepare resend to retry against the retained staging (spec 28) — it is
+     * not rolled back here and does not arm the cutover fallback.
+     */
+    private submitTargetReady;
+    private replyPrepare;
+    /** Copies one exact-identity payload chunk into its registered assembly. */
+    private acceptRelocationStateChunk;
+    private registerTargetAssembly;
+    private relocationIntegrityFaultGate;
+    requestSessionRelocationSeal(meshName: string, targetNodeRid: RoutingId, request: ServiceSessionRelocationSeal, signal?: AbortSignal): Promise<ServiceSessionRelocationSealed>;
+    sendSessionRelocationRoute(meshName: string, targetNodeRid: RoutingId, request: ServiceSessionRelocationRoute, signal?: AbortSignal): Promise<void>;
+    private requestSessionRelocationSealControl;
+    private acceptSessionRelocationResponse;
+    private sourceLifecycleGeneration;
+    private handleSessionRelocationSeal;
+    private handleSessionRelocationRoute;
+    private validateSessionOwnerFence;
+    private sendSessionRelocationResponse;
+    private relocateSpotAggregate;
+    private relocateStandaloneActor;
+    private relocatePerActorSpotShell;
+    private actorCaptureUnit;
+    private reserveRelocationId;
+    private reserveExactRelocationId;
+    private runCoordinator;
+    /** Streams the payload chunks of one stage under the effective in-flight budgets. */
+    private sendRelocationStateChunks;
+    /**
+     * Phase 1 in-flight accounting: the charge covers the submit window of one
+     * chunk under min(configured, conservative) budgets per peer and per node.
+     */
+    private acquireRelocationBudget;
+    /** Pre-seal admission wait — a full budget delays the next unit before seal. */
+    private waitForRelocationBudgetHeadroom;
+    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.
+     */
+    private beginSourceCutoverWindow;
+    private scheduleCutoverRetransmit;
+    /**
+     * True when every relocation this source started reached its Message
+     * Follow route removal point (S4) and its cutover retransmission window
+     * ended — both source-local events (spec 30 §11).
+     */
+    isSafeToShutdown(): boolean;
+    private releaseParticipantAuthorities;
+    /** Restores the hidden object and its saved-work prefix before Ready. */
+    private handlePrepareControl;
+    private armTargetCutoverFallback;
+    private handleOneWayControl;
+    /** Validates one boundary relay record and buffers it until cutover applies it. */
+    private stageBoundaryRelay;
+    /**
+     * Compares the cutover confirmation values against the staged boundary
+     * relay. A retransmitted batch replaces a partially received span as a
+     * whole (the retransmission always resends the entire batch, so the exact
+     * span is the staged suffix of `boundaryRecordCount` records).
+     */
+    private reconcileBoundaryRelay;
+    private beginTargetFinalize;
+    private finalizeTargetStage;
+    private validateRelocationData;
+    private applyRelocationData;
+    private finalizeActorJoinProfiles;
+    private submitActorJoinSourceLeave;
+    private acceptActorJoinSourceLeave;
+    private sendControlOneWay;
+    private submitControlFrame;
+    private waitForTargetAuthorities;
+    private clearTargetRelocationPublication;
+    private handleReplyRelay;
+    private sendReplyRelay;
+    private acceptReplyRelayAck;
+    private requireAdmittedPeer;
+    private targetReplyRelayCoordinator;
+    private relayTerminalReplies;
+    private exactSourceLeaseExpired;
+    private publishSessionRoutes;
+    private sendControl;
+    private selectTarget;
+    private readTargetParticipantAuthorities;
+    private reserveTargetForPrepare;
+    private authorityPayloadForPublication;
+    private abortTargetReservation;
+    private abortTargetStage;
+    private commitTargetReservation;
+    private commitTargetAggregate;
+    private readAggregateForCommitRetry;
+    private materializeTargetEnvelope;
+    /** Maps schema ordinals to the authoritative Location Store inventory. */
+    private resolveTargetParticipantInventory;
+    private spotKind;
+    private spotRegistration;
+    private actorRegistration;
+    private captureApplication;
+    private createRelocationAdapter;
+    private recordRelocationInterruption;
+    private sealSpotMessageFollow;
+    private commitSpotMessageFollow;
+    private requireLocationStore;
+    private requireSpotManager;
+    private requireActorManager;
+    private relocationLimits;
+    private requireMeshNode;
+    private sendInfrastructureControl;
+    private requestInfrastructureControl;
+}
+export declare function decodeQueuedHandoffPacket(message: ServiceRelocationQueuedMessage): ZLinkActorHandoffPacket;
+export declare function createServiceRelocationId(isInUse: (candidate: string) => boolean, entropy?: (size: number) => Uint8Array): string;
+/**
+ * Tags a target-side restore failure as data loss (chunk assembly or
+ * checksum verification) so relocationFailed reports failureCode 35 rather
+ * than the generic internal-failure code (spec 15 §4).
+ */
+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;
+export declare function encodeHandoffQueuedMessages(backlog: readonly ZLinkActorHandoffPacket[]): readonly ServiceRelocationQueuedMessage[];
+export {};