@zlink-systems/framework 0.10.0

package/src/runtime/foundation/service-weighted-selection.ts

@@ -0,0 +1,166 @@
+export interface ServiceWeightedSelectionCandidate<T> {
+  readonly value: T;
+  readonly id: string;
+  readonly weight: number;
+}
+
+interface SelectionCycle<T> {
+  readonly kind: 'cycle';
+  readonly values: readonly T[];
+  readonly states: readonly ReadonlyMap<string, bigint>[];
+  readonly cycleStart: number;
+  cursor: number;
+}
+
+interface DirectSelection<T> {
+  readonly kind: 'direct';
+  readonly candidates: readonly WeightedCandidate<T>[];
+}
+
+interface WeightedCandidate<T> {
+  readonly value: T;
+  readonly id: string;
+  readonly weight: bigint;
+}
+
+type SelectionPlan<T> = SelectionCycle<T> | DirectSelection<T>;
+
+const MAX_CYCLE_SEARCH_STEPS = 4_096;
+const MAX_CYCLE_SEARCH_MS = 10;
+
+/** Owns cumulative smooth-weighted selection state without exposing it to topology callers. */
+export class SmoothWeightedSelection<T> {
+  private readonly current = new Map<string, bigint>();
+  private plan: SelectionPlan<T>;
+
+  constructor(
+    private readonly candidateProvider: () => readonly ServiceWeightedSelectionCandidate<T>[]
+  ) {
+    this.plan = emptyCycle();
+    this.rebuild();
+  }
+
+  rebuild(): void {
+    if (this.plan.kind === 'cycle' && this.plan.values.length > 0) {
+      replaceState(this.current, this.plan.states[this.plan.cursor]!);
+    }
+    this.plan = buildSelectionPlan(this.candidateProvider(), this.current);
+  }
+
+  select(accept: (value: T) => boolean = () => true): T | undefined {
+    if (this.plan.kind === 'direct') {
+      for (let attempts = 0; attempts < this.plan.candidates.length; attempts += 1) {
+        const selected = selectDirect(this.plan.candidates, this.current);
+        if (selected !== undefined && accept(selected)) return selected;
+      }
+      return undefined;
+    }
+    if (this.plan.values.length === 0) return undefined;
+    for (let attempts = 0; attempts < this.plan.values.length; attempts += 1) {
+      const cursor = this.plan.cursor;
+      const selected = this.plan.values[cursor]!;
+      const nextCursor = cursor + 1 < this.plan.values.length
+        ? cursor + 1
+        : this.plan.cycleStart;
+      this.plan.cursor = nextCursor;
+      if (accept(selected)) return selected;
+    }
+    return undefined;
+  }
+}
+
+function buildSelectionPlan<T>(
+  eligible: readonly ServiceWeightedSelectionCandidate<T>[],
+  current: Map<string, bigint>
+): SelectionPlan<T> {
+  const candidates: readonly WeightedCandidate<T>[] = eligible.map(candidate => ({
+    ...candidate,
+    weight: BigInt(candidate.weight)
+  }));
+  const total = candidates.reduce((sum, candidate) => sum + candidate.weight, 0n);
+  replaceState(
+    current,
+    new Map(candidates.map(candidate => [
+      candidate.id,
+      current.get(candidate.id) ?? 0n
+    ]))
+  );
+  if (total === 0n) return emptyCycle();
+
+  const values: T[] = [];
+  const states: ReadonlyMap<string, bigint>[] = [];
+  const seen = new Map<string, number>();
+  const working = new Map(current);
+  const startedAt = performance.now();
+  for (;;) {
+    if (values.length >= MAX_CYCLE_SEARCH_STEPS
+      || performance.now() - startedAt >= MAX_CYCLE_SEARCH_MS) {
+      return { kind: 'direct', candidates };
+    }
+    const stateKey = candidates
+      .map(candidate => `${candidate.id}\u0000${working.get(candidate.id) ?? 0n}`)
+      .join('\u0001');
+    const cycleStart = seen.get(stateKey);
+    if (cycleStart !== undefined) {
+      return {
+        kind: 'cycle',
+        values: Object.freeze(values),
+        states: Object.freeze(states),
+        cycleStart,
+        cursor: 0
+      };
+    }
+    seen.set(stateKey, values.length);
+    states.push(new Map(working));
+    let selected = candidates[0]!;
+    let selectedCurrent = working.get(selected.id)! + selected.weight;
+    for (const candidate of candidates) {
+      const next = working.get(candidate.id)! + candidate.weight;
+      working.set(candidate.id, next);
+      if (next > selectedCurrent) {
+        selected = candidate;
+        selectedCurrent = next;
+      }
+    }
+    working.set(selected.id, working.get(selected.id)! - total);
+    values.push(selected.value);
+  }
+}
+
+function emptyCycle<T>(): SelectionCycle<T> {
+  return {
+    kind: 'cycle',
+    values: Object.freeze([]),
+    states: Object.freeze([]),
+    cycleStart: 0,
+    cursor: 0
+  };
+}
+
+function selectDirect<T>(
+  candidates: readonly WeightedCandidate<T>[],
+  current: Map<string, bigint>
+): T | undefined {
+  if (candidates.length === 0) return undefined;
+  const total = candidates.reduce((sum, candidate) => sum + candidate.weight, 0n);
+  let selected = candidates[0]!;
+  let selectedCurrent = current.get(selected.id)! + selected.weight;
+  for (const candidate of candidates) {
+    const next = current.get(candidate.id)! + candidate.weight;
+    current.set(candidate.id, next);
+    if (next > selectedCurrent) {
+      selected = candidate;
+      selectedCurrent = next;
+    }
+  }
+  current.set(selected.id, current.get(selected.id)! - total);
+  return selected.value;
+}
+
+function replaceState(
+  target: Map<string, bigint>,
+  source: ReadonlyMap<string, bigint>
+): void {
+  target.clear();
+  for (const [key, value] of source) target.set(key, value);
+}

package/src/runtime/foundation/service-wire-binary-primitives.ts

@@ -0,0 +1,80 @@
+import type { RoutingId } from '../../contracts';
+import {
+  decodeRoutingId,
+  encodeRoutingIdStorageHex
+} from '../routing-id';
+
+export type ServiceWireInvalid = (message: string) => never;
+
+/** Encodes text without silently replacing an unpaired UTF-16 surrogate. */
+export function encodeCanonicalServiceWireText(
+  value: string,
+  field: string,
+  maximumBytes: number,
+  invalid: ServiceWireInvalid
+): Buffer {
+  const bytes = Buffer.from(value, 'utf8');
+  if (
+    bytes.byteLength < 1
+    || bytes.byteLength > maximumBytes
+    || value.includes('\0')
+    || bytes.toString('utf8') !== value
+  ) {
+    invalid(`${field} must be 1..${maximumBytes} canonical UTF-8 bytes without NUL.`);
+  }
+  return bytes;
+}
+
+/** Decodes schema text and rejects Node's replacement-character fallback. */
+export function decodeCanonicalServiceWireText(
+  bytes: Uint8Array,
+  field: string,
+  invalid: ServiceWireInvalid
+): string {
+  const encoded = Buffer.from(bytes);
+  const value = encoded.toString('utf8');
+  if (
+    value.includes('\0')
+    || !Buffer.from(value, 'utf8').equals(encoded)
+  ) {
+    invalid(`${field} is not canonical UTF-8 without NUL.`);
+  }
+  return value;
+}
+
+/** Preserves the schema's binary-safe RoutingId bytes. */
+export function encodeServiceWireRoutingId(
+  value: RoutingId,
+  field: string,
+  maximumBytes: number,
+  invalid: ServiceWireInvalid
+): Buffer {
+  let bytes: Buffer;
+  try {
+    bytes = Buffer.from(encodeRoutingIdStorageHex(value), 'hex');
+  } catch (error) {
+    invalid(`${field} is not a valid RoutingId: ${errorMessage(error)}`);
+  }
+  if (bytes.byteLength < 1 || bytes.byteLength > maximumBytes) {
+    invalid(`${field} must be 1..${maximumBytes} opaque bytes.`);
+  }
+  return bytes;
+}
+
+/** Returns printable UTF-8 as a string and otherwise retains an opaque byte identity. */
+export function decodeServiceWireRoutingId(
+  bytes: Uint8Array,
+  field: string,
+  maximumBytes: number,
+  invalid: ServiceWireInvalid
+): RoutingId {
+  const encoded = Buffer.from(bytes);
+  if (encoded.byteLength < 1 || encoded.byteLength > maximumBytes) {
+    invalid(`${field} must be 1..${maximumBytes} opaque bytes.`);
+  }
+  return decodeRoutingId(encoded.toString('utf8'), encoded.toString('hex'));
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/runtime/foundation/service-wire-codec.ts

@@ -0,0 +1,91 @@
+const PREFIX_SIZE = 5;
+const LIVENESS_FRAME_SIZE = PREFIX_SIZE + 8;
+
+export interface ServiceWireDefinition {
+  readonly magic: readonly [number, number];
+  readonly major: number;
+  readonly commands: Readonly<Record<string, number>> & {
+    readonly livenessProbe: number;
+    readonly livenessAck: number;
+  };
+}
+
+export type ServiceWireDecodeErrorCode =
+  | 'truncated-field'
+  | 'invalid-magic'
+  | 'unsupported-major'
+  | 'unknown-command'
+  | 'forbidden-flag'
+  | 'invalid-field'
+  | 'trailing-byte';
+
+export class ServiceWireDecodeError extends Error {
+  constructor(readonly code: ServiceWireDecodeErrorCode) {
+    super(`Service wire decode failed: ${code}.`);
+    this.name = 'ServiceWireDecodeError';
+  }
+}
+
+export interface ServiceWireLivenessRecord {
+  readonly command: number;
+  readonly probeId: bigint;
+}
+
+export interface ServiceWireCodec {
+  encodeLivenessRecord(record: ServiceWireLivenessRecord): Buffer;
+  decodeLivenessRecord(frame: Uint8Array): ServiceWireLivenessRecord;
+}
+
+export function createServiceWireCodec(definition: ServiceWireDefinition): ServiceWireCodec {
+  const knownCommands = new Set<number>(Object.values(definition.commands));
+  return {
+    encodeLivenessRecord(record) {
+      if (
+        record.command !== definition.commands.livenessProbe &&
+        record.command !== definition.commands.livenessAck
+      ) {
+        throw new RangeError('command must be a liveness command.');
+      }
+      if (record.probeId <= 0n || record.probeId > 0xffff_ffff_ffff_ffffn) {
+        throw new RangeError('probeId must be a non-zero unsigned 64-bit integer.');
+      }
+
+      const frame = Buffer.allocUnsafe(LIVENESS_FRAME_SIZE);
+      frame[0] = definition.magic[0];
+      frame[1] = definition.magic[1];
+      frame[2] = definition.major;
+      frame[3] = record.command;
+      frame[4] = 0;
+      frame.writeBigUInt64BE(record.probeId, PREFIX_SIZE);
+      return frame;
+    },
+    decodeLivenessRecord(frame) {
+      if (frame.byteLength < PREFIX_SIZE) fail('truncated-field');
+      if (frame[0] !== definition.magic[0] || frame[1] !== definition.magic[1]) {
+        fail('invalid-magic');
+      }
+      if (frame[2] !== definition.major) fail('unsupported-major');
+
+      const command = frame[3];
+      if (!knownCommands.has(command)) fail('unknown-command');
+      if (
+        command !== definition.commands.livenessProbe &&
+        command !== definition.commands.livenessAck
+      ) {
+        fail('unknown-command');
+      }
+      if (frame[4] !== 0) fail('forbidden-flag');
+      if (frame.byteLength < LIVENESS_FRAME_SIZE) fail('truncated-field');
+      if (frame.byteLength > LIVENESS_FRAME_SIZE) fail('trailing-byte');
+
+      const view = Buffer.from(frame.buffer, frame.byteOffset, frame.byteLength);
+      const probeId = view.readBigUInt64BE(PREFIX_SIZE);
+      if (probeId === 0n) fail('invalid-field');
+      return { command, probeId };
+    }
+  };
+}
+
+function fail(code: ServiceWireDecodeErrorCode): never {
+  throw new ServiceWireDecodeError(code);
+}

package/src/runtime/foundation/service-wire-constants.generated.ts

@@ -0,0 +1,131 @@
+// Generated from service-wire-v1.schema.json. Do not edit.
+export const SERVICE_WIRE_MAGIC = [90, 77] as const;
+export const SERVICE_WIRE_MAJOR = 1 as const;
+export const SERVICE_WIRE_REQUIRED_CAPABILITY = "framework-service-v13" as const;
+export const SERVICE_FRAMEWORK_MULTIPART_PACKET_NAME = "ZLinkFrameworkMultipart" as const;
+export const SERVICE_FRAMEWORK_MULTIPART_CONTENT_TYPE = "application/x-zlink-multipart" as const;
+export const ServiceWireCommand = {
+  hello: 1,
+  admit: 2,
+  reject: 3,
+  update: 4,
+  livenessProbe: 5,
+  livenessAck: 6,
+  nodeSend: 16,
+  nodeRequest: 17,
+  channelSend: 18,
+  channelRequest: 19,
+  reply: 20,
+  spotSend: 21,
+  spotRequest: 22,
+  logicalMulticast: 23,
+  actorSend: 24,
+  actorRequest: 25,
+  actorLookup: 26,
+  actorDestroy: 27,
+  actorJoin: 28,
+  actorLeft: 29,
+  relocationReady: 30,
+  relocationData: 31,
+  replyRelay: 33,
+  relocationCutover: 34,
+  boundSessionSend: 36,
+  actorJoined: 37,
+  boundSessionBind: 38,
+  instanceSpot: 39,
+  relocationPrepare: 40,
+  sessionRelocationSeal: 42,
+  sessionRelocationSealed: 43,
+  sessionRelocationRoute: 44,
+  replyRelayAck: 46,
+  userSpotCreate: 47,
+  userSpotClose: 48,
+  actorCreate: 49,
+  messageFollow: 50,
+  boundSessionReplaced: 51,
+  relocationState: 52,
+  relocationFailed: 53,
+} as const;
+export const ServiceWireFlag = {
+  metadata: 1,
+  boundSession: 2,
+  sourceSpotId: 4,
+  extension: 8,
+} as const;
+export const ServiceWireFrameworkErrorCode = {
+  none: 0,
+  actorRouteNotFound: 1,
+  actorCreateFailed: 2,
+  actorAlreadyExists: 3,
+  actorTypeMismatch: 4,
+  spotCreateFailed: 5,
+  spotRouteNotFound: 6,
+  spotTypeMismatch: 7,
+  actorSessionNotBound: 8,
+  handlerNotFound: 9,
+  routeHandlerNotFound: 10,
+  actorDispatchHandlerNotFound: 11,
+  payloadDecodeFailed: 12,
+  routeNotConnected: 13,
+  requestTargetNotFound: 14,
+  requestRejected: 15,
+  requestProtocolError: 16,
+  requestFailed: 17,
+  workerQueueFull: 18,
+  workerTimedOut: 19,
+  workerFailed: 20,
+  actorLocationStale: 21,
+  actorCreateRejected: 22,
+  spotGenerationStale: 33,
+  spotMoving: 34,
+  relocationDataLost: 35,
+} as const;
+export const ServiceWireBoundaryTerminalResults = [101, 103, 108, 109, 110, 111, 112, 113] as const;
+export const ServiceWireExactTerminalByFailureCode = {
+  1: 102, // actorRouteNotFound
+  2: 105, // actorCreateFailed
+  3: 107, // actorAlreadyExists
+  4: 107, // actorTypeMismatch
+  5: 105, // spotCreateFailed
+  6: 102, // spotRouteNotFound
+  7: 107, // spotTypeMismatch
+  8: 102, // actorSessionNotBound
+  9: 102, // handlerNotFound
+  10: 102, // routeHandlerNotFound
+  11: 102, // actorDispatchHandlerNotFound
+  12: 104, // payloadDecodeFailed
+  13: 105, // routeNotConnected
+  14: 102, // requestTargetNotFound
+  15: 106, // requestRejected
+  16: 104, // requestProtocolError
+  17: 105, // requestFailed
+  18: 106, // workerQueueFull
+  19: 105, // workerTimedOut
+  20: 105, // workerFailed
+  21: 107, // actorLocationStale
+  22: 106, // actorCreateRejected
+  33: 107, // spotGenerationStale
+  34: 107, // spotMoving
+  35: 105, // relocationDataLost
+} as const;
+// Schema terminal-failure-integrity: success is ok+none, boundary terminals
+// carry none, typed failures must match their exact terminal, and an unknown
+// failure code is a protocol error before dispatch.
+export const isValidServiceWireTerminalFailure = (
+  terminal: number,
+  failureCode: number
+): boolean => {
+  if (terminal === 0) {
+    return failureCode === 0;
+  }
+  if ((ServiceWireBoundaryTerminalResults as readonly number[]).includes(terminal)) {
+    return failureCode === 0;
+  }
+  if (failureCode === 0) {
+    return false;
+  }
+  if (!Object.hasOwn(ServiceWireExactTerminalByFailureCode, failureCode)) {
+    return false;
+  }
+  return ServiceWireExactTerminalByFailureCode[failureCode as keyof typeof ServiceWireExactTerminalByFailureCode] === terminal;
+};