@alisio/core 0.5.1 → 0.6.0

package/dist/forge/limits.js

@@ -0,0 +1,73 @@
+/**
+ * Forja limit merging: global ∩ project ∩ request. Pure: no I/O.
+ *
+ * The global layer (user config) picks values up to the hard maxima; project and request layers can
+ * only lower them (spec D16). Projects may lower only a subset (§10); a request may lower any limit.
+ */
+import { ForgeError } from "./errors.js";
+import { MAX_MESSAGE_BYTES } from "./protocol.js";
+const KiB = 1024;
+const MiB = 1024 * KiB;
+/**
+ * The most a tool input may weigh: the protocol message that carries it (envelope, ids, tool name)
+ * must fit in `MAX_MESSAGE_BYTES`, so the effective limit stays a little below it whatever the
+ * configuration says. Over this a call is refused as `TOOL_INPUT_INVALID` before it is sent.
+ */
+export const MAX_CALL_INPUT_BYTES = MAX_MESSAGE_BYTES - 4 * KiB;
+/** Defaults of the spec's §6.5 table. */
+export const DEFAULT_FORGE_LIMITS = {
+    maxSourceBytes: 64 * KiB,
+    timeoutMs: 30_000,
+    memoryBytes: 32 * MiB,
+    stackBytes: 256 * KiB,
+    maxToolCalls: 50,
+    maxConcurrency: 4,
+    maxCallInputBytes: 256 * KiB,
+    maxCallResponseBytes: 512 * KiB,
+    maxRetainedOutputBytes: 1 * MiB,
+    maxOutputChars: 16_000,
+};
+/** Hard global maxima of the same table. */
+export const MAX_FORGE_LIMITS = {
+    maxSourceBytes: 64 * KiB,
+    timeoutMs: 300_000,
+    memoryBytes: 128 * MiB,
+    stackBytes: 512 * KiB,
+    maxToolCalls: 500,
+    maxConcurrency: 16,
+    maxCallInputBytes: 1 * MiB,
+    maxCallResponseBytes: 2 * MiB,
+    maxRetainedOutputBytes: 4 * MiB,
+    maxOutputChars: 48_000,
+};
+/** The limits a project config may lower; the rest is global-only. */
+export const PROJECT_LOWERABLE_LIMITS = [
+    "timeoutMs",
+    "maxToolCalls",
+    "maxConcurrency",
+    "maxOutputChars",
+];
+const KEYS = Object.keys(DEFAULT_FORGE_LIMITS);
+function checked(layer, key, value) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new ForgeError("INVALID_INPUT", `${layer} limit ${key} must be a positive integer`);
+    }
+    return value;
+}
+export function mergeLimits(layers) {
+    const merged = { ...DEFAULT_FORGE_LIMITS };
+    for (const key of KEYS) {
+        const configured = layers.global?.[key];
+        if (configured !== undefined) {
+            merged[key] = Math.min(checked("global", key, configured), MAX_FORGE_LIMITS[key]);
+        }
+        const project = PROJECT_LOWERABLE_LIMITS.includes(key) ? layers.project?.[key] : undefined;
+        if (project !== undefined)
+            merged[key] = Math.min(merged[key], checked("project", key, project));
+        const request = layers.request?.[key];
+        if (request !== undefined)
+            merged[key] = Math.min(merged[key], checked("request", key, request));
+    }
+    merged.maxCallInputBytes = Math.min(merged.maxCallInputBytes, MAX_CALL_INPUT_BYTES);
+    return merged;
+}

package/dist/forge/nested.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The nested-call port of Forja (spec D-24, D-29, §6.4): how a script running inside a `js_run`
+ * call reaches other tools. A nested call is NOT a second permission system: it passes the same
+ * gate a direct call of the run passes (the run's `toolFilter`, opt-in tools, the LIVE run policy
+ * and `decideEffect`), with two differences that follow from "never open a new approval":
+ * approvals and stored grants do not exist for it, and the answer to "would need to ask" is a
+ * structured error instead of a prompt.
+ *
+ * The runner builds one dispatcher per tool call (`core/call-internals.ts`); the broker of Phase 3b
+ * is its only consumer. Nothing here knows QuickJS.
+ */
+import type { ArtifactPublisher, ToolDecisions, ToolDefinition, ToolResult } from "@alisio/sdk";
+import type { Policy } from "../core/contracts.ts";
+import type { ToolRegistry } from "../core/registry.ts";
+import type { PathAccess } from "../runtime/access.ts";
+import { type ForgeErrorCode } from "./errors.ts";
+/**
+ * Tools no script can reach in v1: Forja's own tools and `execute` (no recursion), the guide
+ * (a model-facing tool), and the subagent tools (`task`, `task_wait` and `send_message` can wait
+ * on a child session that is waiting for this very call: D-29), and `ask_user_question` (the only
+ * tool that opens an interactive prompt; approvals and installs are already refused). Opt-in tools (`OPT_IN_TOOLS`) are
+ * excluded as well.
+ */
+export declare const FORGE_EXCLUDED_TOOLS: ReadonlySet<string>;
+export interface NestedCallStart {
+    /** `${parentCallId}:forge:${n}`: the journal id of this call; never a `tool_calls` row. */
+    nestedCallId: string;
+    name: string;
+    effect: string;
+    /** Resolved absolute paths the tool declared (journaled for `write` calls, D-31). */
+    paths: string[];
+}
+export interface NestedCallRequest {
+    name: unknown;
+    input?: unknown;
+    /** Cancels this call; combined with the signal of the parent call. */
+    signal?: AbortSignal;
+    /** Runs once the call passed the gate, right before the tool executes. */
+    onStart?: (start: NestedCallStart) => void;
+}
+export type NestedCallOutcome = {
+    ok: true;
+    nestedCallId: string;
+    effect: string;
+    /** Text parts of the result, joined. */
+    text: string;
+    /** The text parsed as JSON when it is JSON, else the text. */
+    value: unknown;
+    result: ToolResult;
+} | {
+    ok: false;
+    nestedCallId: string;
+    code: ForgeErrorCode;
+    message: string;
+    /** Known once the tool was found; lets the caller journal the failed attempt. */
+    effect?: string;
+};
+export interface NestedCallDispatcher {
+    /** The tools a nested call can reach right now (what `catalog.search` lists). */
+    catalog(): ToolDefinition[];
+    /**
+     * Whether the registry has a tool of this name, reachable or not. The only names a record or a
+     * broadcast may carry: a name a script invented is never stored.
+     */
+    knows(name: string): boolean;
+    call(request: NestedCallRequest): Promise<NestedCallOutcome>;
+}
+export interface NestedDispatcherDeps {
+    registry: ToolRegistry;
+    /** The run's live policy object; read at every call (a session approval widens it). */
+    policy: Policy;
+    /** Whether the run could open an approval for a direct call (only to tell the error apart). */
+    approvals: boolean;
+    /**
+     * Whether a write confined to the scratchpad may run without an approval (default true). It is
+     * false only for a run locked down on purpose (a child run with approvals turned off).
+     */
+    scratchWrites?: boolean;
+    toolFilter?: (tool: ToolDefinition) => boolean;
+    optInTools?: readonly string[];
+    workspace: string;
+    session: string;
+    label?: string;
+    runId?: string;
+    /** The id of the parent tool call; artifacts and decisions are bound to it. */
+    parentCallId: string;
+    signal: AbortSignal;
+    pathAccess?: PathAccess;
+    artifacts?: ArtifactPublisher;
+    decisions?: ToolDecisions;
+    /** The run's guard (context changed, token budget spent): throws to refuse the call. */
+    guard?: (effect: string) => void;
+    /** Flags the parent call effectful; called when a non-read, non-internal call starts. */
+    markEffectful: () => void;
+}
+export declare function createNestedDispatcher(deps: NestedDispatcherDeps): NestedCallDispatcher;

package/dist/forge/nested.js

@@ -0,0 +1,214 @@
+import { OPT_IN_TOOLS, optInAllows } from "../core/opt-in.js";
+import { decideEffect, effectOf } from "../permissions/decide.js";
+import { isForgeError } from "./errors.js";
+import { forgeCallId } from "./journal.js";
+import { hasScratchEstimator, scratchIncomingBytes } from "./scratch-quota.js";
+/**
+ * Tools no script can reach in v1: Forja's own tools and `execute` (no recursion), the guide
+ * (a model-facing tool), and the subagent tools (`task`, `task_wait` and `send_message` can wait
+ * on a child session that is waiting for this very call: D-29), and `ask_user_question` (the only
+ * tool that opens an interactive prompt; approvals and installs are already refused). Opt-in tools (`OPT_IN_TOOLS`) are
+ * excluded as well.
+ */
+export const FORGE_EXCLUDED_TOOLS = new Set([
+    "js_run",
+    "forge_guide",
+    "task",
+    "task_wait",
+    "send_message",
+    "execute",
+    // Opens an interactive prompt; a script has nobody to ask (D7: never a new approval or UI).
+    "ask_user_question",
+]);
+const isPlainObject = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const messageOf = (error) => error instanceof Error ? error.message : String(error);
+export function createNestedDispatcher(deps) {
+    let counter = 0;
+    /** The tool when this run lets a script reach it, else undefined (excluded, filtered, absent). */
+    const reachable = (name) => {
+        if (FORGE_EXCLUDED_TOOLS.has(name) || OPT_IN_TOOLS.has(name))
+            return undefined;
+        let tool;
+        try {
+            tool = deps.registry.get(name);
+        }
+        catch {
+            return undefined;
+        }
+        if (deps.toolFilter && !deps.toolFilter(tool))
+            return undefined;
+        if (!optInAllows(name, deps.optInTools))
+            return undefined;
+        return tool;
+    };
+    const decide = (tool, approvals) => decideEffect(deps.policy, tool, { approvals, capabilityGranted: false });
+    const allInScratch = async (targets) => {
+        const access = deps.pathAccess;
+        if (!access || targets.length === 0)
+            return false;
+        const inside = await Promise.all(targets.map((t) => access.isScratchPath(t, deps.session)));
+        return inside.every(Boolean);
+    };
+    return {
+        knows(name) {
+            try {
+                deps.registry.get(name);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        catalog() {
+            return deps.registry
+                .list()
+                .filter((tool) => reachable(tool.name) && decide(tool, false).kind === "allow");
+        },
+        async call(request) {
+            const nestedCallId = forgeCallId(deps.parentCallId, ++counter);
+            const fail = (code, message, effect) => ({
+                ok: false,
+                nestedCallId,
+                code,
+                message,
+                ...(effect ? { effect } : {}),
+            });
+            const name = request.name;
+            if (typeof name !== "string" || name === "")
+                return fail("TOOL_UNAVAILABLE", "tool name must be a non-empty string");
+            const tool = reachable(name);
+            if (!tool)
+                return fail("TOOL_UNAVAILABLE", `Tool "${name}" is not available from js_run`);
+            const effect = effectOf(tool);
+            const rawInput = request.input === undefined ? {} : request.input;
+            if (!isPlainObject(rawInput))
+                return fail("TOOL_INPUT_INVALID", "tool input must be a JSON object", effect);
+            let input;
+            try {
+                input = deps.registry.parse(name, JSON.stringify(rawInput));
+            }
+            catch (error) {
+                return fail("TOOL_INPUT_INVALID", messageOf(error), effect);
+            }
+            const signal = request.signal ? AbortSignal.any([deps.signal, request.signal]) : deps.signal;
+            // Declared paths are resolved first, like a direct call, but can never ask for a directory.
+            const resolved = new Map();
+            const targets = [];
+            try {
+                signal.throwIfAborted();
+                if (deps.pathAccess)
+                    for (const declared of tool.paths?.(input) ?? [])
+                        if (!resolved.has(declared)) {
+                            const target = await deps.pathAccess.resolve(declared, {
+                                workspace: deps.workspace,
+                                session: deps.session,
+                                ...(deps.label ? { label: deps.label } : {}),
+                                signal,
+                                interactive: false,
+                            });
+                            resolved.set(declared, target);
+                            resolved.set(target, target);
+                            targets.push(target);
+                        }
+            }
+            catch (error) {
+                if (signal.aborted)
+                    return fail("CANCELLED", "cancelled", effect);
+                return fail("PERMISSION_DENIED", messageOf(error), effect);
+            }
+            try {
+                deps.guard?.(effect);
+            }
+            catch (error) {
+                return fail("PERMISSION_DENIED", messageOf(error), effect);
+            }
+            if (decide(tool, false).kind !== "allow") {
+                // Same answer as a direct call: "would ask" is APPROVAL_REQUIRED, "never allowed" is denied.
+                const direct = decide(tool, deps.approvals);
+                // The scratchpad is an authorized write root: a write confined to it needs no approval,
+                // also when nobody could be asked (headless).
+                const scratchWrite = deps.scratchWrites !== false &&
+                    effect === "write" &&
+                    !tool.capability &&
+                    hasScratchEstimator(name) &&
+                    decide(tool, true).kind === "ask" &&
+                    (await allInScratch(targets));
+                if (!scratchWrite)
+                    return direct.kind === "ask"
+                        ? fail("APPROVAL_REQUIRED", `"${name}" needs approval (effect: ${effect}); a script cannot request one. ` +
+                            "Call it directly or ask the user to allow it for this session.", effect)
+                        : fail("PERMISSION_DENIED", `Capability denied: ${tool.capability ?? effect}`, effect);
+            }
+            // A write confined to the scratchpad is bound by its quota, however it was allowed. The check
+            // and the write run under one lock, so parallel writes cannot all pass it (L1).
+            let releaseScratch;
+            try {
+                if (effect === "write" && !tool.capability && (await allInScratch(targets))) {
+                    releaseScratch = await deps.pathAccess?.lockScratch(deps.session);
+                    const problem = await deps.pathAccess?.scratchQuotaProblem(deps.session, await scratchIncomingBytes(name, input, targets), targets);
+                    if (problem)
+                        return fail("BUDGET_EXCEEDED", problem, effect);
+                }
+                // From here the tool may leave effects, even if the script is then cancelled.
+                if (effect !== "read" && effect !== "internal")
+                    deps.markEffectful();
+                request.onStart?.({ nestedCallId, name, effect, paths: targets });
+                const context = {
+                    signal,
+                    workspace: deps.workspace,
+                    emit: () => { },
+                    session: deps.session,
+                    callId: deps.parentCallId,
+                    ...(deps.runId ? { runId: deps.runId } : {}),
+                    ...(deps.label ? { label: deps.label } : {}),
+                    ...(deps.artifacts ? { artifacts: deps.artifacts } : {}),
+                    ...(deps.decisions ? { decisions: deps.decisions } : {}),
+                    // A script can never open the installation prompt.
+                    approveInstall: async () => "deny",
+                    ...(deps.pathAccess
+                        ? {
+                            resolvePath: (path) => {
+                                const known = resolved.get(path);
+                                return known !== undefined
+                                    ? Promise.resolve(known)
+                                    : deps.pathAccess.resolve(path, {
+                                        workspace: deps.workspace,
+                                        session: deps.session,
+                                        ...(deps.label ? { label: deps.label } : {}),
+                                        signal,
+                                        interactive: false,
+                                    });
+                            },
+                        }
+                        : {}),
+                };
+                let result;
+                try {
+                    result = await tool.execute(input, context);
+                }
+                catch (error) {
+                    if (signal.aborted)
+                        return fail("CANCELLED", "cancelled", effect);
+                    return fail(isForgeError(error) ? error.code : "TOOL_FAILED", messageOf(error), effect);
+                }
+                const text = result.content
+                    .filter((part) => part.type === "text")
+                    .map((part) => part.text)
+                    .join("\n");
+                if (result.isError)
+                    return fail("TOOL_FAILED", text, effect);
+                let value = text;
+                try {
+                    value = JSON.parse(text);
+                }
+                catch {
+                    /* Not JSON: the text itself is the value. */
+                }
+                return { ok: true, nestedCallId, effect, text, value, result };
+            }
+            finally {
+                releaseScratch?.();
+            }
+        },
+    };
+}

package/dist/forge/ports.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Ports of the Forja core (hexagonal). Engines, hosts, transports and stores are adapters; the
+ * core never depends on QuickJS, Pyodide, Docker or SQLite. Types only: no runtime code.
+ *
+ * Later phases add the remaining ports (`IsolateHost`, `Transport`, `ExecutionJournal`,
+ * `StateStore`, `GuideProvider`) next to these.
+ */
+import type { EngineDescriptor, EngineId, EngineLanguage, IsolationLevel, PermissionMode } from "@alisio/sdk";
+import type { ForgeErrorCode } from "./errors.ts";
+import type { ForgeLimits } from "./limits.ts";
+import type { GuestMessage, HostMessage } from "./protocol.ts";
+export type { EngineDescriptor, EngineId, EngineLanguage, IsolationLevel };
+export interface ExecutionRequest {
+    language: EngineLanguage;
+    source: string;
+    title?: string;
+    /** Can only lower the effective limits. */
+    requestedLimits?: Partial<ForgeLimits>;
+    /** Configured or forced by the user; never chosen by the model. */
+    engineHint?: EngineId;
+    /** Per-engine extensions (inputs, extras, rerunOf...). */
+    payload?: Record<string, unknown>;
+}
+/**
+ * Built only by the core from the runner's tool context. No field of the model's input can
+ * override it.
+ */
+export interface TrustedExecutionContext {
+    executionId: string;
+    toolCallId: string;
+    rootSessionId: string;
+    workspace: string;
+    permissionMode: PermissionMode;
+    allowAnalysis: boolean;
+    allowProcess: boolean;
+    signal: AbortSignal;
+    limits: ForgeLimits;
+}
+/** An execution ready to run; engines extend it with their own handles. */
+export interface PreparedExecution {
+    readonly executionId: string;
+    readonly engine: EngineId;
+    readonly limits: ForgeLimits;
+    /** The `analysis_executions` row this execution created (Python); the journal links to it. */
+    readonly analysisExecutionId?: string;
+}
+export type TerminationReason = "cancelled" | "timeout" | "protocol_violation" | "limit_exceeded";
+export interface TerminationReport {
+    /** The host checked that the guest no longer runs. */
+    confirmed: boolean;
+    method: "interrupt" | "terminate" | "kill" | "container-kill";
+    elapsedMs: number;
+    /** Resolves once the guest is finally gone; lets an unconfirmed termination keep its slot until then. */
+    settled?: Promise<void>;
+}
+export type EngineOutcome = {
+    kind: "completed";
+    value?: unknown;
+} | {
+    kind: "failed";
+    code: ForgeErrorCode;
+    message: string;
+};
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/** A message for the guest without the envelope fields the transport stamps (`protocol`, `seq`). */
+export type HostReply = DistributiveOmit<HostMessage, "protocol" | "seq">;
+/**
+ * The kernel's side of an execution, handed to the engine's `run`. The engine owns the transport
+ * and the isolate; the kernel decides what each guest message means.
+ */
+export interface KernelChannel {
+    /**
+     * Called by the engine for every guest message that passed validation (schema, sequence,
+     * correlation, size, capability gate), CONCURRENTLY: a slow `call` never blocks the next
+     * message. The optional reply goes to the guest. Throwing a `ForgeError` ends the execution with
+     * that code.
+     */
+    receive(message: GuestMessage): Promise<HostReply | undefined>;
+    /** Called once by the engine with the function that sends a message to the guest (credit grants). */
+    bind(send: (reply: HostReply) => void): void;
+    /** Aborted when the kernel stops the execution (cancellation or deadline). */
+    readonly signal: AbortSignal;
+}
+/** Isolation hosts (spec §6.3, D-20): where the VM runs, and how it is stopped. */
+export interface IsolateExit {
+    code: number | null;
+    signal: string | null;
+    /** Spawn or worker error, when the isolate could not run at all. */
+    error?: string;
+}
+export interface IsolateSession {
+    readonly kind: "worker" | "process";
+    /** Raw guest messages; validation is the engine's job. */
+    onMessage(handler: (raw: unknown) => void): void;
+    /** The stream broke (oversized or malformed frame): a protocol violation. */
+    onStreamError(handler: (reason: string) => void): void;
+    send(message: unknown): void;
+    readonly exited: Promise<IsolateExit>;
+    /** Stops the guest by the host's own means and reports whether it is confirmed gone. */
+    stop(reason: TerminationReason): Promise<TerminationReport>;
+}
+export interface IsolateHost {
+    readonly kind: "worker" | "process";
+    /** Starts an isolate. The guest sends `ready` first; nothing runs until the host sends `start`. */
+    start(): IsolateSession;
+}
+export interface ExecutionEngine {
+    readonly id: EngineId;
+    describe(): Promise<EngineDescriptor>;
+    prepare(request: ExecutionRequest, ctx: TrustedExecutionContext): Promise<PreparedExecution>;
+    run(prepared: PreparedExecution, channel: KernelChannel): Promise<EngineOutcome>;
+    terminate(prepared: PreparedExecution, reason: TerminationReason): Promise<TerminationReport>;
+    /**
+     * Optional step between `run` and the commit of the shared state, for engines whose results must
+     * be published first (Python's artifacts). It runs only when the host did not stop the execution,
+     * and may turn a completed outcome into a failed one: a failure discards the state delta.
+     */
+    collect?(prepared: PreparedExecution, outcome: EngineOutcome): Promise<EngineOutcome>;
+    dispose(prepared: PreparedExecution): Promise<void>;
+}

package/dist/forge/ports.js

@@ -0,0 +1 @@
+export {};

package/dist/forge/progress.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Progress coalescing (spec §5.4, D14): at most 4 progress events per second reach the UI, but a
+ * terminal event (a finished call, the end of a phase) is never dropped. Non-terminal events that
+ * arrive too soon are replaced by the newest one of their category (script progress, a call
+ * starting, anything else) and delivered when that category's window reopens, so a burst of
+ * calls never hides the script's own progress. Pure but for the injected clock and timer.
+ */
+import type { ForgeProgress } from "@alisio/sdk";
+export declare const PROGRESS_INTERVAL_MS = 250;
+export interface ProgressClock {
+    now(): number;
+    /** Schedules `run` after `ms` and returns how to cancel it. */
+    schedule(run: () => void, ms: number): () => void;
+}
+export declare class ProgressCoalescer {
+    #private;
+    constructor(sink: (progress: ForgeProgress) => void, clock?: ProgressClock);
+    /** A progress event that may be replaced by a newer one of its category. */
+    update(progress: ForgeProgress): void;
+    /** An event that must reach the UI: delivered now, after anything still waiting. */
+    terminal(progress: ForgeProgress): void;
+    /** Delivers what is waiting and stops the timers. */
+    close(): void;
+}

package/dist/forge/progress.js

@@ -0,0 +1,76 @@
+export const PROGRESS_INTERVAL_MS = 250;
+const realClock = {
+    now: () => Date.now(),
+    schedule(run, ms) {
+        const timer = setTimeout(run, ms);
+        timer.unref?.();
+        return () => clearTimeout(timer);
+    },
+};
+const categoryOf = (progress) => progress.phase === "call"
+    ? "call"
+    : progress.message !== undefined ||
+        progress.completed !== undefined ||
+        progress.total !== undefined
+        ? "progress"
+        : "other";
+export class ProgressCoalescer {
+    #sink;
+    #clock;
+    #lanes = new Map();
+    #order = 0;
+    constructor(sink, clock = realClock) {
+        this.#sink = sink;
+        this.#clock = clock;
+    }
+    /** A progress event that may be replaced by a newer one of its category. */
+    update(progress) {
+        const category = categoryOf(progress);
+        let lane = this.#lanes.get(category);
+        if (!lane) {
+            lane = { lastAt: Number.NEGATIVE_INFINITY };
+            this.#lanes.set(category, lane);
+        }
+        const wait = lane.lastAt + PROGRESS_INTERVAL_MS - this.#clock.now();
+        if (wait <= 0 && lane.pending === undefined)
+            return this.#deliver(lane, progress);
+        lane.pending = { progress, order: this.#order++ };
+        const owner = lane;
+        lane.cancel ??= this.#clock.schedule(() => {
+            owner.cancel = undefined;
+            this.#flushLane(owner);
+        }, Math.max(wait, 0));
+    }
+    /** An event that must reach the UI: delivered now, after anything still waiting. */
+    terminal(progress) {
+        this.#flush();
+        this.#sink(progress);
+    }
+    /** Delivers what is waiting and stops the timers. */
+    close() {
+        this.#flush();
+    }
+    /** Everything waiting, in arrival order. */
+    #flush() {
+        const waiting = [];
+        for (const lane of this.#lanes.values()) {
+            lane.cancel?.();
+            lane.cancel = undefined;
+            if (lane.pending)
+                waiting.push({ lane, ...lane.pending });
+            lane.pending = undefined;
+        }
+        for (const item of waiting.sort((a, b) => a.order - b.order))
+            this.#deliver(item.lane, item.progress);
+    }
+    #flushLane(lane) {
+        const pending = lane.pending;
+        lane.pending = undefined;
+        if (pending)
+            this.#deliver(lane, pending.progress);
+    }
+    #deliver(lane, progress) {
+        lane.lastAt = this.#clock.now();
+        this.#sink(progress);
+    }
+}