@zlink-systems/framework 0.10.0

package/src/runtime/admission.ts

@@ -0,0 +1,192 @@
+import { ZLinkFrameworkInternalErrorKind, createInternalFrameworkException  } from './framework-errors-internal';
+export class ZLinkRuntimeAdmissionGate {
+  private readonly meshes = new Map<string, ZLinkMeshAdmissionState>();
+
+  get acceptsNewWork(): boolean {
+    for (const state of this.meshes.values()) {
+      if (state.sealed) return false;
+    }
+    return true;
+  }
+
+  register(meshName: string): void {
+    if (!this.meshes.has(meshName)) {
+      this.meshes.set(meshName, {
+        sealed: false,
+        sealedReason: ZLinkFrameworkInternalErrorKind.RequestRejected,
+        active: 0,
+        waiters: [],
+        waiterHead: 0,
+        waiterCount: 0
+      });
+    }
+  }
+
+  accepts(meshName: string): boolean {
+    return !this.requireState(meshName).sealed;
+  }
+
+  pending(meshName: string): number {
+    return this.requireState(meshName).active;
+  }
+
+  seal(
+    meshName: string,
+    reason: ZLinkFrameworkInternalErrorKind = ZLinkFrameworkInternalErrorKind.RequestRejected
+  ): void {
+    const state = this.requireState(meshName);
+    state.sealed = true;
+    state.sealedReason = reason;
+  }
+
+  close(): void {
+    for (const state of this.meshes.values()) {
+      state.sealed = true;
+      state.sealedReason = ZLinkFrameworkInternalErrorKind.RuntimeShutdown;
+    }
+  }
+
+  claim(meshName: string, operation: string): ZLinkApplicationWorkClaim {
+    const state = this.requireState(meshName);
+    if (!state.sealed) {
+      state.active += 1;
+      let closed = false;
+      return {
+        close: () => {
+          if (closed) return;
+          closed = true;
+          state.active -= 1;
+          if (state.active === 0) {
+            let resolve: (() => void) | undefined;
+            while ((resolve = takeWaiter(state)) !== undefined) resolve();
+          }
+        }
+      };
+    }
+    throw createInternalFrameworkException(
+      state.sealedReason,
+      `${operation} was rejected because the framework is draining.`
+    );
+  }
+
+  async run<T>(meshName: string, operation: string, work: () => Promise<T>): Promise<T> {
+    const claim = this.claim(meshName, operation);
+    try {
+      return await work();
+    } finally {
+      claim.close();
+    }
+  }
+
+  awaitZero(meshName: string, signal?: AbortSignal): Promise<void> {
+    const state = this.requireState(meshName);
+    if (state.active === 0) return Promise.resolve();
+    if (signal?.aborted === true) return Promise.reject(signal.reason);
+    return new Promise<void>((resolve, reject) => {
+      const complete = () => {
+        signal?.removeEventListener('abort', abort);
+        resolve();
+      };
+      const abort = () => {
+        const index = state.waiters.indexOf(complete, state.waiterHead);
+        if (index >= 0) {
+          state.waiters[index] = undefined;
+          state.waiterCount -= 1;
+          advanceWaiterHead(state);
+          compactWaiters(state);
+        }
+        reject(signal?.reason);
+      };
+        state.waiters.push(complete);
+        state.waiterCount += 1;
+      signal?.addEventListener('abort', abort, { once: true });
+    });
+  }
+
+  requireRequest(operation: string, meshName?: string): void {
+    if (meshName === undefined) {
+      if (this.acceptsNewWork) return;
+    } else if (this.accepts(meshName)) {
+      return;
+    }
+    throw createInternalFrameworkException(
+      meshName === undefined
+        ? this.firstSealedReason()
+        : this.requireState(meshName).sealedReason,
+      `${operation} was rejected because the framework is draining.`
+    );
+  }
+
+  requireActorCreate(actorId: string, meshName?: string): void {
+    if (meshName === undefined) {
+      if (this.acceptsNewWork) return;
+    } else if (this.accepts(meshName)) {
+      return;
+    }
+    const reason = meshName === undefined
+      ? this.firstSealedReason()
+      : this.requireState(meshName).sealedReason;
+    throw createInternalFrameworkException(
+      reason === ZLinkFrameworkInternalErrorKind.RuntimeShutdown
+        ? ZLinkFrameworkInternalErrorKind.RuntimeShutdown
+        : ZLinkFrameworkInternalErrorKind.ActorCreateRejected,
+      `Actor '${actorId}' create request was rejected because the framework is draining.`
+    );
+  }
+
+  private requireState(meshName: string): ZLinkMeshAdmissionState {
+    const state = this.meshes.get(meshName);
+    if (state !== undefined) return state;
+    throw createInternalFrameworkException(
+      ZLinkFrameworkInternalErrorKind.RouteNotConnected,
+      `RouteMesh '${meshName}' is not registered.`
+    );
+  }
+
+  private firstSealedReason(): ZLinkFrameworkInternalErrorKind {
+    for (const state of this.meshes.values()) {
+      if (state.sealed) return state.sealedReason;
+    }
+    return ZLinkFrameworkInternalErrorKind.RuntimeShutdown;
+  }
+}
+
+export interface ZLinkApplicationWorkClaim {
+  close(): void;
+}
+
+interface ZLinkMeshAdmissionState {
+  sealed: boolean;
+  sealedReason: ZLinkFrameworkInternalErrorKind;
+  active: number;
+  readonly waiters: Array<(() => void) | undefined>;
+  waiterHead: number;
+  waiterCount: number;
+}
+
+function takeWaiter(state: ZLinkMeshAdmissionState): (() => void) | undefined {
+  advanceWaiterHead(state);
+  const waiter = state.waiters[state.waiterHead];
+  if (waiter === undefined) return undefined;
+  state.waiters[state.waiterHead] = undefined;
+  state.waiterHead += 1;
+  state.waiterCount -= 1;
+  compactWaiters(state);
+  return waiter;
+}
+
+function advanceWaiterHead(state: ZLinkMeshAdmissionState): void {
+  while (state.waiterHead < state.waiters.length && state.waiters[state.waiterHead] === undefined) {
+    state.waiterHead += 1;
+  }
+}
+
+function compactWaiters(state: ZLinkMeshAdmissionState): void {
+  if (state.waiterCount === 0) {
+    state.waiters.length = 0;
+    state.waiterHead = 0;
+  } else if (state.waiterHead >= 1024 && state.waiterHead * 2 >= state.waiters.length) {
+    state.waiters.splice(0, state.waiterHead);
+    state.waiterHead = 0;
+  }
+}

package/src/runtime/application-jobs/application-ingress-record-owner.ts

@@ -0,0 +1,216 @@
+import type {
+  ApplicationJobPermitPort,
+  ApplicationJobQueuePort
+} from './contracts';
+
+export type ApplicationJobRecordDomain = 'application' | 'infrastructure';
+
+export interface IngressRecordPort {
+  close(): void;
+}
+
+/**
+ * Owns one raw ingress record from pre-receive reservation through every
+ * derived mailbox job. Child jobs have independent queue permits while the
+ * ordinary Framework-owned ingress record closes after the last child terminal.
+ */
+export class ApplicationIngressRecordOwner {
+  private readonly stop = new AbortController();
+  private closed = false;
+
+  private constructor(private readonly shared: SharedIngressRecordState) {}
+
+  static create(
+    queue: ApplicationJobQueuePort,
+    initialPermit: ApplicationJobPermitPort,
+    record: IngressRecordPort
+  ): ApplicationIngressRecordOwner {
+    return new ApplicationIngressRecordOwner(
+      new SharedIngressRecordState(queue, initialPermit, record)
+    );
+  }
+
+  retain(): ApplicationIngressRecordOwner {
+    this.requireOpen();
+    this.shared.retainOwner();
+    return new ApplicationIngressRecordOwner(this.shared);
+  }
+
+  takeInitial(domain: ApplicationJobRecordDomain): ApplicationJobRecordLease {
+    this.requireOpen();
+    const job = this.shared.takeInitialPermit(domain);
+    if (job === undefined) {
+      throw new Error('Application ingress record initial permit was already transferred.');
+    }
+    return job;
+  }
+
+  async acquire(
+    domain: ApplicationJobRecordDomain,
+    signal?: AbortSignal
+  ): Promise<ApplicationJobRecordLease> {
+    this.requireOpen();
+    const initial = this.shared.takeInitialPermit(domain);
+    if (initial !== undefined) return initial;
+
+    const waitSignal = signal === undefined
+      ? this.stop.signal
+      : AbortSignal.any([this.stop.signal, signal]);
+    const permit = await this.shared.acquirePermit(waitSignal);
+    if (this.closed) {
+      permit.releaseAfterInternalProcessing();
+      throw ownerClosedError();
+    }
+    return this.shared.createJob(permit, domain);
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.stop.abort(ownerClosedError());
+    this.shared.releaseOwner();
+  }
+
+  private requireOpen(): void {
+    if (this.closed) throw ownerClosedError();
+  }
+}
+
+/** Queue-permit child of one shared raw ingress record. */
+export class ApplicationJobRecordLease implements ApplicationJobPermitPort {
+  private ingressClosed = false;
+  private permitReleased = false;
+  private processingTerminal = false;
+  private detachedForHandlerTurn = false;
+  private jobReleased = false;
+
+  constructor(
+    private readonly shared: SharedIngressRecordState,
+    private readonly permit: ApplicationJobPermitPort
+  ) {}
+
+  markApplicationQueued(): void {
+    // The owner classifies and marks the child atomically when it is created;
+    // downstream dispatch must not mutate queue accounting a second time.
+  }
+
+  detachForHandlerTurn(): void {
+    this.detachedForHandlerTurn = true;
+  }
+
+  releaseBeforeHandler(): void {
+    this.releasePermit(() => this.permit.releaseBeforeHandler());
+  }
+
+  releaseAfterInternalProcessing(): void {
+    this.processingTerminal = true;
+    this.releasePermit(() => this.permit.releaseAfterInternalProcessing());
+    this.releaseJobIfTerminal();
+  }
+
+  close(): void {
+    if (this.ingressClosed) return;
+    this.ingressClosed = true;
+    if (!this.detachedForHandlerTurn) {
+      this.releaseAfterInternalProcessing();
+      return;
+    }
+    this.releaseJobIfTerminal();
+  }
+
+  private releasePermit(release: () => void): void {
+    if (this.permitReleased) return;
+    this.permitReleased = true;
+    release();
+  }
+
+  private releaseJobIfTerminal(): void {
+    if (
+      this.jobReleased
+      || !this.ingressClosed
+      || !this.processingTerminal
+    ) return;
+    this.jobReleased = true;
+    this.shared.releaseJob();
+  }
+}
+
+class SharedIngressRecordState {
+  private ownerCount = 1;
+  private jobCount = 0;
+  private initialPermit?: ApplicationJobPermitPort;
+  private recordClosed = false;
+
+  constructor(
+    private readonly queue: ApplicationJobQueuePort,
+    initialPermit: ApplicationJobPermitPort,
+    private readonly record: IngressRecordPort
+  ) {
+    this.initialPermit = initialPermit;
+  }
+
+  retainOwner(): void {
+    if (this.recordClosed) throw ownerClosedError();
+    this.ownerCount += 1;
+  }
+
+  releaseOwner(): void {
+    if (this.ownerCount === 0) return;
+    this.ownerCount -= 1;
+    this.tryCloseIngressRecord();
+  }
+
+  takeInitialPermit(
+    domain: ApplicationJobRecordDomain
+  ): ApplicationJobRecordLease | undefined {
+    const permit = this.initialPermit;
+    if (permit === undefined) return undefined;
+    this.initialPermit = undefined;
+    return this.createJob(permit, domain);
+  }
+
+  acquirePermit(signal: AbortSignal): Promise<ApplicationJobPermitPort> {
+    return this.queue.acquire(signal);
+  }
+
+  createJob(
+    permit: ApplicationJobPermitPort,
+    domain: ApplicationJobRecordDomain
+  ): ApplicationJobRecordLease {
+    this.jobCount += 1;
+    try {
+      if (domain === 'application') permit.markApplicationQueued();
+      return new ApplicationJobRecordLease(this, permit);
+    } catch (error) {
+      this.jobCount -= 1;
+      permit.releaseAfterInternalProcessing();
+      this.tryCloseIngressRecord();
+      throw error;
+    }
+  }
+
+  releaseJob(): void {
+    if (this.jobCount === 0) {
+      throw new Error('Application ingress record job accounting underflow.');
+    }
+    this.jobCount -= 1;
+    this.tryCloseIngressRecord();
+  }
+
+  private tryCloseIngressRecord(): void {
+    if (this.ownerCount !== 0 || this.jobCount !== 0 || this.recordClosed) return;
+    this.recordClosed = true;
+    try {
+      this.initialPermit?.releaseAfterInternalProcessing();
+    } finally {
+      this.initialPermit = undefined;
+      this.record.close();
+    }
+  }
+}
+
+function ownerClosedError(): Error {
+  const error = new Error('Application ingress record owner is closed.');
+  error.name = 'AbortError';
+  return error;
+}

package/src/runtime/application-jobs/application-job-queue-handler-start-gate.ts

@@ -0,0 +1,10 @@
+/**
+ * Internal E2E seam for holding one acquired application-job permit until the
+ * handler turn completes. Production hosts do not register this provider.
+ */
+export const ZLINK_INTERNAL_APPLICATION_JOB_QUEUE_HANDLER_START_GATE =
+  Symbol.for('zlink.internal.application-job-queue-handler-start-gate');
+
+export interface ZLinkInternalApplicationJobQueueHandlerStartGate {
+  shouldHoldPermitBeforeHandler(): boolean;
+}

package/src/runtime/application-jobs/application-job-queue-scope.ts

@@ -0,0 +1,64 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+import type { ApplicationJobPermitPort } from './contracts';
+
+interface ApplicationJobPermitScope {
+  readonly permit: ApplicationJobPermitPort;
+  detached: boolean;
+}
+
+const applicationJobPermitScope = new AsyncLocalStorage<ApplicationJobPermitScope>();
+
+/**
+ * Carries the host-owned queue permit through internal async dispatch without
+ * leaking capacity ownership into public handler contracts.
+ */
+export async function runWithApplicationJobPermit<TResult>(
+  permit: ApplicationJobPermitPort,
+  callback: () => Promise<TResult> | TResult
+): Promise<TResult> {
+  const scope: ApplicationJobPermitScope = { permit, detached: false };
+  return applicationJobPermitScope.run(scope, async () => {
+    try {
+      return await callback();
+    } finally {
+      if (!scope.detached) permit.releaseAfterInternalProcessing();
+    }
+  });
+}
+
+/** Releases the current job permit immediately before the first user callback. */
+export function releaseApplicationJobPermitBeforeHandler(): void {
+  applicationJobPermitScope.getStore()?.permit.releaseBeforeHandler();
+}
+
+/** @internal Returns an ingress permit after a durable queue takes record ownership. */
+export function releaseApplicationJobPermitForDurableHandoff(): void {
+  applicationJobPermitScope.getStore()?.permit.releaseAfterInternalProcessing();
+}
+
+/** True while dispatch already owns the host-wide application job permit. */
+export function hasApplicationJobPermit(): boolean {
+  return applicationJobPermitScope.getStore() !== undefined;
+}
+
+/** Re-enters the captured permit scope when a serial executor runs later. */
+export function bindApplicationJobPermit<TResult>(
+  callback: () => Promise<TResult> | TResult
+): () => Promise<TResult> | TResult {
+  const scope = applicationJobPermitScope.getStore();
+  if (scope === undefined) return callback;
+  return () => applicationJobPermitScope.run(scope, callback);
+}
+
+/**
+ * Transfers the current permit to a detached internal handler turn. The
+ * detached owner must release it at handler entry or at a pre-start terminal.
+ */
+export function detachApplicationJobPermit(): ApplicationJobPermitPort | undefined {
+  const scope = applicationJobPermitScope.getStore();
+  if (scope === undefined) return undefined;
+  scope.permit.detachForHandlerTurn?.();
+  scope.detached = true;
+  return scope.permit;
+}

package/src/runtime/application-jobs/contracts.ts

@@ -0,0 +1,26 @@
+export interface ApplicationJobPermitPort {
+  markApplicationQueued(): void;
+  /** Transfers ingress-record cleanup to a detached exact-target handler turn. */
+  detachForHandlerTurn?(): void;
+  releaseBeforeHandler(): void;
+  releaseAfterInternalProcessing(): void;
+}
+
+export interface ApplicationJobQueuePort {
+  acquire(signal?: AbortSignal): Promise<ApplicationJobPermitPort>;
+  registerReceiveFlowTarget?(
+    identity: object,
+    applyState: (state: 'running' | 'paused') => void,
+    failureSink?: (error: unknown) => void
+  ): boolean;
+  unregisterReceiveFlowTarget?(identity: object): void;
+  pressureState?(): 'running' | 'paused';
+  pressureTransition?(): {
+    readonly state: 'running' | 'paused';
+    readonly sequence: bigint;
+  };
+  onPressureStateChange?(
+    listener: (state: 'running' | 'paused', sequence: bigint) => void
+  ): () => void;
+  recordFlowStateConfigFailure?(): void;
+}

package/src/runtime/application-jobs/receive-flow-controller.ts

@@ -0,0 +1,188 @@
+import type { ApplicationJobQueuePort } from './contracts';
+
+type ApplicationJobPressureState = 'running' | 'paused';
+
+interface ApplicationJobPressureTransition {
+  readonly state: ApplicationJobPressureState;
+  readonly sequence: bigint;
+}
+
+export interface ApplicationJobReceiveFlowTarget<TNativeState> {
+  setReceiveFlowState(state: TNativeState): void;
+}
+
+interface ReceiveFlowTargetState {
+  appliedSequence: bigint;
+  appliedState?: ApplicationJobPressureState;
+  pending?: ApplicationJobPressureTransition;
+  applying: boolean;
+}
+
+class ReceiveFlowControllerClosedError extends Error {
+  constructor() {
+    super('Application job receive-flow controller is disposed.');
+  }
+}
+
+/**
+ * Host-local owner of absolute receive-flow propagation. A target is entered
+ * in the registry before its initial snapshot is read, so a reentrant queue
+ * transition is either applied immediately or fences the older snapshot by
+ * sequence.
+ */
+export class ApplicationJobReceiveFlowController<TNativeState> {
+  private readonly targets = new Map<
+    ApplicationJobReceiveFlowTarget<TNativeState>,
+    ReceiveFlowTargetState
+  >();
+  private readonly unregisterPressureListener: () => void;
+  private latestTransition?: ApplicationJobPressureTransition;
+  private disposed = false;
+
+  constructor(
+    private readonly queue: ApplicationJobQueuePort | undefined,
+    private readonly toNativeState: (state: ApplicationJobPressureState) => TNativeState,
+    private readonly failureSink?: (error: unknown) => void
+  ) {
+    this.unregisterPressureListener = queue?.onPressureStateChange?.(
+      (state, sequence) => this.apply(state, sequence)
+    ) ?? (() => undefined);
+  }
+
+  register(target: ApplicationJobReceiveFlowTarget<TNativeState>): boolean {
+    if (this.disposed) throw new ReceiveFlowControllerClosedError();
+    if (this.queue === undefined) return false;
+
+    const targetState: ReceiveFlowTargetState = {
+      appliedSequence: -1n,
+      applying: false
+    };
+    this.targets.set(target, targetState);
+    try {
+      const current = this.currentTransition();
+      if (current === undefined) {
+        this.targets.delete(target);
+        return false;
+      }
+      this.rememberLatest(current);
+      this.enqueue(target, targetState, current, true);
+      if (!this.isActiveTarget(target, targetState)) {
+        throw new ReceiveFlowControllerClosedError();
+      }
+      return true;
+    } catch (error) {
+      this.unregister(target);
+      if (!(error instanceof ReceiveFlowControllerClosedError)) {
+        this.reportFailure(error);
+      }
+      throw error;
+    }
+  }
+
+  unregister(target: ApplicationJobReceiveFlowTarget<TNativeState>): void {
+    const targetState = this.targets.get(target);
+    if (targetState === undefined) return;
+    targetState.pending = undefined;
+    this.targets.delete(target);
+  }
+
+  apply(state: ApplicationJobPressureState, sequence: bigint): void {
+    if (this.disposed) return;
+    const transition = { state, sequence } satisfies ApplicationJobPressureTransition;
+    this.rememberLatest(transition);
+    for (const [target, targetState] of this.targets) {
+      this.enqueue(target, targetState, transition, false);
+    }
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.unregisterPressureListener();
+    for (const targetState of this.targets.values()) targetState.pending = undefined;
+    this.targets.clear();
+  }
+
+  private currentTransition(): ApplicationJobPressureTransition | undefined {
+    const snapshot = this.queue?.pressureTransition?.();
+    const fallbackState = snapshot === undefined ? this.queue?.pressureState?.() : undefined;
+    const current = snapshot ?? (fallbackState === undefined
+      ? undefined
+      : { state: fallbackState, sequence: 0n });
+    if (this.latestTransition === undefined) return current;
+    if (current === undefined || this.latestTransition.sequence > current.sequence) {
+      return this.latestTransition;
+    }
+    return current;
+  }
+
+  private rememberLatest(transition: ApplicationJobPressureTransition): void {
+    if (this.latestTransition === undefined
+        || transition.sequence > this.latestTransition.sequence) {
+      this.latestTransition = transition;
+    }
+  }
+
+  private enqueue(
+    target: ApplicationJobReceiveFlowTarget<TNativeState>,
+    targetState: ReceiveFlowTargetState,
+    transition: ApplicationJobPressureTransition,
+    throwOnFailure: boolean
+  ): void {
+    if (this.targets.get(target) !== targetState
+        || transition.sequence <= targetState.appliedSequence
+        || (targetState.pending !== undefined
+          && transition.sequence <= targetState.pending.sequence)) return;
+    targetState.pending = transition;
+    if (targetState.applying) return;
+
+    targetState.applying = true;
+    let firstFailure: unknown;
+    try {
+      while (this.targets.get(target) === targetState
+          && targetState.pending !== undefined) {
+        const next = targetState.pending;
+        targetState.pending = undefined;
+        if (next.sequence <= targetState.appliedSequence) continue;
+        try {
+          if (targetState.appliedState !== next.state) {
+            target.setReceiveFlowState(this.toNativeState(next.state));
+            targetState.appliedState = next.state;
+          }
+        } catch (error) {
+          firstFailure ??= error;
+          if (!throwOnFailure) this.reportFailure(error);
+        } finally {
+          targetState.appliedSequence = next.sequence;
+        }
+      }
+    } finally {
+      targetState.applying = false;
+    }
+    if (throwOnFailure && firstFailure !== undefined) throw firstFailure;
+  }
+
+  private reportFailure(error: unknown): void {
+    this.recordFailure();
+    try {
+      this.failureSink?.(error);
+    } catch {
+      // Diagnostics cannot alter the absolute queue pressure state.
+    }
+  }
+
+  private recordFailure(): void {
+    try {
+      this.queue?.recordFlowStateConfigFailure?.();
+    } catch {
+      // Metrics cannot alter receive-flow application or socket lifecycle.
+    }
+  }
+
+  private isActiveTarget(
+    target: ApplicationJobReceiveFlowTarget<TNativeState>,
+    targetState: ReceiveFlowTargetState
+  ): boolean {
+    return !this.disposed && this.targets.get(target) === targetState;
+  }
+}