@itookit/dsht 0.5.1 → 0.5.2

package/dist/controller/foreground.d.ts

@@ -0,0 +1,44 @@
+import type { ForegroundKind, ForegroundSnapshot } from '../contracts.ts';
+type ForegroundEvent = {
+    phase: 'queued';
+    kind: ForegroundKind;
+    label: string;
+} | {
+    phase: 'begin';
+    id: number;
+    kind: ForegroundKind;
+    label: string;
+} | {
+    phase: 'end';
+    id: number;
+    kind: ForegroundKind;
+    cancelled: boolean;
+};
+/** Owns scheduling only; the application publishes state and reports action failures. */
+export declare class ForegroundSlot {
+    private readonly listener;
+    private current?;
+    private readonly owner;
+    private readonly waiters;
+    private granted;
+    private closed;
+    private sequence;
+    constructor(listener: {
+        changed(started: boolean): void;
+        trace(event: ForegroundEvent): void;
+    });
+    /** Only display data crosses the UI boundary; the abort controller stays private. */
+    get snapshot(): ForegroundSnapshot | undefined;
+    /** An inherited async context is an owner only while that exact operation is active. */
+    private ownsCurrent;
+    /** Nested work shares its owner's signal. Other callers are refused or wait in arrival order.
+     * Cancellation is cooperative: admitted work keeps its result/error, and no new nested work starts
+     * after cancellation. The slot stays occupied until the admitted work settles.
+     */
+    run<T>(kind: ForegroundKind, label: string, work: (signal: AbortSignal) => Promise<T>, wait?: boolean): Promise<T | undefined>;
+    /** Abort cooperatively, keeping the slot until work has settled. */
+    cancel(): boolean;
+    /** Permanently refuse new claims, abort the occupant and release all waiting callers. */
+    close(): void;
+}
+export {};

package/dist/controller/foreground.js

@@ -0,0 +1,79 @@
+/** Admission and cancellation for the application's single foreground operation. */
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** Owns scheduling only; the application publishes state and reports action failures. */
+export class ForegroundSlot {
+    listener;
+    current;
+    owner = new AsyncLocalStorage();
+    waiters = [];
+    granted = false;
+    closed = false;
+    sequence = 0;
+    constructor(listener) {
+        this.listener = listener;
+    }
+    /** Only display data crosses the UI boundary; the abort controller stays private. */
+    get snapshot() { return this.current?.snapshot; }
+    /** An inherited async context is an owner only while that exact operation is active. */
+    ownsCurrent() {
+        return this.current !== undefined && this.owner.getStore() === this.current.snapshot.id;
+    }
+    /** Nested work shares its owner's signal. Other callers are refused or wait in arrival order.
+     * Cancellation is cooperative: admitted work keeps its result/error, and no new nested work starts
+     * after cancellation. The slot stays occupied until the admitted work settles.
+     */
+    async run(kind, label, work, wait = false) {
+        if (this.closed)
+            return undefined;
+        if (this.ownsCurrent()) {
+            const signal = this.current.abort.signal;
+            return signal.aborted ? undefined : await work(signal);
+        }
+        if (this.current !== undefined || this.granted) {
+            if (!wait)
+                return undefined;
+            this.listener.trace({ phase: 'queued', kind, label });
+            await new Promise(resolve => this.waiters.push(resolve));
+            this.granted = false;
+            if (this.closed)
+                return undefined;
+        }
+        const snapshot = Object.freeze({ id: ++this.sequence, kind, label, startedAt: Date.now() });
+        const operation = { snapshot, abort: new AbortController() };
+        this.current = operation;
+        try {
+            this.listener.trace({ phase: 'begin', id: snapshot.id, kind, label });
+            this.listener.changed(true);
+            if (operation.abort.signal.aborted)
+                return undefined;
+            return await this.owner.run(snapshot.id, () => work(operation.abort.signal));
+        }
+        finally {
+            this.current = undefined;
+            // Reserve before publishing: an observer may synchronously try to claim the empty slot.
+            const next = this.waiters.shift();
+            this.granted = next !== undefined;
+            try {
+                this.listener.trace({ phase: 'end', id: snapshot.id, kind, cancelled: operation.abort.signal.aborted });
+                this.listener.changed(false);
+            }
+            finally {
+                next?.();
+            }
+        }
+    }
+    /** Abort cooperatively, keeping the slot until work has settled. */
+    cancel() {
+        if (this.current === undefined)
+            return false;
+        this.current.abort.abort();
+        return true;
+    }
+    /** Permanently refuse new claims, abort the occupant and release all waiting callers. */
+    close() {
+        this.closed = true;
+        this.cancel();
+        for (const wake of this.waiters.splice(0))
+            wake();
+    }
+}

package/dist/controller/loop-coordinator.d.ts

@@ -0,0 +1,48 @@
+import type { ObjectValue } from '../json.ts';
+import type { LoopProgress, LoopTerminalReason } from '../contracts.ts';
+import { type LoopLimits, type LoopProtocol } from './loop.ts';
+import { type VerifierPort } from './verifier.ts';
+/** Application facts and effects a loop needs; no Controller, State or Transcript crosses here. */
+export interface LoopHost {
+    facts(): {
+        sessionId?: string;
+        online: boolean;
+        busy: boolean;
+        pending: boolean;
+        ready: boolean;
+    };
+    reply(): string;
+    send(prompt: string): Promise<void>;
+    publish(failure?: string): void;
+    trace(event: string, detail: ObjectValue): void;
+}
+export interface LoopCoordinatorOptions {
+    directory: string;
+    verifier?: VerifierPort;
+    verdictRoot?: string;
+    deadlineMs?: number;
+    allowSelfFallback?: boolean;
+}
+/** Owns the selected run and its lifetime, while ScoredLoop owns the pure scoring rules. */
+export declare class LoopCoordinator {
+    private readonly host;
+    private readonly options;
+    private current?;
+    private closed;
+    constructor(host: LoopHost, options: LoopCoordinatorOptions);
+    get progress(): LoopProgress | undefined;
+    get sessionId(): string | undefined;
+    get verifierName(): string | undefined;
+    get forkedVerification(): boolean;
+    get selfScoring(): boolean;
+    start(protocol: LoopProtocol, limits: LoopLimits): Promise<void>;
+    stop(reason?: LoopTerminalReason): void;
+    answer(text: string): Promise<void>;
+    clearResult(): void;
+    forget(): void;
+    /** Called after application facts or transcript content change. */
+    changed(): void;
+    idle(sessionId: string): void;
+    /** Stop timers and verifier work before the application tears down the connection. */
+    close(): Promise<void>;
+}