@hunterzhu/pulse-runtime 0.1.0

package/dist/scheduler/clock.js

@@ -0,0 +1,92 @@
+import { performance } from 'node:perf_hooks';
+export class TimerWheel {
+    entries = new Map();
+    selected = new Map();
+    seq = 0;
+    schedule(at, callback) { const id = `timer-${++this.seq}`; this.entries.set(id, { id, at, callback, cancelled: false }); return id; }
+    cancel(id) { const entry = this.entries.get(id) ?? this.selected.get(id); if (entry)
+        entry.cancelled = true; }
+    due(now, limit = Number.POSITIVE_INFINITY) {
+        const due = [...this.entries.values()].filter((entry) => !entry.cancelled && entry.at <= now).sort((a, b) => a.at - b.at || a.id.localeCompare(b.id)).slice(0, limit);
+        return due.map((entry) => {
+            this.entries.delete(entry.id);
+            this.selected.set(entry.id, entry);
+            let completed = false;
+            return {
+                ...entry,
+                callback: () => {
+                    if (completed)
+                        return;
+                    if (entry.cancelled) {
+                        completed = true;
+                        this.selected.delete(entry.id);
+                        return;
+                    }
+                    try {
+                        entry.callback();
+                        completed = true;
+                        this.selected.delete(entry.id);
+                    }
+                    catch (cause) {
+                        this.selected.delete(entry.id);
+                        if (!entry.cancelled)
+                            this.entries.set(entry.id, entry);
+                        throw cause;
+                    }
+                },
+            };
+        });
+    }
+    nextAt() { return [...this.entries.values()].filter((entry) => !entry.cancelled).sort((a, b) => a.at - b.at)[0]?.at; }
+    get size() { return [...this.entries.values()].filter((entry) => !entry.cancelled).length; }
+}
+export class VirtualClock {
+    timers = new TimerWheel();
+    current = 0;
+    now() { return this.current; }
+    set(now) { if (now < this.current)
+        throw new Error('VirtualClock cannot move backwards'); this.current = now; }
+    advance(ms) { if (ms < 0)
+        throw new Error('VirtualClock cannot move backwards'); this.current += ms; }
+    schedule(delayMs, callback) { return this.timers.schedule(this.current + delayMs, callback); }
+}
+/** Monotonic host clock for production runtimes; timers never fast-forward. */
+export class MonotonicClock {
+    timers = new TimerWheel();
+    startedAt = performance.now();
+    epoch;
+    current;
+    constructor(startAt = Date.now()) {
+        if (!Number.isFinite(startAt))
+            throw new Error('INVALID_CLOCK_START');
+        this.epoch = startAt;
+        this.current = startAt;
+    }
+    now() {
+        this.current = Math.max(this.current, this.epoch + performance.now() - this.startedAt);
+        return this.current;
+    }
+    set(now) {
+        if (!Number.isFinite(now) || now < this.current)
+            return;
+        this.current = now;
+    }
+    advance(ms) {
+        if (!Number.isFinite(ms) || ms < 0)
+            throw new Error('MonotonicClock cannot move backwards');
+        this.set(this.now() + ms);
+    }
+    schedule(delayMs, callback) {
+        if (!Number.isFinite(delayMs) || delayMs < 0)
+            throw new Error('INVALID_TIMER_DELAY');
+        return this.timers.schedule(this.now() + delayMs, callback);
+    }
+    async waitUntil(at) {
+        if (!Number.isFinite(at))
+            throw new Error('INVALID_TIMER_DEADLINE');
+        while (this.now() < at) {
+            const remaining = at - this.current;
+            await new Promise((resolve) => setTimeout(resolve, Math.max(1, remaining)));
+        }
+    }
+}

package/dist/scheduler/decision.d.ts

@@ -0,0 +1,72 @@
+import type { LaneRecord } from '../core/types.js';
+export interface SchedulerDecisionCandidate {
+    laneId: string;
+    agentId: string;
+    goal?: string;
+    effectivePriority: number;
+    basePriority: number;
+    waitingMs: number;
+    inheritedFloor?: number;
+}
+export interface SchedulerDecisionRequest {
+    schemaVersion: 1;
+    decisionId: string;
+    candidateEpoch: number;
+    now: number;
+    availableSlots: number;
+    candidates: readonly SchedulerDecisionCandidate[];
+}
+export interface SchedulerDecision {
+    decisionId: string;
+    candidateEpoch: number;
+    orderedLaneIds: string[];
+    modelId: string;
+}
+/**
+ * An advisory scheduler policy. Implementations may be model-, ranker-, or
+ * rule-based. They never receive Runtime mutators and their result is only
+ * considered after it returns through the Runtime FactInbox.
+ */
+export interface SchedulerDecisionModel {
+    readonly id: string;
+    decide(request: SchedulerDecisionRequest, signal: AbortSignal): Promise<SchedulerDecision>;
+}
+export interface SchedulerDecisionConfig {
+    model?: SchedulerDecisionModel;
+    /** Minimum number of ready lanes before the advisory model is consulted. */
+    minCandidates?: number;
+    /** Maximum number of deterministic top candidates exposed to the model. */
+    candidateLimit?: number;
+    /** Maximum time an advisory request may run before deterministic fallback. */
+    decisionTimeoutMs?: number;
+    /** Number of outstanding advisory requests allowed at once. */
+    maxOutstandingDecisions?: number;
+    /** Maximum distance from deterministic order that a suggestion may move a lane. */
+    maxReorderDistance?: number;
+    /** Every Nth dispatch is deterministic, even when a model suggestion exists. */
+    deterministicReserveEvery?: number;
+    /** Goals are local data; expose them only when the host explicitly opts in. */
+    includeGoals?: boolean;
+}
+export interface SchedulerDecisionCoordinatorOptions {
+    model: SchedulerDecisionModel;
+    timeoutMs: number;
+    maxOutstanding: number;
+}
+/**
+ * Owns only the lifecycle of advisory calls. It deliberately has no Runtime
+ * reference: completion is delivered to the caller, which must enqueue a
+ * fact before touching Runtime state.
+ */
+export declare class SchedulerDecisionCoordinator {
+    private readonly model;
+    private readonly timeoutMs;
+    private readonly maxOutstanding;
+    private readonly controllers;
+    private outstanding;
+    constructor(options: SchedulerDecisionCoordinatorOptions);
+    get pending(): number;
+    request(request: SchedulerDecisionRequest, onDecision: (decision: SchedulerDecision) => void, onFailure?: () => void): boolean;
+    cancel(): void;
+}
+export declare function schedulerDecisionCandidateFromLane(lane: Readonly<LaneRecord>, effectivePriority: number, now: number, includeGoal: boolean, inheritedFloor?: number | undefined): SchedulerDecisionCandidate;

package/dist/scheduler/decision.js

@@ -0,0 +1,63 @@
+/**
+ * Owns only the lifecycle of advisory calls. It deliberately has no Runtime
+ * reference: completion is delivered to the caller, which must enqueue a
+ * fact before touching Runtime state.
+ */
+export class SchedulerDecisionCoordinator {
+    model;
+    timeoutMs;
+    maxOutstanding;
+    controllers = new Set();
+    outstanding = 0;
+    constructor(options) {
+        this.model = options.model;
+        this.timeoutMs = options.timeoutMs;
+        this.maxOutstanding = options.maxOutstanding;
+    }
+    get pending() { return this.outstanding; }
+    request(request, onDecision, onFailure = () => undefined) {
+        if (this.outstanding >= this.maxOutstanding)
+            return false;
+        const controller = new AbortController();
+        this.controllers.add(controller);
+        this.outstanding++;
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        void Promise.resolve()
+            .then(() => this.model.decide(structuredClone(request), controller.signal))
+            .then((decision) => {
+            if (!decision || typeof decision !== 'object')
+                return;
+            try {
+                onDecision(structuredClone(decision));
+            }
+            catch { /* advisory failures never escape into the Runtime turn */ }
+        }, () => {
+            try {
+                onFailure();
+            }
+            catch { /* advisory failures never escape into the Runtime turn */ }
+        })
+            .finally(() => {
+            clearTimeout(timer);
+            this.controllers.delete(controller);
+            this.outstanding--;
+        });
+        return true;
+    }
+    cancel() {
+        for (const controller of this.controllers)
+            controller.abort();
+        this.controllers.clear();
+    }
+}
+export function schedulerDecisionCandidateFromLane(lane, effectivePriority, now, includeGoal, inheritedFloor = lane.inheritedFloor) {
+    return {
+        laneId: lane.id,
+        agentId: lane.agentId,
+        ...(includeGoal ? { goal: lane.goal } : {}),
+        effectivePriority,
+        basePriority: lane.priority,
+        waitingMs: Math.max(0, now - lane.readySince),
+        ...(inheritedFloor === undefined ? {} : { inheritedFloor }),
+    };
+}

package/dist/scheduler/index.d.ts

@@ -0,0 +1,6 @@
+export * from './clock.js';
+export * from './ready-queue.js';
+export * from './locks.js';
+export * from './telemetry.js';
+export * from './worker.js';
+export * from './decision.js';

package/dist/scheduler/index.js

@@ -0,0 +1,6 @@
+export * from './clock.js';
+export * from './ready-queue.js';
+export * from './locks.js';
+export * from './telemetry.js';
+export * from './worker.js';
+export * from './decision.js';

package/dist/scheduler/locks.d.ts

@@ -0,0 +1,18 @@
+export type LockMode = 'shared' | 'exclusive';
+export declare class ResourceLockManager {
+    readonly writerPreferenceBound: number;
+    private readonly holders;
+    private readonly queues;
+    private seq;
+    constructor(writerPreferenceBound?: number);
+    acquire(resource: string, mode: LockMode, requestId?: string): Promise<() => void>;
+    tryAcquire(resource: string, mode: LockMode, requestId?: string): (() => void) | undefined;
+    wait(resource: string, mode: LockMode, requestId: string, onGrant: (release: () => void) => void): void;
+    cancelWait(resource: string, requestId: string): void;
+    restoreHeld(resource: string, mode: LockMode, requestId: string): () => void;
+    private canGrant;
+    private drain;
+    release(resource: string, requestId: string): void;
+    isHeld(resource: string, mode?: LockMode): boolean;
+    queued(resource: string): number;
+}

package/dist/scheduler/locks.js

@@ -0,0 +1,106 @@
+export class ResourceLockManager {
+    writerPreferenceBound;
+    holders = new Map();
+    queues = new Map();
+    seq = 0;
+    constructor(writerPreferenceBound = Number.POSITIVE_INFINITY) {
+        this.writerPreferenceBound = writerPreferenceBound;
+        if (writerPreferenceBound !== Number.POSITIVE_INFINITY && (!Number.isInteger(writerPreferenceBound) || writerPreferenceBound < 0))
+            throw new Error('INVALID_WRITER_PREFERENCE_BOUND');
+    }
+    acquire(resource, mode, requestId = `lock-${++this.seq}`) {
+        return new Promise((resolve, reject) => {
+            const queue = this.queues.get(resource) ?? [];
+            const request = { id: requestId, mode, seq: ++this.seq, ...(mode === 'exclusive' ? { aheadSharedIds: queue.filter((queued) => queued.mode === 'shared').map((queued) => queued.id) } : {}), resolve, reject };
+            queue.push(request);
+            this.queues.set(resource, queue);
+            this.drain(resource);
+        });
+    }
+    tryAcquire(resource, mode, requestId = `lock-${++this.seq}`) {
+        const holders = this.holders.get(resource) ?? new Map();
+        const queue = this.queues.get(resource) ?? [];
+        if (queue.length > 0)
+            return undefined;
+        if (mode === 'exclusive' && holders.size > 0)
+            return undefined;
+        if (mode === 'shared' && [...holders.values()].some((heldMode) => heldMode === 'exclusive'))
+            return undefined;
+        holders.set(requestId, mode);
+        this.holders.set(resource, holders);
+        return () => this.release(resource, requestId);
+    }
+    wait(resource, mode, requestId, onGrant) {
+        const holders = this.holders.get(resource) ?? new Map();
+        if (holders.has(requestId)) {
+            onGrant(() => this.release(resource, requestId));
+            return;
+        }
+        const queue = this.queues.get(resource) ?? [];
+        if (queue.some((request) => request.id === requestId))
+            return;
+        const request = { id: requestId, mode, seq: ++this.seq, ...(mode === 'exclusive' ? { aheadSharedIds: queue.filter((queued) => queued.mode === 'shared').map((queued) => queued.id) } : {}), resolve: onGrant, reject: () => undefined };
+        queue.push(request);
+        this.queues.set(resource, queue);
+        this.drain(resource);
+    }
+    cancelWait(resource, requestId) {
+        const queue = this.queues.get(resource);
+        if (!queue)
+            return;
+        const index = queue.findIndex((request) => request.id === requestId);
+        if (index >= 0)
+            queue.splice(index, 1);
+        if (queue.length === 0)
+            this.queues.delete(resource);
+    }
+    restoreHeld(resource, mode, requestId) {
+        if (!requestId || this.holders.get(resource)?.has(requestId))
+            throw new Error('INVALID_LOCK_RESTORE');
+        const holders = this.holders.get(resource) ?? new Map();
+        if (mode === 'exclusive' && holders.size > 0)
+            throw new Error('RESOURCE_RESTORE_CONFLICT');
+        if (mode === 'shared' && [...holders.values()].some((heldMode) => heldMode === 'exclusive'))
+            throw new Error('RESOURCE_RESTORE_CONFLICT');
+        if ((this.queues.get(resource)?.length ?? 0) > 0)
+            throw new Error('RESOURCE_RESTORE_CONFLICT');
+        holders.set(requestId, mode);
+        this.holders.set(resource, holders);
+        return () => this.release(resource, requestId);
+    }
+    canGrant(resource, request) {
+        const holders = this.holders.get(resource) ?? new Map();
+        if (request.mode === 'shared' && [...holders.values()].some((mode) => mode === 'exclusive'))
+            return false;
+        if (request.mode === 'exclusive' && holders.size)
+            return false;
+        const queue = this.queues.get(resource) ?? [];
+        const index = queue.findIndex((queued) => queued.id === request.id);
+        if (index < 0)
+            return false;
+        if (request.mode === 'exclusive')
+            return !queue.slice(0, index).some((queued) => queued.mode === 'exclusive');
+        const firstWriter = queue.find((queued) => queued.mode === 'exclusive');
+        if (firstWriter === undefined)
+            return true;
+        const sharedOrdinal = firstWriter.aheadSharedIds?.indexOf(request.id) ?? -1;
+        return sharedOrdinal >= 0 && sharedOrdinal < this.writerPreferenceBound;
+    }
+    drain(resource) {
+        const queue = this.queues.get(resource) ?? [];
+        for (const request of [...queue]) {
+            if (!this.canGrant(resource, request))
+                continue;
+            const holders = this.holders.get(resource) ?? new Map();
+            holders.set(request.id, request.mode);
+            this.holders.set(resource, holders);
+            queue.splice(queue.findIndex((item) => item.id === request.id), 1);
+            request.resolve(() => this.release(resource, request.id));
+            if (request.mode === 'exclusive')
+                break;
+        }
+    }
+    release(resource, requestId) { this.holders.get(resource)?.delete(requestId); this.drain(resource); }
+    isHeld(resource, mode) { const values = [...(this.holders.get(resource)?.values() ?? [])]; return mode ? values.includes(mode) : values.length > 0; }
+    queued(resource) { return this.queues.get(resource)?.length ?? 0; }
+}

package/dist/scheduler/ready-queue.d.ts

@@ -0,0 +1,32 @@
+import type { LaneRecord } from '../core/types.js';
+export interface ReadyItem {
+    laneId: string;
+    basePriority: number;
+    readySince: number;
+    enqueueSeq: number;
+    inheritedFloor?: number;
+}
+export declare class ReadyQueue {
+    private readonly agingIntervalMs;
+    private readonly agingCap;
+    private readonly items;
+    constructor(agingIntervalMs?: number, agingCap?: number);
+    enqueue(item: ReadyItem): void;
+    remove(laneId: string): void;
+    get size(): number;
+    has(laneId: string): boolean;
+    score(item: ReadyItem, now: number): number;
+    dequeue(now: number): string | undefined;
+    dequeueSpecific(laneId: string): string | undefined;
+    snapshot(now: number): Array<ReadyItem & {
+        effectivePriority: number;
+    }>;
+}
+export declare class PriorityInheritance {
+    private readonly floors;
+    clear(): void;
+    raise(targetLaneId: string, consumerId: string, score: number): void;
+    release(targetLaneId: string, consumerId: string): void;
+    floor(targetLaneId: string): number | undefined;
+}
+export declare function readyItemFromLane(lane: LaneRecord, inheritedFloor?: number | undefined): ReadyItem;

package/dist/scheduler/ready-queue.js

@@ -0,0 +1,40 @@
+export class ReadyQueue {
+    agingIntervalMs;
+    agingCap;
+    items = new Map();
+    constructor(agingIntervalMs = 1000, agingCap = Number.POSITIVE_INFINITY) {
+        this.agingIntervalMs = agingIntervalMs;
+        this.agingCap = agingCap;
+    }
+    enqueue(item) { this.items.set(item.laneId, item); }
+    remove(laneId) { this.items.delete(laneId); }
+    get size() { return this.items.size; }
+    has(laneId) { return this.items.has(laneId); }
+    score(item, now) {
+        const aging = Math.min(this.agingCap, Math.floor(Math.max(0, now - item.readySince) / this.agingIntervalMs));
+        return Math.max(item.basePriority + aging, item.inheritedFloor ?? Number.NEGATIVE_INFINITY);
+    }
+    dequeue(now) {
+        const best = [...this.items.values()].sort((a, b) => this.score(b, now) - this.score(a, now) || a.enqueueSeq - b.enqueueSeq)[0];
+        if (!best)
+            return undefined;
+        this.items.delete(best.laneId);
+        return best.laneId;
+    }
+    dequeueSpecific(laneId) {
+        if (!this.items.has(laneId))
+            return undefined;
+        this.items.delete(laneId);
+        return laneId;
+    }
+    snapshot(now) { return [...this.items.values()].map((item) => ({ ...item, effectivePriority: this.score(item, now) })).sort((a, b) => b.effectivePriority - a.effectivePriority || a.enqueueSeq - b.enqueueSeq); }
+}
+export class PriorityInheritance {
+    floors = new Map();
+    clear() { this.floors.clear(); }
+    raise(targetLaneId, consumerId, score) { if (!this.floors.has(targetLaneId))
+        this.floors.set(targetLaneId, new Map()); this.floors.get(targetLaneId).set(consumerId, score); }
+    release(targetLaneId, consumerId) { this.floors.get(targetLaneId)?.delete(consumerId); }
+    floor(targetLaneId) { const values = [...(this.floors.get(targetLaneId)?.values() ?? [])]; return values.length ? Math.max(...values) : undefined; }
+}
+export function readyItemFromLane(lane, inheritedFloor = lane.inheritedFloor) { return { laneId: lane.id, basePriority: lane.priority, readySince: lane.readySince, enqueueSeq: lane.enqueueSeq, ...(inheritedFloor === undefined ? {} : { inheritedFloor }) }; }