@zlink-systems/framework 0.10.0

package/dist/runtime/foundation/route-mesh-connection-policy.d.ts

@@ -0,0 +1,3 @@
+import type { ServiceNodeDescriptor, ServiceObjectRole } from './service-topology-registry';
+export declare function routeMeshConnectionNotRequired(localObjectRole: ServiceObjectRole, localHasServerChannel: boolean, remoteObjectRole: ServiceObjectRole, remoteHasServerChannel: boolean): boolean;
+export declare function descriptorConnectionNotRequired(local: ServiceNodeDescriptor, remote: ServiceNodeDescriptor): boolean;

package/dist/runtime/foundation/route-mesh-connection-policy.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routeMeshConnectionNotRequired = routeMeshConnectionNotRequired;
+exports.descriptorConnectionNotRequired = descriptorConnectionNotRequired;
+function routeMeshConnectionNotRequired(localObjectRole, localHasServerChannel, remoteObjectRole, remoteHasServerChannel) {
+    return localObjectRole === 'client'
+        && !localHasServerChannel
+        && remoteObjectRole === 'client'
+        && !remoteHasServerChannel;
+}
+function descriptorConnectionNotRequired(local, remote) {
+    return routeMeshConnectionNotRequired(local.objectRole, local.channels.length > 0, remote.objectRole, remote.channels.length > 0);
+}

package/dist/runtime/foundation/runtime-state-projections.d.ts

@@ -0,0 +1,13 @@
+import { ZLinkFrameworkRuntimeState } from '../../contracts';
+export type MaintenanceAdmissionState = 'preparing' | 'serving' | 'retiring' | 'draining' | 'stopped' | 'error';
+export type DiscoveryAvailability = 'preparing' | 'serving' | 'retiring' | 'stopped' | 'error' | 'disconnected';
+/** Derives public readiness from the public runtime state authority. */
+export declare function runtimeStateIsReady(state: ZLinkFrameworkRuntimeState): boolean;
+/** Keeps admission gating separate from the public readiness projection. */
+export declare function runtimeAcceptsWork(state: ZLinkFrameworkRuntimeState, admissionOpen: boolean): boolean;
+/** Projects public state into the maintenance admission bounded context. */
+export declare function maintenanceAdmissionState(state: ZLinkFrameworkRuntimeState): MaintenanceAdmissionState;
+/** Projects public state into discovery without creating transport-only state. */
+export declare function discoveryAvailabilityForRuntimeState(state: ZLinkFrameworkRuntimeState): Exclude<DiscoveryAvailability, 'disconnected'>;
+/** Combines host readiness with the target projection without changing host state. */
+export declare function topologyRuntimeIsReady(state: ZLinkFrameworkRuntimeState, readyTargetCount: number): boolean;

package/dist/runtime/foundation/runtime-state-projections.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runtimeStateIsReady = runtimeStateIsReady;
+exports.runtimeAcceptsWork = runtimeAcceptsWork;
+exports.maintenanceAdmissionState = maintenanceAdmissionState;
+exports.discoveryAvailabilityForRuntimeState = discoveryAvailabilityForRuntimeState;
+exports.topologyRuntimeIsReady = topologyRuntimeIsReady;
+const contracts_1 = require("../../contracts");
+/** Derives public readiness from the public runtime state authority. */
+function runtimeStateIsReady(state) {
+    return state === contracts_1.ZLinkFrameworkRuntimeState.Serving;
+}
+/** Keeps admission gating separate from the public readiness projection. */
+function runtimeAcceptsWork(state, admissionOpen) {
+    return runtimeStateIsReady(state) && admissionOpen;
+}
+/** Projects public state into the maintenance admission bounded context. */
+function maintenanceAdmissionState(state) {
+    switch (state) {
+        case contracts_1.ZLinkFrameworkRuntimeState.Preparing: return 'preparing';
+        case contracts_1.ZLinkFrameworkRuntimeState.Serving: return 'serving';
+        case contracts_1.ZLinkFrameworkRuntimeState.Relocating:
+        case contracts_1.ZLinkFrameworkRuntimeState.Relocated: return 'retiring';
+        case contracts_1.ZLinkFrameworkRuntimeState.Draining: return 'draining';
+        case contracts_1.ZLinkFrameworkRuntimeState.Stopped: return 'stopped';
+        case contracts_1.ZLinkFrameworkRuntimeState.Error: return 'error';
+    }
+}
+/** Projects public state into discovery without creating transport-only state. */
+function discoveryAvailabilityForRuntimeState(state) {
+    switch (state) {
+        case contracts_1.ZLinkFrameworkRuntimeState.Preparing: return 'preparing';
+        case contracts_1.ZLinkFrameworkRuntimeState.Serving: return 'serving';
+        case contracts_1.ZLinkFrameworkRuntimeState.Relocating:
+        case contracts_1.ZLinkFrameworkRuntimeState.Relocated:
+        case contracts_1.ZLinkFrameworkRuntimeState.Draining: return 'retiring';
+        case contracts_1.ZLinkFrameworkRuntimeState.Stopped: return 'stopped';
+        case contracts_1.ZLinkFrameworkRuntimeState.Error: return 'error';
+    }
+}
+/** Combines host readiness with the target projection without changing host state. */
+function topologyRuntimeIsReady(state, readyTargetCount) {
+    return runtimeStateIsReady(state) && readyTargetCount > 0;
+}

package/dist/runtime/foundation/service-authority-payload-codec.d.ts

@@ -0,0 +1,56 @@
+import type { ZLinkLocationOwnerToken } from '../../contracts/Locations';
+export interface ServiceReadySpotAuthority {
+    readonly kind: 'user_spot' | 'instance_spot';
+    readonly stableType: string;
+    readonly spotId: string;
+    readonly ownerId: string;
+    readonly ownerLeaseGeneration: bigint;
+    readonly ownerMeshName: string;
+    readonly ownerNodeRid: string;
+    readonly ownerNodeGeneration: bigint;
+    readonly activationRecovery?: ServiceActivationRecoveryState;
+}
+export interface ServiceDecodedInstanceAuthority extends ServiceReadySpotAuthority {
+    readonly kind: 'instance_spot';
+    readonly state: 'coldActivating' | 'ready' | 'closing';
+}
+export interface ServiceActivationRecoveryState {
+    readonly reference: string;
+    readonly sha256: Uint8Array;
+    readonly encodedSize: number;
+    readonly inboxSequence: bigint;
+    readonly replayCursor: bigint;
+}
+export interface ServiceInstanceAuthorityPayload {
+    readonly state: 'coldActivating' | 'ready' | 'closing';
+    readonly stableType: string;
+    readonly spotId: string;
+    readonly ownerId: string;
+    readonly ownerLeaseGeneration: bigint;
+    readonly ownerMeshName: string;
+    readonly ownerNodeRid: string;
+    readonly ownerNodeGeneration: bigint;
+    readonly activationRecovery?: ServiceActivationRecoveryState;
+}
+export interface ServiceUserSpotAuthorityPayload {
+    readonly state: 'creating' | 'ready' | 'closing';
+    readonly stableType: string;
+    readonly spotId: string;
+    readonly ownerId: string;
+    readonly ownerLeaseGeneration: bigint;
+    readonly ownerMeshName: string;
+    readonly ownerNodeRid: string;
+    readonly ownerNodeGeneration: bigint;
+}
+/** Replaces only authority-relocation-state and preserves the canonical owner payload. */
+export declare function replaceServiceAuthorityRelocationState(payload: Uint8Array, relocationState: Uint8Array): Buffer;
+export declare function encodeServiceUserSpotAuthorityPayload(value: ServiceUserSpotAuthorityPayload): Buffer;
+export declare function encodeServiceInstanceAuthorityPayload(value: ServiceInstanceAuthorityPayload): Buffer;
+export declare function decodeServiceReadySpotAuthority(payload: Uint8Array): ServiceReadySpotAuthority | undefined;
+export declare function decodeServiceInstanceAuthorityPayload(payload: Uint8Array): ServiceDecodedInstanceAuthority | undefined;
+export declare function rewriteServiceAuthorityOwner(payload: Uint8Array, owner: ZLinkLocationOwnerToken): Buffer | undefined;
+export declare function rewriteServiceAuthorityRoute(payload: Uint8Array, owner: ZLinkLocationOwnerToken, target: {
+    readonly meshName: string;
+    readonly nodeRid: string;
+    readonly nodeGeneration: bigint;
+}): Buffer | undefined;

package/dist/runtime/foundation/service-authority-payload-codec.js

@@ -0,0 +1,411 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.replaceServiceAuthorityRelocationState = replaceServiceAuthorityRelocationState;
+exports.encodeServiceUserSpotAuthorityPayload = encodeServiceUserSpotAuthorityPayload;
+exports.encodeServiceInstanceAuthorityPayload = encodeServiceInstanceAuthorityPayload;
+exports.decodeServiceReadySpotAuthority = decodeServiceReadySpotAuthority;
+exports.decodeServiceInstanceAuthorityPayload = decodeServiceInstanceAuthorityPayload;
+exports.rewriteServiceAuthorityOwner = rewriteServiceAuthorityOwner;
+exports.rewriteServiceAuthorityRoute = rewriteServiceAuthorityRoute;
+const service_relocation_runtime_1 = require("./service-relocation-runtime");
+const AUTHORITY_MAGIC = Buffer.from([0x5a, 0x4c, 0x41, 0x55]);
+const AUTHORITY_FORMAT_VERSION = 1;
+const AUTHORITY_FLAGS = 0;
+const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true });
+/** Replaces only authority-relocation-state and preserves the canonical owner payload. */
+function replaceServiceAuthorityRelocationState(payload, relocationState) {
+    const bytes = Buffer.from(payload);
+    const reader = new AuthorityReader(bytes);
+    reader.expect(AUTHORITY_MAGIC);
+    if (reader.u8() !== AUTHORITY_FORMAT_VERSION || reader.u16() !== AUTHORITY_FLAGS) {
+        throw new TypeError('Authority payload header is invalid.');
+    }
+    const bodyLength = reader.u32();
+    const body = reader.takeReader(bodyLength);
+    const checksumOffset = reader.offset;
+    const checksum = reader.u32();
+    if (!reader.done || (0, service_relocation_runtime_1.crc32c)(bytes.subarray(0, checksumOffset)) !== checksum) {
+        throw new TypeError('Authority payload checksum is invalid.');
+    }
+    body.u8();
+    body.u8();
+    body.skip(body.u16());
+    body.text8();
+    body.nonZeroU64();
+    body.text8();
+    body.rid();
+    body.nonZeroU64();
+    const relocationOffset = body.offset;
+    body.bool8();
+    body.skip(body.u32());
+    const relocationEnd = body.offset;
+    const currentBody = bytes.subarray(11, 11 + bodyLength);
+    const nextBody = Buffer.concat([
+        currentBody.subarray(0, relocationOffset),
+        Buffer.from(relocationState),
+        currentBody.subarray(relocationEnd)
+    ]);
+    const envelope = Buffer.concat([
+        AUTHORITY_MAGIC,
+        Buffer.of(AUTHORITY_FORMAT_VERSION),
+        u16(AUTHORITY_FLAGS),
+        u32(nextBody.byteLength),
+        nextBody
+    ]);
+    return Buffer.concat([envelope, u32((0, service_relocation_runtime_1.crc32c)(envelope))]);
+}
+function encodeServiceUserSpotAuthorityPayload(value) {
+    const spot = conditional(2, concat(rid(value.spotId, 'spotId'), text8(value.stableType, 'stableType'), Buffer.of(1)));
+    const object = conditional(2, spot);
+    const body = concat(Buffer.of(value.state === 'creating' ? 1 : value.state === 'closing' ? 3 : 0), object, text8(value.ownerId, 'ownerId'), u64(value.ownerLeaseGeneration, 'ownerLeaseGeneration'), text8(value.ownerMeshName, 'ownerMeshName'), rid(value.ownerNodeRid, 'ownerNodeRid'), u64(value.ownerNodeGeneration, 'ownerNodeGeneration'), conditional32(0, Buffer.alloc(0)), conditional32(0, Buffer.alloc(0)));
+    const envelope = concat(AUTHORITY_MAGIC, Buffer.of(AUTHORITY_FORMAT_VERSION), u16(AUTHORITY_FLAGS), u32(body.byteLength), body);
+    return concat(envelope, u32((0, service_relocation_runtime_1.crc32c)(envelope)));
+}
+function encodeServiceInstanceAuthorityPayload(value) {
+    if (value.activationRecovery !== undefined && value.state !== 'ready') {
+        throw new RangeError('activationRecovery is allowed only on a Ready Instance Spot authority.');
+    }
+    const instanceBody = concat(text8(value.stableType, 'stableType'), rid(value.spotId, 'spotId'));
+    const instance = conditional(value.state === 'coldActivating' ? 1 : value.state === 'closing' ? 3 : 2, instanceBody);
+    const spot = conditional(3, instance);
+    const object = conditional(2, spot);
+    const activationRecovery = value.activationRecovery === undefined
+        ? conditional32(0, Buffer.alloc(0))
+        : conditional32(1, concat(text16(value.activationRecovery.reference, 'activationRecovery.reference'), sha256(value.activationRecovery.sha256), boundedU32(value.activationRecovery.encodedSize, 'activationRecovery.encodedSize'), u64(value.activationRecovery.inboxSequence, 'activationRecovery.inboxSequence'), ordinalU64(value.activationRecovery.replayCursor, 'activationRecovery.replayCursor')));
+    if (value.activationRecovery !== undefined
+        && value.activationRecovery.replayCursor > value.activationRecovery.inboxSequence) {
+        throw new RangeError('activationRecovery.replayCursor must not exceed inboxSequence.');
+    }
+    const body = concat(Buffer.of(value.state === 'coldActivating' ? 1 : value.state === 'closing' ? 3 : 0), object, text8(value.ownerId, 'ownerId'), u64(value.ownerLeaseGeneration, 'ownerLeaseGeneration'), text8(value.ownerMeshName, 'ownerMeshName'), rid(value.ownerNodeRid, 'ownerNodeRid'), u64(value.ownerNodeGeneration, 'ownerNodeGeneration'), conditional32(0, Buffer.alloc(0)), activationRecovery);
+    const envelope = concat(AUTHORITY_MAGIC, Buffer.of(AUTHORITY_FORMAT_VERSION), u16(AUTHORITY_FLAGS), u32(body.byteLength), body);
+    return concat(envelope, u32((0, service_relocation_runtime_1.crc32c)(envelope)));
+}
+function decodeServiceReadySpotAuthority(payload) {
+    const decoded = decodeSpotAuthority(payload);
+    return decoded?.state === 'ready' && decoded.operationKind === 0
+        ? decoded
+        : undefined;
+}
+function decodeServiceInstanceAuthorityPayload(payload) {
+    const decoded = decodeSpotAuthority(payload);
+    if (decoded?.kind !== 'instance_spot'
+        || !(decoded.state === 'coldActivating' && decoded.operationKind === 1
+            || decoded.state === 'ready' && decoded.operationKind === 0
+            || decoded.state === 'closing' && decoded.operationKind === 3)) {
+        return undefined;
+    }
+    return {
+        ...decoded,
+        kind: 'instance_spot',
+        state: decoded.state
+    };
+}
+function rewriteServiceAuthorityOwner(payload, owner) {
+    const decoded = decodeSpotAuthority(payload);
+    if (decoded === undefined)
+        return undefined;
+    return encodeRewrittenServiceAuthority(decoded, owner, {
+        meshName: decoded.ownerMeshName,
+        nodeRid: decoded.ownerNodeRid,
+        nodeGeneration: decoded.ownerNodeGeneration
+    });
+}
+function rewriteServiceAuthorityRoute(payload, owner, target) {
+    const decoded = decodeSpotAuthority(payload);
+    return decoded === undefined
+        ? undefined
+        : encodeRewrittenServiceAuthority(decoded, owner, target);
+}
+function encodeRewrittenServiceAuthority(decoded, owner, target) {
+    const common = {
+        stableType: decoded.stableType,
+        spotId: decoded.spotId,
+        ownerId: owner.ownerId,
+        ownerLeaseGeneration: owner.leaseGeneration,
+        ownerMeshName: target.meshName,
+        ownerNodeRid: target.nodeRid,
+        ownerNodeGeneration: target.nodeGeneration
+    };
+    if (decoded.kind === 'user_spot') {
+        const state = decoded.operationKind === 0
+            ? 'ready'
+            : decoded.operationKind === 1
+                ? 'creating'
+                : decoded.operationKind === 3
+                    ? 'closing'
+                    : undefined;
+        return state === undefined
+            ? undefined
+            : encodeServiceUserSpotAuthorityPayload({ ...common, state });
+    }
+    if (decoded.state === 'other')
+        return undefined;
+    return encodeServiceInstanceAuthorityPayload({
+        ...common,
+        state: decoded.state,
+        ...(decoded.activationRecovery === undefined
+            ? {}
+            : { activationRecovery: decoded.activationRecovery })
+    });
+}
+function decodeSpotAuthority(payload) {
+    try {
+        const reader = new AuthorityReader(payload);
+        reader.expect(AUTHORITY_MAGIC);
+        if (reader.u8() !== AUTHORITY_FORMAT_VERSION || reader.u16() !== AUTHORITY_FLAGS) {
+            return undefined;
+        }
+        const bodyLength = reader.u32();
+        const body = reader.takeReader(bodyLength);
+        const checksumOffset = reader.offset;
+        const checksum = reader.u32();
+        if (!reader.done || (0, service_relocation_runtime_1.crc32c)(reader.bytes.subarray(0, checksumOffset)) !== checksum) {
+            return undefined;
+        }
+        const operationKind = body.u8();
+        const objectKind = body.u8();
+        const object = body.takeReader(body.u16());
+        if (objectKind !== 2)
+            return undefined;
+        const spotKind = object.u8();
+        const spot = object.takeReader(object.u16());
+        if (!object.done)
+            return undefined;
+        let kind;
+        let state;
+        let stableType;
+        let spotId;
+        if (spotKind === 2) {
+            kind = 'user_spot';
+            spotId = spot.rid();
+            stableType = spot.text8();
+            state = spot.u8();
+        }
+        else if (spotKind === 3) {
+            kind = 'instance_spot';
+            state = spot.u8();
+            const instance = spot.takeReader(spot.u16());
+            stableType = instance.text8();
+            spotId = instance.rid();
+            if (!instance.done)
+                return undefined;
+        }
+        else {
+            return undefined;
+        }
+        if (!spot.done)
+            return undefined;
+        const ownerId = body.text8();
+        const ownerLeaseGeneration = body.nonZeroU64();
+        const ownerMeshName = body.text8();
+        const ownerNodeRid = body.rid();
+        const ownerNodeGeneration = body.nonZeroU64();
+        const hasRelocation = body.bool8();
+        const relocationLength = body.u32();
+        if (hasRelocation || relocationLength !== 0)
+            return undefined;
+        const hasActivationRecovery = body.bool8();
+        const activationRecoveryBody = body.takeReader(body.u32());
+        let activationRecovery;
+        if (hasActivationRecovery) {
+            const reference = activationRecoveryBody.text16();
+            const sha256 = activationRecoveryBody.sizedBytes8(32);
+            const encodedSize = activationRecoveryBody.u32();
+            if (encodedSize > 1024 * 1024)
+                return undefined;
+            const inboxSequence = activationRecoveryBody.nonZeroU64();
+            const replayCursor = activationRecoveryBody.u64();
+            if (replayCursor > inboxSequence)
+                return undefined;
+            activationRecovery = {
+                reference,
+                sha256,
+                encodedSize,
+                inboxSequence,
+                replayCursor
+            };
+        }
+        if (activationRecovery !== undefined
+            && (kind !== 'instance_spot'
+                || state !== 2
+                || operationKind !== 0)) {
+            return undefined;
+        }
+        if (!activationRecoveryBody.done || !body.done)
+            return undefined;
+        return {
+            kind,
+            state: kind === 'instance_spot'
+                ? state === 1
+                    ? 'coldActivating'
+                    : state === 2
+                        ? 'ready'
+                        : state === 3
+                            ? 'closing'
+                            : 'other'
+                : state === 1 ? 'ready' : 'other',
+            operationKind,
+            stableType,
+            spotId,
+            ownerId,
+            ownerLeaseGeneration,
+            ownerMeshName,
+            ownerNodeRid,
+            ownerNodeGeneration,
+            ...(activationRecovery === undefined ? {} : { activationRecovery })
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function conditional(discriminator, body) {
+    return concat(Buffer.of(discriminator), u16(body.byteLength), body);
+}
+function conditional32(discriminator, body) {
+    return concat(Buffer.of(discriminator), u32(body.byteLength), body);
+}
+function text8(value, name) {
+    return sized8(value, name);
+}
+function rid(value, name) {
+    return sized8(value, name);
+}
+function text16(value, name) {
+    const bytes = Buffer.from(value);
+    if (bytes.byteLength < 1 || bytes.byteLength > 0xffff || bytes.includes(0)) {
+        throw new RangeError(`${name} must contain 1..65535 UTF-8 bytes without NUL.`);
+    }
+    return concat(u16(bytes.byteLength), bytes);
+}
+function sha256(value) {
+    if (value.byteLength !== 32) {
+        throw new RangeError('activationRecovery.sha256 must contain exactly 32 bytes.');
+    }
+    return concat(Buffer.of(32), value);
+}
+function sized8(value, name) {
+    const bytes = Buffer.from(value);
+    if (bytes.byteLength < 1 || bytes.byteLength > 255 || bytes.includes(0)) {
+        throw new RangeError(`${name} must contain 1..255 UTF-8 bytes without NUL.`);
+    }
+    return concat(Buffer.of(bytes.byteLength), bytes);
+}
+function u16(value) {
+    const result = Buffer.alloc(2);
+    result.writeUInt16BE(value);
+    return result;
+}
+function u32(value) {
+    const result = Buffer.alloc(4);
+    result.writeUInt32BE(value);
+    return result;
+}
+function boundedU32(value, name) {
+    if (!Number.isInteger(value) || value < 0 || value > 1024 * 1024) {
+        throw new RangeError(`${name} must be an integer in the range 0..1048576.`);
+    }
+    return u32(value);
+}
+function u64(value, name) {
+    if (value <= 0n || value > 0xffffffffffffffffn) {
+        throw new RangeError(`${name} must be a non-zero u64.`);
+    }
+    const result = Buffer.alloc(8);
+    result.writeBigUInt64BE(value);
+    return result;
+}
+function ordinalU64(value, name) {
+    if (value < 0n || value > 0xffffffffffffffffn) {
+        throw new RangeError(`${name} must be a u64.`);
+    }
+    const result = Buffer.alloc(8);
+    result.writeBigUInt64BE(value);
+    return result;
+}
+function concat(...parts) {
+    return Buffer.concat(parts.map(part => Buffer.from(part)));
+}
+class AuthorityReader {
+    bytes;
+    offset = 0;
+    constructor(payload) {
+        this.bytes = Buffer.from(payload);
+    }
+    get done() {
+        return this.offset === this.bytes.byteLength;
+    }
+    expect(expected) {
+        const value = this.take(expected.byteLength);
+        if (!value.equals(Buffer.from(expected)))
+            throw new Error('Authority payload magic mismatch.');
+    }
+    u8() {
+        return this.take(1)[0];
+    }
+    bool8() {
+        const value = this.u8();
+        if (value !== 0 && value !== 1)
+            throw new Error('Authority bool8 is invalid.');
+        return value === 1;
+    }
+    u16() {
+        return this.take(2).readUInt16BE(0);
+    }
+    u32() {
+        return this.take(4).readUInt32BE(0);
+    }
+    nonZeroU64() {
+        const value = this.take(8).readBigUInt64BE(0);
+        if (value === 0n)
+            throw new Error('Authority non-zero u64 is zero.');
+        return value;
+    }
+    u64() {
+        return this.take(8).readBigUInt64BE(0);
+    }
+    text8() {
+        return this.sized8();
+    }
+    rid() {
+        return this.sized8();
+    }
+    text16() {
+        const length = this.u16();
+        if (length === 0)
+            throw new Error('Authority text is empty.');
+        const value = this.take(length);
+        if (value.includes(0))
+            throw new Error('Authority text contains NUL.');
+        return FATAL_UTF8.decode(value);
+    }
+    sizedBytes8(expectedLength) {
+        const length = this.u8();
+        if (length !== expectedLength)
+            throw new Error('Authority byte field length is invalid.');
+        return Buffer.from(this.take(length));
+    }
+    takeReader(length) {
+        return new AuthorityReader(this.take(length));
+    }
+    skip(length) {
+        this.take(length);
+    }
+    sized8() {
+        const length = this.u8();
+        if (length === 0)
+            throw new Error('Authority text is empty.');
+        const value = this.take(length);
+        if (value.includes(0))
+            throw new Error('Authority text contains NUL.');
+        return FATAL_UTF8.decode(value);
+    }
+    take(length) {
+        if (length < 0 || this.offset + length > this.bytes.byteLength) {
+            throw new Error('Authority payload is truncated.');
+        }
+        const result = this.bytes.subarray(this.offset, this.offset + length);
+        this.offset += length;
+        return result;
+    }
+}

package/dist/runtime/foundation/service-discovery-registry.d.ts

@@ -0,0 +1,42 @@
+export interface ClientServerDescriptor {
+    readonly channelName: string;
+    readonly serverRoutingId: string;
+    readonly lifecycleGeneration: bigint;
+    readonly descriptorRevision: bigint;
+    readonly weight: number;
+    readonly state: 'preparing' | 'serving' | 'retiring' | 'stopped' | 'error' | 'disconnected';
+    readonly securityIdentity: string;
+    readonly effectiveMaxMessageBytes: number;
+    readonly advertisedEndpoint: string;
+}
+export interface FanoutPublisherDescriptor {
+    readonly channelName: string;
+    readonly publisherRoutingId: string;
+    readonly lifecycleGeneration: bigint;
+    readonly descriptorRevision: bigint;
+    readonly advertisedEndpoint: string;
+    readonly state: 'preparing' | 'serving' | 'retiring' | 'stopped' | 'error';
+}
+export interface SelectedClientServer {
+    readonly descriptor: ClientServerDescriptor;
+    readonly connectionId: string;
+}
+/** Dedicated discovery state; fanout publishers never reuse RouteMesh peer rows. */
+export declare class ServiceDiscoveryRegistry {
+    private readonly clientServers;
+    private readonly fanoutPublishers;
+    private readonly clientServerSelections;
+    admitClientServer(descriptor: ClientServerDescriptor, connectionId: string): boolean;
+    markClientServerDisconnected(channelName: string, serverRoutingId: string, connectionId: string): boolean;
+    removeClientServer(channelName: string, serverRoutingId: string, connectionId: string): boolean;
+    selectClientServer(channelName: string): ClientServerDescriptor | undefined;
+    selectClientServerConnection(channelName: string): SelectedClientServer | undefined;
+    private selectClientServerConnectionCore;
+    clientServerDescriptors(channelName: string): readonly ClientServerDescriptor[];
+    admitFanoutPublisher(descriptor: FanoutPublisherDescriptor, connectionId: string): boolean;
+    removeFanoutPublisher(channelName: string, publisherRoutingId: string, connectionId: string): boolean;
+    fanoutEndpoints(channelName: string): readonly FanoutPublisherDescriptor[];
+    private admit;
+    private invalidateClientServerCandidates;
+    private clientServerCandidates;
+}