@zlink-systems/framework 0.10.0

package/dist/runtime/host/location-runtime-owner.js

@@ -0,0 +1,227 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkLocationRuntimeOwner = void 0;
+const locations_1 = require("../locations");
+class ZLinkLocationRuntimeOwner {
+    options;
+    stores;
+    runtime;
+    lifecycle;
+    events;
+    leaseTrackerState;
+    spotRouteInvalidator;
+    constructor(options) {
+        this.options = options;
+    }
+    get currentStores() {
+        return this.stores;
+    }
+    get currentRuntime() {
+        return this.runtime;
+    }
+    get currentLifecycle() {
+        return this.lifecycle;
+    }
+    get currentEvents() {
+        return this.events;
+    }
+    get currentLeaseTracker() {
+        return this.leaseTrackerState?.tracker;
+    }
+    setSpotRouteInvalidator(invalidator) {
+        this.spotRouteInvalidator = invalidator;
+    }
+    actorTransferStore() {
+        const store = this.stores?.locationStore ?? this.createAndRememberStores()?.locationStore;
+        return isActorTransferStore(store) ? store : undefined;
+    }
+    locationStore() {
+        return this.stores?.locationStore ?? this.createAndRememberStores()?.locationStore;
+    }
+    ensureRuntime(primaryMeshName) {
+        if (this.runtime !== undefined) {
+            return this.runtime;
+        }
+        const stores = this.stores ?? this.createRuntimeStores();
+        if (stores === undefined) {
+            return undefined;
+        }
+        this.stores = stores;
+        const runtime = new locations_1.ZLinkLocationRuntime({
+            stores,
+            options: this.options.registration.locations.options,
+            events: this.ensureEvents(),
+            leaseTracker: this.leaseTracker(stores),
+            metrics: this.options.metrics,
+            meshNames: [...this.options.registration.spotNodes.keys()],
+            leaseScopes: [
+                ...[...this.options.registration.spotNodes.keys()]
+                    .map(name => ({ kind: 'mesh', name })),
+                ...[...this.options.registration.channels.keys()]
+                    .map(name => ({ kind: 'channel', name }))
+            ],
+            rewriteAuthorityPayloadForOwner: this.options.rewriteAuthorityPayloadForOwner
+        });
+        this.runtime = runtime;
+        this.lifecycle = new locations_1.ZLinkLocationLifecycle(runtime, stores.actorStore, primaryMeshName ?? '', stores.authorityStore, stores.spotStore, spotId => this.spotRouteInvalidator?.(spotId));
+        return runtime;
+    }
+    createRefResolver(spotMeshNames) {
+        this.ensureRuntime(spotMeshNames.length === 1 ? spotMeshNames[0] : undefined);
+        const stores = this.stores;
+        if (stores === undefined) {
+            return undefined;
+        }
+        return new locations_1.ZLinkStoreLocationResolvers({
+            stores: { ...stores, authorityStore: stores.locationStore },
+            leaseTracker: this.leaseTracker(stores),
+            events: this.events,
+            spotMeshNames,
+            routeCacheMaxAgeMs: this.options.registration.locations.options.routeCacheMaxAgeMs
+        });
+    }
+    createSpotRouteResolver(spotMeshNames, spotRouterChannelIdByMesh, resolveLocalSpot) {
+        const stores = this.stores;
+        if (stores === undefined || spotMeshNames.length === 0) {
+            return undefined;
+        }
+        return new locations_1.ZLinkLocationSpotRouteResolver(new locations_1.ZLinkStoreLocationResolvers({
+            stores: { ...stores, authorityStore: stores.locationStore },
+            leaseTracker: this.leaseTracker(stores),
+            events: this.events,
+            routeCacheMaxAgeMs: this.options.registration.locations.options.routeCacheMaxAgeMs
+        }), spotMeshNames, spotRouterChannelIdByMesh, resolveLocalSpot);
+    }
+    createActorLocationResolver(spotMeshNames) {
+        const stores = this.stores;
+        if (stores === undefined) {
+            return undefined;
+        }
+        return new locations_1.ZLinkStoreLocationResolvers({
+            stores: { ...stores, authorityStore: stores.locationStore },
+            leaseTracker: this.leaseTracker(stores),
+            events: this.events,
+            spotMeshNames,
+            routeCacheMaxAgeMs: this.options.registration.locations.options.routeCacheMaxAgeMs
+        });
+    }
+    ownerNodeRid(spotNodeRuntime) {
+        const primaryMeshNode = spotNodeRuntime?.primaryMeshNode;
+        const spotNodeRid = primaryMeshNode === undefined
+            ? undefined
+            : String(primaryMeshNode.status().routingId);
+        if (spotNodeRid !== undefined) {
+            return spotNodeRid;
+        }
+        for (const channel of this.options.registration.channels.values()) {
+            const routingId = channel.routingId ?? channel.server?.routingId;
+            if (routingId !== undefined) {
+                return routingId;
+            }
+        }
+        for (const routeChannel of this.options.registration.routeChannelOptions.values()) {
+            if (routeChannel.routingId !== undefined) {
+                return routeChannel.routingId;
+            }
+        }
+        for (const spotNode of this.options.registration.spotNodes.values()) {
+            const routingId = spotNode.routingId ?? spotNode.router?.routingId ?? spotNode.pubSub?.routingId;
+            if (routingId !== undefined) {
+                return routingId;
+            }
+        }
+        return this.options.fallbackNodeRid;
+    }
+    async startForRuntime(primaryMeshName, spotNodeRuntime, channelRuntime) {
+        const runtime = this.ensureRuntime(primaryMeshName);
+        if (runtime === undefined) {
+            return undefined;
+        }
+        await runtime.start(this.ownerNodeRid(spotNodeRuntime));
+        const stores = this.currentStores;
+        if (stores === undefined) {
+            return runtime;
+        }
+        spotNodeRuntime.configureLocationAutoConnect(runtime, stores, this.options.registration.locations.options, this.currentEvents);
+        await spotNodeRuntime.startLocationAutoConnect();
+        channelRuntime.configureLocationAutoConnect(runtime, stores, this.options.registration.locations.options, this.currentEvents);
+        await channelRuntime.startLocationAutoConnect();
+        return runtime;
+    }
+    clearForStop() {
+        const snapshot = {
+            runtime: this.runtime,
+            lifecycle: this.lifecycle
+        };
+        this.stores = undefined;
+        this.runtime = undefined;
+        this.lifecycle = undefined;
+        this.events = undefined;
+        this.leaseTrackerState = undefined;
+        return snapshot;
+    }
+    createRuntimeStores() {
+        const locations = this.options.registration.locations;
+        if (locations.useInMemoryStores) {
+            const provider = new locations_1.ZLinkInMemoryProviderLocationStore();
+            const store = new locations_1.ZLinkLocationStoreRepository(provider);
+            return {
+                locationStore: store,
+                authorityStore: store,
+                clientServerStore: store,
+                fanoutStore: store,
+                peerStore: store,
+                spotStore: store,
+                actorStore: store,
+                routeStore: store,
+                ownerLeaseStore: store
+            };
+        }
+        const provider = locations.storeInstance;
+        if (provider !== undefined) {
+            const store = new locations_1.ZLinkLocationStoreRepository(provider);
+            return {
+                locationStore: store,
+                authorityStore: store,
+                clientServerStore: store,
+                fanoutStore: store,
+                peerStore: store,
+                spotStore: store,
+                actorStore: store,
+                routeStore: store,
+                ownerLeaseStore: store
+            };
+        }
+        return undefined;
+    }
+    createAndRememberStores() {
+        if (this.stores !== undefined)
+            return this.stores;
+        this.stores = this.createRuntimeStores();
+        return this.stores;
+    }
+    leaseTracker(stores) {
+        if (this.leaseTrackerState?.stores === stores) {
+            return this.leaseTrackerState.tracker;
+        }
+        const tracker = new locations_1.ZLinkOwnerLeaseTracker({
+            store: stores.ownerLeaseStore,
+            options: this.options.registration.locations.options
+        });
+        this.leaseTrackerState = { stores, tracker };
+        return tracker;
+    }
+    ensureEvents() {
+        return this.events;
+    }
+}
+exports.ZLinkLocationRuntimeOwner = ZLinkLocationRuntimeOwner;
+function isActorTransferStore(value) {
+    const store = value;
+    return typeof store.prepareActorTransfer === 'function'
+        && typeof store.commitActorTransfer === 'function'
+        && typeof store.activateActorTransfer === 'function'
+        && typeof store.abortActorTransfer === 'function'
+        && typeof store.takeOverActorTransfer === 'function'
+        && typeof store.resolveActorTransfer === 'function';
+}

package/dist/runtime/host/mesh-router-resolver.d.ts

@@ -0,0 +1,16 @@
+import type { RoutingId } from '../../contracts';
+import type { ZLinkFrameworkRegistration } from '../configuration';
+import type { ZLinkRemoteBoundSessionTarget } from '../actors';
+export declare class MeshRouterResolver {
+    private readonly registration;
+    constructor(registration: ZLinkFrameworkRegistration);
+    canUseRouterChannel(routerChannelId: string): boolean;
+    classifyManualNodeTarget(meshName: string, targetNodeRid: RoutingId): boolean | undefined;
+    defaultRouterChannelId(): string | undefined;
+    defaultSpotRouterChannelId(): string | undefined;
+    remoteBoundSessionTargetForSource(sourceNodeRid: RoutingId): ZLinkRemoteBoundSessionTarget | undefined;
+    primaryMeshName(): string | undefined;
+    actorMeshName(actorType: string): string | undefined;
+    spotLocationMeshNames(): readonly string[];
+    spotRouterChannelIdByMesh(): (meshName: string) => string;
+}

package/dist/runtime/host/mesh-router-resolver.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MeshRouterResolver = void 0;
+const routing_id_1 = require("../routing-id");
+class MeshRouterResolver {
+    registration;
+    constructor(registration) {
+        this.registration = registration;
+    }
+    canUseRouterChannel(routerChannelId) {
+        return this.registration.routeChannels.has(routerChannelId)
+            || this.registration.spotNodes.get(routerChannelId)?.router !== undefined;
+    }
+    classifyManualNodeTarget(meshName, targetNodeRid) {
+        const router = this.registration.spotNodes.get(meshName)?.router;
+        if (router === undefined)
+            return undefined;
+        const manualConnections = router.manualConnections ?? [];
+        const manualPeers = router.manualPeerConnections ?? [];
+        if (manualConnections.length === 0 && manualPeers.length === 0)
+            return undefined;
+        if (manualPeers.some((peer) => (0, routing_id_1.routingIdsEqual)(peer.peerRid, targetNodeRid)))
+            return true;
+        return manualConnections.length === 0 ? false : undefined;
+    }
+    defaultRouterChannelId() {
+        const candidates = [
+            ...this.registration.routeChannels,
+            ...[...this.registration.spotNodes.entries()]
+                .filter(([, spotNode]) => spotNode.router !== undefined)
+                .map(([spotNodeName]) => spotNodeName)
+        ];
+        return candidates.length === 1 ? candidates[0] : undefined;
+    }
+    defaultSpotRouterChannelId() {
+        const candidates = [...this.registration.spotNodes.entries()]
+            .filter(([, spotNode]) => spotNode.router !== undefined)
+            .map(([spotNodeName]) => spotNodeName);
+        return candidates.length === 1 ? candidates[0] : undefined;
+    }
+    remoteBoundSessionTargetForSource(sourceNodeRid) {
+        const routerChannelId = this.defaultSpotRouterChannelId()
+            ?? this.defaultRouterChannelId();
+        if (routerChannelId === undefined) {
+            return undefined;
+        }
+        const targetNodeRid = (0, routing_id_1.normalizeRoutingId)(sourceNodeRid);
+        return {
+            routerChannelId,
+            targetNodeRid,
+            spotId: targetNodeRid
+        };
+    }
+    primaryMeshName() {
+        const names = [...this.registration.spotNodes.entries()]
+            .filter(([, node]) => node.entrySpotType !== undefined
+            || (node.spotFactories?.length ?? 0) > 0
+            || (node.actorFactories instanceof Map
+                ? node.actorFactories.size > 0
+                : Object.keys(node.actorFactories ?? {}).length > 0))
+            .map(([name]) => name);
+        if (names.length === 1)
+            return names[0];
+        if (names.length > 1)
+            return undefined;
+        const allMeshNames = [...this.registration.spotNodes.keys()];
+        return allMeshNames.length === 1 ? allMeshNames[0] : undefined;
+    }
+    actorMeshName(actorType) {
+        const matches = [...this.registration.spotNodes.entries()]
+            .filter(([, node]) => node.actorFactories instanceof Map
+            ? node.actorFactories.has(actorType)
+            : node.actorFactories !== undefined && Object.hasOwn(node.actorFactories, actorType))
+            .map(([name]) => name);
+        return matches.length === 1 ? matches[0] : undefined;
+    }
+    spotLocationMeshNames() {
+        return [...new Set([
+                ...this.registration.spotNodes.keys(),
+                ...this.registration.routeChannels.keys()
+            ])];
+    }
+    spotRouterChannelIdByMesh() {
+        const routeChannels = [...this.registration.routeChannelOptions.values()];
+        const mapped = new Map();
+        for (const [spotMeshName, spotNode] of this.registration.spotNodes.entries()) {
+            const conventionalRouteChannelId = `${spotMeshName}.route`;
+            if (this.registration.routeChannels.has(conventionalRouteChannelId)
+                || this.registration.routeChannelOptions.has(conventionalRouteChannelId)) {
+                mapped.set(spotMeshName, conventionalRouteChannelId);
+                continue;
+            }
+            const spotNodeRid = spotNode.router?.routingId ?? spotNode.routingId;
+            if (spotNodeRid === undefined) {
+                continue;
+            }
+            const candidates = routeChannels
+                .filter((routeChannel) => routeChannel.routingId !== undefined &&
+                (0, routing_id_1.routingIdsEqual)(routeChannel.routingId, spotNodeRid))
+                .map((routeChannel) => routeChannel.routerChannelId);
+            if (candidates.length === 1) {
+                mapped.set(spotMeshName, candidates[0]);
+            }
+        }
+        return (meshName) => mapped.get(meshName) ?? meshName;
+    }
+}
+exports.MeshRouterResolver = MeshRouterResolver;

package/dist/runtime/host/relocation-direct-transfer.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Conservative chunk size for paths without a negotiated target receive cap.
+ * Spec 28 §4.2: when no admission reply announced the target's effective
+ * receive chunk limit, the source uses the 32 KiB value that is safe on any
+ * deployment.
+ */
+export declare const RELOCATION_CONSERVATIVE_CHUNK_LIMIT_BYTES: number;
+/**
+ * Phase 1 conservative in-flight budget floor. Until Core exposes the
+ * per-pipe applied HWM observation API, the effective budget is
+ * min(configured, this constant) — spec 28 §5.3 (구현 노트: Phase 1 근사).
+ */
+export declare const RELOCATION_PHASE1_CONSERVATIVE_BUDGET_BYTES: number;
+/**
+ * Effective chunk size limit for one Actor Join's relocation state chunks:
+ * min(configured, target's advertised cap, conservative floor). 0 from the
+ * target means "not advertised" and does not participate in the min (spec
+ * 15 §4.2).
+ */
+export declare function effectiveActorJoinChunkLimitBytes(configuredChunkLimitBytes: number, advertisedReceiveChunkLimitBytes: number | undefined): number;
+export interface ZLinkRelocationChunkPlan {
+    readonly chunkBytes: number;
+    readonly chunkCount: number;
+    readonly totalLength: number;
+    readonly checksumCrc32c: number;
+}
+/**
+ * Splits one relocation payload into ordered chunks that satisfy the shared
+ * wire bounds (chunk data <= 64 MiB, chunk count <= 4096). The configured
+ * limit is honoured unless the count bound forces larger chunks.
+ */
+export declare function planRelocationChunks(payload: Uint8Array, configuredChunkLimitBytes: number): ZLinkRelocationChunkPlan;
+export declare function relocationChunkAt(payload: Uint8Array, plan: ZLinkRelocationChunkPlan, ordinal: number): Buffer;
+export type ZLinkRelocationChunkAcceptance = 'accepted' | 'duplicate' | 'completed';
+/**
+ * Target-side assembly buffer for one exact relocation identity. Chunks are
+ * copied out of their transport lease immediately; once every chunk arrived
+ * the payload checksum is verified exactly once. A checksum mismatch is a
+ * non-retryable explicit failure (spec 28 §4.3) and partial payloads are
+ * never exposed.
+ */
+export declare class ZLinkRelocationPayloadAssembly {
+    readonly totalLength: number;
+    readonly chunkCount: number;
+    readonly checksumCrc32c: number;
+    private readonly buffer;
+    private nextOrdinal;
+    private receivedBytes;
+    private outcome?;
+    private readonly waiters;
+    constructor(totalLength: number, chunkCount: number, checksumCrc32c: number);
+    get completed(): boolean;
+    /** Copies one in-order chunk into the assembly buffer. */
+    accept(ordinal: number, data: Uint8Array): ZLinkRelocationChunkAcceptance;
+    /** Resolves with the verified payload or rejects with the explicit failure. */
+    payload(): Promise<Buffer>;
+    /** Ends the assembly with an explicit failure (identity conflict, abort). */
+    fail(message: string): Error;
+    private finish;
+    private conflict;
+}
+/**
+ * Byte budget for relocation payload bytes concurrently in flight on one
+ * scope (per-peer connection or whole node). A zero limit disables the
+ * budget. Acquisition larger than the whole budget is still admitted when
+ * nothing else is in flight, so no payload size is unable to start.
+ */
+export declare class ZLinkRelocationInFlightBudget {
+    readonly limitBytes: number;
+    private inFlight;
+    private readonly waiters;
+    constructor(limitBytes: number);
+    get inFlightBytes(): number;
+    /** Waits for room, charges the bytes, and returns the exactly-once release. */
+    acquire(bytes: number, signal?: AbortSignal): Promise<() => void>;
+    /** Pre-seal admission wait: resolves while the budget has any headroom. */
+    waitForHeadroom(signal?: AbortSignal): Promise<void>;
+    private waitForRelease;
+}
+/** Effective Phase 1 budget: min(configured, conservative floor); 0 = off. */
+export declare function effectiveRelocationBudgetBytes(configuredBytes: number): number;

package/dist/runtime/host/relocation-direct-transfer.js

@@ -0,0 +1,240 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkRelocationInFlightBudget = exports.ZLinkRelocationPayloadAssembly = exports.RELOCATION_PHASE1_CONSERVATIVE_BUDGET_BYTES = exports.RELOCATION_CONSERVATIVE_CHUNK_LIMIT_BYTES = void 0;
+exports.effectiveActorJoinChunkLimitBytes = effectiveActorJoinChunkLimitBytes;
+exports.planRelocationChunks = planRelocationChunks;
+exports.relocationChunkAt = relocationChunkAt;
+exports.effectiveRelocationBudgetBytes = effectiveRelocationBudgetBytes;
+const service_stateful_wire_codec_1 = require("../foundation/service-stateful-wire-codec");
+const service_relocation_runtime_1 = require("../foundation/service-relocation-runtime");
+/**
+ * Conservative chunk size for paths without a negotiated target receive cap.
+ * Spec 28 §4.2: when no admission reply announced the target's effective
+ * receive chunk limit, the source uses the 32 KiB value that is safe on any
+ * deployment.
+ */
+exports.RELOCATION_CONSERVATIVE_CHUNK_LIMIT_BYTES = 32 * 1024;
+/**
+ * Phase 1 conservative in-flight budget floor. Until Core exposes the
+ * per-pipe applied HWM observation API, the effective budget is
+ * min(configured, this constant) — spec 28 §5.3 (구현 노트: Phase 1 근사).
+ */
+exports.RELOCATION_PHASE1_CONSERVATIVE_BUDGET_BYTES = 8 * 1024 * 1024;
+/**
+ * Effective chunk size limit for one Actor Join's relocation state chunks:
+ * min(configured, target's advertised cap, conservative floor). 0 from the
+ * target means "not advertised" and does not participate in the min (spec
+ * 15 §4.2).
+ */
+function effectiveActorJoinChunkLimitBytes(configuredChunkLimitBytes, advertisedReceiveChunkLimitBytes) {
+    const candidates = [configuredChunkLimitBytes, exports.RELOCATION_CONSERVATIVE_CHUNK_LIMIT_BYTES];
+    if (advertisedReceiveChunkLimitBytes !== undefined && advertisedReceiveChunkLimitBytes > 0) {
+        candidates.push(advertisedReceiveChunkLimitBytes);
+    }
+    return Math.min(...candidates);
+}
+/**
+ * Splits one relocation payload into ordered chunks that satisfy the shared
+ * wire bounds (chunk data <= 64 MiB, chunk count <= 4096). The configured
+ * limit is honoured unless the count bound forces larger chunks.
+ */
+function planRelocationChunks(payload, configuredChunkLimitBytes) {
+    if (!Number.isInteger(configuredChunkLimitBytes) || configuredChunkLimitBytes <= 0) {
+        throw new RangeError('relocationPayloadChunkLimitBytes must be a positive integer.');
+    }
+    const totalLength = payload.byteLength;
+    let chunkBytes = Math.min(configuredChunkLimitBytes, exports.RELOCATION_CONSERVATIVE_CHUNK_LIMIT_BYTES);
+    if (Math.ceil(totalLength / chunkBytes) > service_stateful_wire_codec_1.RELOCATION_PAYLOAD_CHUNK_COUNT_MAX) {
+        chunkBytes = Math.ceil(totalLength / service_stateful_wire_codec_1.RELOCATION_PAYLOAD_CHUNK_COUNT_MAX);
+    }
+    if (chunkBytes > service_stateful_wire_codec_1.RELOCATION_STATE_CHUNK_DATA_MAX_BYTES) {
+        throw new RangeError('Relocation payload exceeds the direct transfer size bound.');
+    }
+    const chunkCount = Math.max(1, Math.ceil(totalLength / chunkBytes));
+    return {
+        chunkBytes,
+        chunkCount,
+        totalLength,
+        checksumCrc32c: (0, service_relocation_runtime_1.crc32c)(payload)
+    };
+}
+function relocationChunkAt(payload, plan, ordinal) {
+    if (!Number.isInteger(ordinal) || ordinal < 0 || ordinal >= plan.chunkCount) {
+        throw new RangeError('Relocation chunk ordinal is out of range.');
+    }
+    const source = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
+    return source.subarray(ordinal * plan.chunkBytes, Math.min(source.byteLength, (ordinal + 1) * plan.chunkBytes));
+}
+/**
+ * Target-side assembly buffer for one exact relocation identity. Chunks are
+ * copied out of their transport lease immediately; once every chunk arrived
+ * the payload checksum is verified exactly once. A checksum mismatch is a
+ * non-retryable explicit failure (spec 28 §4.3) and partial payloads are
+ * never exposed.
+ */
+class ZLinkRelocationPayloadAssembly {
+    totalLength;
+    chunkCount;
+    checksumCrc32c;
+    buffer;
+    nextOrdinal = 0;
+    receivedBytes = 0;
+    outcome;
+    waiters = [];
+    constructor(totalLength, chunkCount, checksumCrc32c) {
+        this.totalLength = totalLength;
+        this.chunkCount = chunkCount;
+        this.checksumCrc32c = checksumCrc32c;
+        if (!Number.isSafeInteger(totalLength) || totalLength < 0) {
+            throw new RangeError('Relocation payload total length is invalid.');
+        }
+        if (!Number.isInteger(chunkCount) || chunkCount < 0
+            || chunkCount > service_stateful_wire_codec_1.RELOCATION_PAYLOAD_CHUNK_COUNT_MAX
+            || (totalLength > 0 && chunkCount === 0)) {
+            throw new RangeError('Relocation payload chunk count is invalid.');
+        }
+        this.buffer = Buffer.alloc(totalLength);
+        if (chunkCount === 0)
+            this.finish();
+    }
+    get completed() {
+        return this.outcome !== undefined && 'payload' in this.outcome;
+    }
+    /** Copies one in-order chunk into the assembly buffer. */
+    accept(ordinal, data) {
+        if (this.outcome !== undefined) {
+            if ('error' in this.outcome)
+                throw this.outcome.error;
+            return ordinal < this.chunkCount ? 'duplicate' : this.conflict(`Relocation chunk ordinal ${ordinal} arrived after assembly completed.`);
+        }
+        if (ordinal < this.nextOrdinal)
+            return 'duplicate';
+        if (ordinal !== this.nextOrdinal || ordinal >= this.chunkCount) {
+            return this.conflict(`Relocation chunk ordinal ${ordinal} does not continue the ordered assembly.`);
+        }
+        if (this.receivedBytes + data.byteLength > this.totalLength) {
+            return this.conflict('Relocation chunks exceed the declared payload length.');
+        }
+        if (ordinal === this.chunkCount - 1
+            && this.receivedBytes + data.byteLength !== this.totalLength) {
+            return this.conflict('Relocation chunks do not cover the declared payload length.');
+        }
+        this.buffer.set(data, this.receivedBytes);
+        this.receivedBytes += data.byteLength;
+        this.nextOrdinal += 1;
+        if (this.nextOrdinal === this.chunkCount) {
+            this.finish();
+            return 'completed';
+        }
+        return 'accepted';
+    }
+    /** Resolves with the verified payload or rejects with the explicit failure. */
+    payload() {
+        if (this.outcome !== undefined) {
+            return 'payload' in this.outcome
+                ? Promise.resolve(this.outcome.payload)
+                : Promise.reject(this.outcome.error);
+        }
+        return new Promise((resolve, reject) => {
+            this.waiters.push({ resolve, reject });
+        });
+    }
+    /** Ends the assembly with an explicit failure (identity conflict, abort). */
+    fail(message) {
+        if (this.outcome !== undefined) {
+            return 'error' in this.outcome ? this.outcome.error : new Error(message);
+        }
+        const error = new Error(message);
+        this.outcome = { error };
+        for (const waiter of this.waiters.splice(0))
+            waiter.reject(error);
+        return error;
+    }
+    finish() {
+        if ((0, service_relocation_runtime_1.crc32c)(this.buffer) !== this.checksumCrc32c) {
+            // Spec 28 §9: an assembled-checksum mismatch on an ordered reliable
+            // connection signals an implementation defect or memory corruption.
+            // It is an explicit, non-retryable failure and the partial payload is
+            // never used for Restore.
+            throw this.fail('Relocation payload checksum mismatch after chunk assembly.');
+        }
+        this.outcome = { payload: this.buffer };
+        for (const waiter of this.waiters.splice(0))
+            waiter.resolve(this.buffer);
+    }
+    conflict(message) {
+        throw this.fail(message);
+    }
+}
+exports.ZLinkRelocationPayloadAssembly = ZLinkRelocationPayloadAssembly;
+/**
+ * Byte budget for relocation payload bytes concurrently in flight on one
+ * scope (per-peer connection or whole node). A zero limit disables the
+ * budget. Acquisition larger than the whole budget is still admitted when
+ * nothing else is in flight, so no payload size is unable to start.
+ */
+class ZLinkRelocationInFlightBudget {
+    limitBytes;
+    inFlight = 0;
+    waiters = [];
+    constructor(limitBytes) {
+        this.limitBytes = limitBytes;
+        if (!Number.isSafeInteger(limitBytes) || limitBytes < 0) {
+            throw new RangeError('Relocation in-flight budget must be a non-negative integer.');
+        }
+    }
+    get inFlightBytes() {
+        return this.inFlight;
+    }
+    /** Waits for room, charges the bytes, and returns the exactly-once release. */
+    async acquire(bytes, signal) {
+        if (!Number.isSafeInteger(bytes) || bytes < 0) {
+            throw new RangeError('Relocation budget charge must be a non-negative integer.');
+        }
+        while (this.limitBytes !== 0
+            && this.inFlight > 0
+            && this.inFlight + bytes > this.limitBytes) {
+            await this.waitForRelease(signal);
+        }
+        this.inFlight += bytes;
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.inFlight -= bytes;
+            for (const waiter of this.waiters.splice(0))
+                waiter();
+        };
+    }
+    /** Pre-seal admission wait: resolves while the budget has any headroom. */
+    async waitForHeadroom(signal) {
+        while (this.limitBytes !== 0 && this.inFlight >= this.limitBytes) {
+            await this.waitForRelease(signal);
+        }
+    }
+    waitForRelease(signal) {
+        signal?.throwIfAborted();
+        return new Promise((resolve, reject) => {
+            const waiter = () => {
+                signal?.removeEventListener('abort', aborted);
+                resolve();
+            };
+            const aborted = () => {
+                const index = this.waiters.indexOf(waiter);
+                if (index >= 0)
+                    this.waiters.splice(index, 1);
+                reject(signal?.reason);
+            };
+            signal?.addEventListener('abort', aborted, { once: true });
+            this.waiters.push(waiter);
+        });
+    }
+}
+exports.ZLinkRelocationInFlightBudget = ZLinkRelocationInFlightBudget;
+/** Effective Phase 1 budget: min(configured, conservative floor); 0 = off. */
+function effectiveRelocationBudgetBytes(configuredBytes) {
+    if (configuredBytes === 0)
+        return 0;
+    return Math.min(configuredBytes, exports.RELOCATION_PHASE1_CONSERVATIVE_BUDGET_BYTES);
+}

package/dist/runtime/host/relocation-integrity-fault-gate.d.ts

@@ -0,0 +1,6 @@
+/** Internal E2E-only fault seam for direct relocation transfer integrity cases. */
+export declare const ZLINK_INTERNAL_RELOCATION_INTEGRITY_FAULT_GATE: unique symbol;
+export interface ZLinkInternalRelocationIntegrityFaultGate {
+    consumeChecksumMismatch(): boolean;
+    consumeIdentityConflict(): boolean;
+}