@carno.js/live 1.8.0 → 1.8.1

package/src/LiveEngine.ts

@@ -1,730 +1,806 @@
-import { AllowAllAuthorizer, authKeysOf, isAuthKey, type LiveAuthorizer } from './auth/authorizer';
-import type { InvalidationBus } from './bus/InvalidationBus';
-import type { LiveConfig } from './config';
-import { ancestorsOf, type DepKey } from './graph/dep-key';
-import { DependencyGraph } from './graph/DependencyGraph';
-import { SubscriptionRegistry } from './graph/SubscriptionRegistry';
-import type { InvalidationEvent } from './graph/types';
-import { PatchEngine } from './patch/PatchEngine';
-import { canonical } from './shared/canonical';
-import { fnv1a64 } from './shared/hash';
-import type { ServerMessage } from './shared/protocol';
-import {
-    canonicalInputs,
-    instanceIdOf,
-    scopeKeyOf
-} from './resource/instance-id';
-import type { ResourceRegistry } from './resource/ResourceRegistry';
-import type { LiveInputs, LiveResource, LiveScope } from './resource/types';
-import { isLiveAuthorizationFailure, LiveRouteExecutionError } from './resource/route-executor';
-import { LiveMetrics } from './observability';
-
-export interface LiveTransport {
-    /**
-     * Send one message. The return value is the underlying socket's: Bun's
-     * `ServerWebSocket.send()` answers -1 under back-pressure and 0 when the
-     * message was dropped. Anything <= 0 counts as back-pressure here.
-     */
-    send(connectionId: string, message: ServerMessage): number;
-}
-
-export interface LiveStats {
-    instances: number;
-    recomputes: number;
-    /**
-     * Recomputes that produced no patch. The most important number in the
-     * system: it measures the precision of the invalidation granularity
-     * directly. Climbing means the graph is waking instances for nothing.
-     */
-    recomputesWithoutPatch: number;
-}
-
-interface LiveInstance {
-    id: string;
-    resource: LiveResource;
-    inputs: LiveInputs;
-    scope: LiveScope;
-    patcher: PatchEngine;
-    data: unknown;
-    hash: string;
-    revision: number;
-    computing: Promise<void> | null;
-    dirty: boolean;
-    dropTimer: ReturnType<typeof setTimeout> | null;
-}
-
-export class LiveEngine {
-    private readonly instances = new Map<string, LiveInstance>();
-    /** One promise per instance under construction; also reserves node capacity. */
-    private readonly creating = new Map<string, Promise<LiveInstance>>();
-    /** connectionId → sid → instanceId. Addressing only; refcount lives in the registry. */
-    private readonly bindings = new Map<string, Map<string, string>>();
-    private readonly backpressure = new Map<string, number>();
-    private readonly pending = new Set<string>();
-    /** Scope of each connection, as resolved at subscribe time. */
-    private readonly scopes = new Map<string, LiveScope>();
-    /** connectionId → instanceId → decision. Cleared when an `auth:` key fires. */
-    private readonly authorized = new Map<string, Map<string, boolean>>();
-
-    private flushTimer: ReturnType<typeof setTimeout> | null = null;
-    private unsubscribeBus: (() => void) | null = null;
-    private recomputes = 0;
-    private recomputesWithoutPatch = 0;
-
-    constructor(
-        private readonly resources: ResourceRegistry,
-        private readonly graph: DependencyGraph,
-        private readonly subs: SubscriptionRegistry,
-        private readonly bus: InvalidationBus,
-        private readonly transport: LiveTransport,
-        private readonly config: LiveConfig,
-        private readonly authorizer: LiveAuthorizer = new AllowAllAuthorizer(),
-        private readonly metrics: LiveMetrics = LiveMetrics.none()
-    ) {}
-
-    start(): void {
-        if (this.unsubscribeBus) {
-            return;
-        }
-
-        this.unsubscribeBus = this.bus.subscribe(events => this.onInvalidation(events));
-    }
-
-    stop(): void {
-        this.unsubscribeBus?.();
-        this.unsubscribeBus = null;
-
-        if (this.flushTimer) {
-            clearTimeout(this.flushTimer);
-            this.flushTimer = null;
-        }
-
-        for (const instance of this.instances.values()) {
-            if (instance.dropTimer) {
-                clearTimeout(instance.dropTimer);
-            }
-        }
-    }
-
-    async subscribe(
-        connectionId: string,
-        sid: string,
-        resourceId: string,
-        inputs: LiveInputs,
-        scope: LiveScope,
-        clientHash?: string
-    ): Promise<void> {
-        const resource = this.resources.get(resourceId);
-
-        if (!resource) {
-            this.fail(connectionId, sid, 'unknown_resource', `No live resource named "${resourceId}".`);
-            return;
-        }
-
-        let instanceId: string;
-
-        try {
-            const scopeKey = scopeKeyOf(resource.meta.shared, scope);
-            instanceId = instanceIdOf(resource.id, scopeKey, canonicalInputs(inputs, this.config.maxInputBytes));
-        } catch (error) {
-            this.fail(connectionId, sid, 'invalid_subscription', (error as Error).message);
-            return;
-        }
-
-        this.scopes.set(connectionId, scope);
-
-        const allowed = await this.checkAuthorization(connectionId, instanceId, resource, inputs, scope);
-
-        if (!allowed) {
-            this.fail(
-                connectionId,
-                sid,
-                'forbidden',
-                `This connection is not allowed to subscribe to "${resourceId}".`
-            );
-            return;
-        }
-
-        const known = this.instances.has(instanceId);
-        const creating = this.creating.has(instanceId);
-        const heldByConnection = this.subs.countForConnection(connectionId);
-
-        if (!this.bindings.get(connectionId)?.has(sid) && heldByConnection >= this.config.maxInstancesPerConnection) {
-            this.fail(
-                connectionId,
-                sid,
-                'too_many_instances',
-                `A connection may hold at most ${this.config.maxInstancesPerConnection} live instances.`
-            );
-            return;
-        }
-
-        if (!known && !creating && this.instances.size + this.creating.size >= this.config.maxInstancesPerNode) {
-            this.fail(connectionId, sid, 'node_at_capacity', 'This node is at its live instance ceiling.');
-            return;
-        }
-
-        const previous = this.bindings.get(connectionId)?.get(sid);
-
-        if (previous !== instanceId) {
-            if (previous !== undefined) {
-                this.release(connectionId, sid);
-            }
-
-            this.bind(connectionId, sid, instanceId);
-            this.subs.subscribe(connectionId, instanceId);
-        }
-
-        let instance = this.instances.get(instanceId);
-
-        if (instance?.dropTimer) {
-            clearTimeout(instance.dropTimer);
-            instance.dropTimer = null;
-        }
-
-        if (!instance) {
-            const creation = this.creating.get(instanceId)
-                ?? this.startInstanceCreation(instanceId, resource, inputs, scope);
-
-            try {
-                instance = await creation;
-            } catch (error) {
-                this.release(connectionId, sid);
-
-                const code = error instanceof LiveRouteExecutionError
-                    ? error.statusCode === 401 || error.statusCode === 403
-                        ? 'forbidden'
-                        : error.statusCode >= 400 && error.statusCode < 500
-                            ? 'invalid_subscription'
-                            : 'compute_failed'
-                    : 'compute_failed';
-
-                this.fail(connectionId, sid, code, (error as Error).message);
-                return;
-            }
-        }
-
-        if (this.bindings.get(connectionId)?.get(sid) !== instanceId) {
-            this.scheduleDrop(instanceId);
-            return;
-        }
-
-        this.sendState(connectionId, sid, instance, clientHash);
-    }
-
-    unsubscribe(connectionId: string, sid: string): void {
-        this.release(connectionId, sid);
-    }
-
-    async resync(connectionId: string, sid: string, clientHash?: string): Promise<void> {
-        const instanceId = this.bindings.get(connectionId)?.get(sid);
-        const instance = instanceId ? this.instances.get(instanceId) : undefined;
-
-        if (!instance) {
-            this.fail(connectionId, sid, 'unknown_subscription', 'Resync for a subscription this node does not hold.');
-            return;
-        }
-
-        this.sendState(connectionId, sid, instance, clientHash);
-    }
-
-    dropConnection(connectionId: string): void {
-        const owned = this.bindings.get(connectionId);
-
-        if (owned) {
-            for (const sid of [...owned.keys()]) {
-                this.release(connectionId, sid);
-            }
-        }
-
-        this.bindings.delete(connectionId);
-        this.backpressure.delete(connectionId);
-        this.scopes.delete(connectionId);
-        this.authorized.delete(connectionId);
-    }
-
-    /** Manual invalidation — the third emitter of §4.4. */
-    invalidate(key: string): void {
-        this.bus.publish([{ key, columns: null }]);
-    }
-
-    stats(): LiveStats {
-        return {
-            instances: this.instances.size,
-            recomputes: this.recomputes,
-            recomputesWithoutPatch: this.recomputesWithoutPatch
-        };
-    }
-
-    /**
-     * Polling has no server-side subscription to cache an authorization
-     * decision against, so it must ask the live authorizer on every request.
-     */
-    async authorizePolling(
-        connectionId: string,
-        resourceId: string,
-        inputs: LiveInputs,
-        scope: LiveScope
-    ): Promise<boolean> {
-        const resource = this.resources.get(resourceId);
-
-        if (!resource) {
-            return false;
-        }
-
-        try {
-            scopeKeyOf(resource.meta.shared, scope);
-        } catch {
-            return false;
-        }
-
-        try {
-            return await this.authorizer.authorize({
-                resourceId: resource.id,
-                controllerName: resource.controllerName,
-                handlerName: resource.handlerName,
-                meta: resource.meta,
-                inputs,
-                scope,
-                connectionId
-            });
-        } catch {
-            return false;
-        }
-    }
-
-    // ------------------------------------------------------------ internals
-
-    private bind(connectionId: string, sid: string, instanceId: string): void {
-        let owned = this.bindings.get(connectionId);
-
-        if (!owned) {
-            owned = new Map<string, string>();
-            this.bindings.set(connectionId, owned);
-        }
-
-        owned.set(sid, instanceId);
-    }
-
-    private release(connectionId: string, sid: string): void {
-        const owned = this.bindings.get(connectionId);
-        const instanceId = owned?.get(sid);
-
-        if (!owned || !instanceId) {
-            return;
-        }
-
-        owned.delete(sid);
-        this.authorized.get(connectionId)?.delete(instanceId);
-        this.subs.unsubscribe(connectionId, instanceId);
-        this.scheduleDrop(instanceId);
-    }
-
-    private async checkAuthorization(
-        connectionId: string,
-        instanceId: string,
-        resource: LiveResource,
-        inputs: LiveInputs,
-        scope: LiveScope
-    ): Promise<boolean> {
-        let perConnection = this.authorized.get(connectionId);
-
-        if (!perConnection) {
-            perConnection = new Map<string, boolean>();
-            this.authorized.set(connectionId, perConnection);
-        }
-
-        const cached = perConnection.get(instanceId);
-
-        if (cached !== undefined) {
-            return cached;
-        }
-
-        let allowed: boolean;
-
-        try {
-            allowed = await this.authorizer.authorize({
-                resourceId: resource.id,
-                controllerName: resource.controllerName,
-                handlerName: resource.handlerName,
-                meta: resource.meta,
-                inputs,
-                scope,
-                connectionId
-            });
-        } catch {
-            // An authorizer that throws is a denial. Failing open here would
-            // hand out data on a bug in application code.
-            allowed = false;
-        }
-
-        perConnection.set(instanceId, allowed);
-        return allowed;
-    }
-
-    /** An `auth:` key fired: drop the cached decisions it covers and re-ask. */
-    private reauthorize(key: DepKey): void {
-        for (const [connectionId, scope] of this.scopes) {
-            const affected = authKeysOf(scope).some(owned => ancestorsOf(owned).includes(key));
-
-            if (!affected) {
-                continue;
-            }
-
-            this.authorized.delete(connectionId);
-
-            const owned = this.bindings.get(connectionId);
-
-            if (!owned) {
-                continue;
-            }
-
-            for (const instanceId of new Set(owned.values())) {
-                const instance = this.instances.get(instanceId);
-
-                if (!instance) {
-                    continue;
-                }
-
-                void this.checkAuthorization(connectionId, instanceId, instance.resource, instance.inputs, scope)
-                    .then(allowed => {
-                        if (!allowed) {
-                            this.revoke(connectionId, instanceId);
-                        }
-                    });
-            }
-        }
-    }
-
-    /** End one connection's hold on one instance, telling it why. */
-    private revoke(connectionId: string, instanceId: string): void {
-        for (const sid of this.sidsFor(connectionId, instanceId)) {
-            this.send(connectionId, {
-                t: 'error',
-                sid,
-                code: 'forbidden',
-                message: 'This subscription is no longer authorized for this connection.'
-            });
-            this.release(connectionId, sid);
-        }
-    }
-
-    private scheduleDrop(instanceId: string): void {
-        if (this.subs.hasSubscribers(instanceId)) {
-            return;
-        }
-
-        const instance = this.instances.get(instanceId);
-
-        if (!instance || instance.dropTimer) {
-            return;
-        }
-
-        // Grace period so coming back from a navigation does not recompute
-        // everything the page had a moment ago.
-        instance.dropTimer = setTimeout(() => {
-            if (!this.subs.hasSubscribers(instanceId)) {
-                this.instances.delete(instanceId);
-                this.graph.remove(instanceId);
-            }
-        }, this.config.unsubGraceMs);
-    }
-
-    private startInstanceCreation(
-        instanceId: string,
-        resource: LiveResource,
-        inputs: LiveInputs,
-        scope: LiveScope
-    ): Promise<LiveInstance> {
-        let resolveCreation!: (instance: LiveInstance) => void;
-        let rejectCreation!: (error: unknown) => void;
-        const creation = new Promise<LiveInstance>((resolve, reject) => {
-            resolveCreation = resolve;
-            rejectCreation = reject;
-        });
-
-        this.creating.set(instanceId, creation);
-
-        void this.createInstance(instanceId, resource, inputs, scope).then(
-            instance => {
-                this.clearInstanceCreation(instanceId, creation);
-                resolveCreation(instance);
-            },
-            error => {
-                this.clearInstanceCreation(instanceId, creation);
-                rejectCreation(error);
-            }
-        );
-
-        return creation;
-    }
-
-    private clearInstanceCreation(instanceId: string, creation: Promise<LiveInstance>): void {
-        if (this.creating.get(instanceId) === creation) {
-            this.creating.delete(instanceId);
-        }
-    }
-
-    private async createInstance(
-        instanceId: string,
-        resource: LiveResource,
-        inputs: LiveInputs,
-        scope: LiveScope
-    ): Promise<LiveInstance> {
-        const { data, deps } = await this.resources.compute(resource, inputs, { scope });
-        this.recomputes++;
-        this.graph.setDependencies(instanceId, deps);
-
-        const instance: LiveInstance = {
-            id: instanceId,
-            resource,
-            inputs,
-            scope,
-            patcher: new PatchEngine(resource.meta.key),
-            data,
-            hash: fnv1a64(canonical(data)),
-            revision: 1,
-            computing: null,
-            dirty: false,
-            dropTimer: null
-        };
-
-        this.instances.set(instanceId, instance);
-        return instance;
-    }
-
-    private sendState(
-        connectionId: string,
-        sid: string,
-        instance: LiveInstance,
-        clientHash?: string
-    ): void {
-        if (clientHash && clientHash === instance.hash) {
-            // The screen already holds this exact content. Nothing on the wire.
-            this.send(connectionId, {
-                t: 'current',
-                sid,
-                rev: instance.revision,
-                hash: instance.hash,
-                key: instance.resource.meta.key
-            });
-            return;
-        }
-
-        this.send(connectionId, {
-            t: 'snapshot',
-            sid,
-            rev: instance.revision,
-            hash: instance.hash,
-            data: instance.data,
-            key: instance.resource.meta.key
-        });
-    }
-
-    private onInvalidation(events: InvalidationEvent[]): void {
-        const before = this.pending.size;
-
-        for (const event of events) {
-            if (isAuthKey(event.key)) {
-                // Not data: nothing to recompute, only permissions to re-check.
-                this.reauthorize(event.key);
-                continue;
-            }
-
-            for (const instanceId of this.graph.resolve(event)) {
-                // Grace-held instances have no subscribers but are still cached.
-                if (this.instances.has(instanceId)) {
-                    this.pending.add(instanceId);
-                }
-            }
-        }
-
-        // Newly pending, not total pending: an invalidation that woke nothing
-        // because the instances were already queued did not cost a fan-out.
-        this.metrics.invalidation(events.length, this.pending.size - before);
-
-        if (this.pending.size === 0 || this.flushTimer) {
-            return;
-        }
-
-        this.flushTimer = setTimeout(() => {
-            this.flushTimer = null;
-            void this.flush();
-        }, this.config.coalesceMs);
-    }
-
-    private async flush(): Promise<void> {
-        const batch = [...this.pending];
-        this.pending.clear();
-
-        this.metrics.instances(this.instances.size);
-
-        for (let i = 0; i < batch.length; i += this.config.fanoutQueueThreshold) {
-            const slice = batch.slice(i, i + this.config.fanoutQueueThreshold);
-            await Promise.all(slice.map(instanceId => this.recompute(instanceId)));
-
-            if (i + this.config.fanoutQueueThreshold < batch.length) {
-                // Yield between slices so a large fan-out does not monopolize
-                // the loop and stall unrelated requests.
-                await new Promise(resolve => setTimeout(resolve, 0));
-            }
-        }
-    }
-
-    private recompute(instanceId: string): Promise<void> {
-        const instance = this.instances.get(instanceId);
-
-        if (!instance) {
-            return Promise.resolve();
-        }
-
-        if (instance.computing) {
-            // Single-flight: N invalidations arriving during one recompute cost
-            // exactly one more recompute, not N.
-            instance.dirty = true;
-            return instance.computing;
-        }
-
-        instance.computing = this.runCompute(instance).finally(() => {
-            instance.computing = null;
-
-            if (instance.dirty) {
-                instance.dirty = false;
-                void this.recompute(instanceId);
-            }
-        });
-
-        return instance.computing;
-    }
-
-    private async runCompute(instance: LiveInstance): Promise<void> {
-        const startedAt = performance.now();
-        let data: unknown;
-        let deps;
-
-        try {
-            ({ data, deps } = await this.resources.compute(
-                instance.resource,
-                instance.inputs,
-                { scope: instance.scope }
-            ));
-        } catch (error) {
-            if (isLiveAuthorizationFailure(error)) {
-                this.revokeInstance(instance.id);
-                return;
-            }
-
-            await this.broadcast(instance, sid => ({ t: 'stale', sid, reason: (error as Error).message }));
-            return;
-        }
-
-        this.recomputes++;
-        this.graph.setDependencies(instance.id, deps);
-
-        const hash = fnv1a64(canonical(data));
-
-        if (hash === instance.hash) {
-            // Recompute is not a patch. Coarse invalidation costs CPU, never
-            // traffic and never a re-render. This is the number of §10.
-            this.recomputesWithoutPatch++;
-            this.metrics.recompute(instance.resource.id, false, 0, performance.now() - startedAt);
-            return;
-        }
-
-        const ops = instance.patcher.diff(instance.data, data);
-        const from = instance.revision;
-
-        instance.data = data;
-        instance.hash = hash;
-        instance.revision += 1;
-
-        this.metrics.recompute(instance.resource.id, true, ops.length, performance.now() - startedAt);
-
-        await this.broadcast(instance, sid => ({
-            t: 'patch',
-            sid,
-            from,
-            to: instance.revision,
-            hash,
-            ops
-        }));
-    }
-
-    private async broadcast(
-        instance: LiveInstance,
-        build: (sid: string) => ServerMessage
-    ): Promise<void> {
-        for (const connectionId of [...this.subs.connectionsOf(instance.id)]) {
-            const scope = this.scopes.get(connectionId);
-            const allowed = scope
-                ? await this.checkAuthorization(connectionId, instance.id, instance.resource, instance.inputs, scope)
-                : false;
-
-            if (!allowed) {
-                this.revoke(connectionId, instance.id);
-                continue;
-            }
-
-            for (const sid of this.sidsFor(connectionId, instance.id)) {
-                const message = build(sid);
-
-                if (message.t === 'patch' && this.isBackedUp(connectionId)) {
-                    // The client is behind. Collapse instead of queueing more.
-                    this.send(connectionId, {
-                        t: 'snapshot',
-                        sid,
-                        rev: instance.revision,
-                        hash: instance.hash,
-                        data: instance.data,
-                        key: instance.resource.meta.key
-                    });
-                    this.backpressure.set(connectionId, 0);
-                    continue;
-                }
-
-                this.send(connectionId, message);
-            }
-        }
-    }
-
-    private revokeInstance(instanceId: string): void {
-        const connections = new Set(this.subs.connectionsOf(instanceId));
-
-        for (const connectionId of connections) {
-            this.revoke(connectionId, instanceId);
-        }
-    }
-
-    private sidsFor(connectionId: string, instanceId: string): string[] {
-        const owned = this.bindings.get(connectionId);
-
-        if (!owned) {
-            return [];
-        }
-
-        const sids: string[] = [];
-
-        for (const [sid, boundInstance] of owned) {
-            if (boundInstance === instanceId) {
-                sids.push(sid);
-            }
-        }
-
-        return sids;
-    }
-
-    private isBackedUp(connectionId: string): boolean {
-        return (this.backpressure.get(connectionId) ?? 0) >= this.config.maxPendingPatches;
-    }
-
-    private send(connectionId: string, message: ServerMessage): void {
-        const result = this.transport.send(connectionId, message);
-        const current = this.backpressure.get(connectionId) ?? 0;
-
-        this.backpressure.set(connectionId, result > 0 ? 0 : current + 1);
-    }
-
-    private fail(connectionId: string, sid: string, code: string, message: string): void {
-        this.send(connectionId, { t: 'error', sid, code, message });
-    }
-}
+import { AllowAllAuthorizer, authKeysOf, isAuthKey, type LiveAuthorizer } from './auth/authorizer';
+import type { InvalidationBus } from './bus/InvalidationBus';
+import type { LiveConfig } from './config';
+import { ancestorsOf, type DepKey } from './graph/dep-key';
+import { DependencyGraph } from './graph/DependencyGraph';
+import { SubscriptionRegistry } from './graph/SubscriptionRegistry';
+import type { InvalidationEvent } from './graph/types';
+import { PatchEngine } from './patch/PatchEngine';
+import { canonical } from './shared/canonical';
+import { fnv1a64 } from './shared/hash';
+import type { ServerMessage } from './shared/protocol';
+import {
+    canonicalInputs,
+    instanceIdOf,
+    scopeKeyOf
+} from './resource/instance-id';
+import type { ResourceRegistry } from './resource/ResourceRegistry';
+import type { LiveInputs, LiveResource, LiveScope } from './resource/types';
+import { isLiveAuthorizationFailure, LiveRouteExecutionError } from './resource/route-executor';
+import { LiveMetrics } from './observability';
+
+export interface LiveTransport {
+    /**
+     * Send one message. The return value is the underlying socket's: Bun's
+     * `ServerWebSocket.send()` answers -1 under back-pressure and 0 when the
+     * message was dropped. Anything <= 0 counts as back-pressure here.
+     */
+    send(connectionId: string, message: ServerMessage): number;
+}
+
+export interface LiveStats {
+    instances: number;
+    recomputes: number;
+    /**
+     * Recomputes that produced no patch. The most important number in the
+     * system: it measures the precision of the invalidation granularity
+     * directly. Climbing means the graph is waking instances for nothing.
+     */
+    recomputesWithoutPatch: number;
+}
+
+interface LiveInstance {
+    id: string;
+    resource: LiveResource;
+    inputs: LiveInputs;
+    scope: LiveScope;
+    patcher: PatchEngine;
+    data: unknown;
+    hash: string;
+    revision: number;
+    computing: Promise<void> | null;
+    dirty: boolean;
+    dropTimer: ReturnType<typeof setTimeout> | null;
+}
+
+export class LiveEngine {
+    private readonly instances = new Map<string, LiveInstance>();
+    /** One promise per instance under construction; also reserves node capacity. */
+    private readonly creating = new Map<string, Promise<LiveInstance>>();
+    /** connectionId → sid → instanceId. Addressing only; refcount lives in the registry. */
+    private readonly bindings = new Map<string, Map<string, string>>();
+    private readonly backpressure = new Map<string, number>();
+    private readonly pending = new Set<string>();
+    /** Scope of each connection, as resolved at subscribe time. */
+    private readonly scopes = new Map<string, LiveScope>();
+    /** connectionId → instanceId → decision. Cleared when an `auth:` key fires. */
+    private readonly authorized = new Map<string, Map<string, boolean>>();
+
+    /**
+     * Permits for concurrent computes, and whoever is queued for one.
+     *
+     * Every compute runs the resource's route and so its queries, against a
+     * database pool far smaller than any fan-out. This caps them where the
+     * query actually happens, so overlapping flushes and the dirty-retry path
+     * are held to the same bound as a flush.
+     */
+    private inFlight = 0;
+    private readonly waiting: (() => void)[] = [];
+
+    private flushTimer: ReturnType<typeof setTimeout> | null = null;
+    private unsubscribeBus: (() => void) | null = null;
+    private recomputes = 0;
+    private recomputesWithoutPatch = 0;
+
+    constructor(
+        private readonly resources: ResourceRegistry,
+        private readonly graph: DependencyGraph,
+        private readonly subs: SubscriptionRegistry,
+        private readonly bus: InvalidationBus,
+        private readonly transport: LiveTransport,
+        private readonly config: LiveConfig,
+        private readonly authorizer: LiveAuthorizer = new AllowAllAuthorizer(),
+        private readonly metrics: LiveMetrics = LiveMetrics.none()
+    ) {}
+
+    start(): void {
+        if (this.unsubscribeBus) {
+            return;
+        }
+
+        this.unsubscribeBus = this.bus.subscribe(events => this.onInvalidation(events));
+    }
+
+    stop(): void {
+        this.unsubscribeBus?.();
+        this.unsubscribeBus = null;
+
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+
+        for (const instance of this.instances.values()) {
+            if (instance.dropTimer) {
+                clearTimeout(instance.dropTimer);
+            }
+        }
+
+        // Let whoever is queued for a permit through: they finish the compute
+        // they already started, rather than awaiting a release that stopping
+        // means will never come. Each one is counted as it goes, so the
+        // release it makes on the way out balances and a restarted engine
+        // does not begin below zero.
+        while (this.waiting.length > 0) {
+            this.inFlight++;
+            this.waiting.shift()!();
+        }
+    }
+
+    async subscribe(
+        connectionId: string,
+        sid: string,
+        resourceId: string,
+        inputs: LiveInputs,
+        scope: LiveScope,
+        clientHash?: string
+    ): Promise<void> {
+        const resource = this.resources.get(resourceId);
+
+        if (!resource) {
+            this.fail(connectionId, sid, 'unknown_resource', `No live resource named "${resourceId}".`);
+            return;
+        }
+
+        let instanceId: string;
+
+        try {
+            const scopeKey = scopeKeyOf(resource.meta.shared, scope);
+            instanceId = instanceIdOf(resource.id, scopeKey, canonicalInputs(inputs, this.config.maxInputBytes));
+        } catch (error) {
+            this.fail(connectionId, sid, 'invalid_subscription', (error as Error).message);
+            return;
+        }
+
+        this.scopes.set(connectionId, scope);
+
+        const allowed = await this.checkAuthorization(connectionId, instanceId, resource, inputs, scope);
+
+        if (!allowed) {
+            this.fail(
+                connectionId,
+                sid,
+                'forbidden',
+                `This connection is not allowed to subscribe to "${resourceId}".`
+            );
+            return;
+        }
+
+        const known = this.instances.has(instanceId);
+        const creating = this.creating.has(instanceId);
+        const heldByConnection = this.subs.countForConnection(connectionId);
+
+        if (!this.bindings.get(connectionId)?.has(sid) && heldByConnection >= this.config.maxInstancesPerConnection) {
+            this.fail(
+                connectionId,
+                sid,
+                'too_many_instances',
+                `A connection may hold at most ${this.config.maxInstancesPerConnection} live instances.`
+            );
+            return;
+        }
+
+        if (!known && !creating && this.instances.size + this.creating.size >= this.config.maxInstancesPerNode) {
+            this.fail(connectionId, sid, 'node_at_capacity', 'This node is at its live instance ceiling.');
+            return;
+        }
+
+        const previous = this.bindings.get(connectionId)?.get(sid);
+
+        if (previous !== instanceId) {
+            if (previous !== undefined) {
+                this.release(connectionId, sid);
+            }
+
+            this.bind(connectionId, sid, instanceId);
+            this.subs.subscribe(connectionId, instanceId);
+        }
+
+        let instance = this.instances.get(instanceId);
+
+        if (instance?.dropTimer) {
+            clearTimeout(instance.dropTimer);
+            instance.dropTimer = null;
+        }
+
+        if (!instance) {
+            const creation = this.creating.get(instanceId)
+                ?? this.startInstanceCreation(instanceId, resource, inputs, scope);
+
+            try {
+                instance = await creation;
+            } catch (error) {
+                this.release(connectionId, sid);
+
+                const code = error instanceof LiveRouteExecutionError
+                    ? error.statusCode === 401 || error.statusCode === 403
+                        ? 'forbidden'
+                        : error.statusCode >= 400 && error.statusCode < 500
+                            ? 'invalid_subscription'
+                            : 'compute_failed'
+                    : 'compute_failed';
+
+                this.fail(connectionId, sid, code, (error as Error).message);
+                return;
+            }
+        }
+
+        if (this.bindings.get(connectionId)?.get(sid) !== instanceId) {
+            this.scheduleDrop(instanceId);
+            return;
+        }
+
+        this.sendState(connectionId, sid, instance, clientHash);
+    }
+
+    unsubscribe(connectionId: string, sid: string): void {
+        this.release(connectionId, sid);
+    }
+
+    async resync(connectionId: string, sid: string, clientHash?: string): Promise<void> {
+        const instanceId = this.bindings.get(connectionId)?.get(sid);
+        const instance = instanceId ? this.instances.get(instanceId) : undefined;
+
+        if (!instance) {
+            this.fail(connectionId, sid, 'unknown_subscription', 'Resync for a subscription this node does not hold.');
+            return;
+        }
+
+        this.sendState(connectionId, sid, instance, clientHash);
+    }
+
+    dropConnection(connectionId: string): void {
+        const owned = this.bindings.get(connectionId);
+
+        if (owned) {
+            for (const sid of [...owned.keys()]) {
+                this.release(connectionId, sid);
+            }
+        }
+
+        this.bindings.delete(connectionId);
+        this.backpressure.delete(connectionId);
+        this.scopes.delete(connectionId);
+        this.authorized.delete(connectionId);
+    }
+
+    /** Manual invalidation — the third emitter of §4.4. */
+    invalidate(key: string): void {
+        this.bus.publish([{ key, columns: null }]);
+    }
+
+    stats(): LiveStats {
+        return {
+            instances: this.instances.size,
+            recomputes: this.recomputes,
+            recomputesWithoutPatch: this.recomputesWithoutPatch
+        };
+    }
+
+    /**
+     * Polling has no server-side subscription to cache an authorization
+     * decision against, so it must ask the live authorizer on every request.
+     */
+    async authorizePolling(
+        connectionId: string,
+        resourceId: string,
+        inputs: LiveInputs,
+        scope: LiveScope
+    ): Promise<boolean> {
+        const resource = this.resources.get(resourceId);
+
+        if (!resource) {
+            return false;
+        }
+
+        try {
+            scopeKeyOf(resource.meta.shared, scope);
+        } catch {
+            return false;
+        }
+
+        try {
+            return await this.authorizer.authorize({
+                resourceId: resource.id,
+                controllerName: resource.controllerName,
+                handlerName: resource.handlerName,
+                meta: resource.meta,
+                inputs,
+                scope,
+                connectionId
+            });
+        } catch {
+            return false;
+        }
+    }
+
+    // ------------------------------------------------------------ internals
+
+    private bind(connectionId: string, sid: string, instanceId: string): void {
+        let owned = this.bindings.get(connectionId);
+
+        if (!owned) {
+            owned = new Map<string, string>();
+            this.bindings.set(connectionId, owned);
+        }
+
+        owned.set(sid, instanceId);
+    }
+
+    private release(connectionId: string, sid: string): void {
+        const owned = this.bindings.get(connectionId);
+        const instanceId = owned?.get(sid);
+
+        if (!owned || !instanceId) {
+            return;
+        }
+
+        owned.delete(sid);
+        this.authorized.get(connectionId)?.delete(instanceId);
+        this.subs.unsubscribe(connectionId, instanceId);
+        this.scheduleDrop(instanceId);
+    }
+
+    private async checkAuthorization(
+        connectionId: string,
+        instanceId: string,
+        resource: LiveResource,
+        inputs: LiveInputs,
+        scope: LiveScope
+    ): Promise<boolean> {
+        let perConnection = this.authorized.get(connectionId);
+
+        if (!perConnection) {
+            perConnection = new Map<string, boolean>();
+            this.authorized.set(connectionId, perConnection);
+        }
+
+        const cached = perConnection.get(instanceId);
+
+        if (cached !== undefined) {
+            return cached;
+        }
+
+        let allowed: boolean;
+
+        try {
+            allowed = await this.authorizer.authorize({
+                resourceId: resource.id,
+                controllerName: resource.controllerName,
+                handlerName: resource.handlerName,
+                meta: resource.meta,
+                inputs,
+                scope,
+                connectionId
+            });
+        } catch {
+            // An authorizer that throws is a denial. Failing open here would
+            // hand out data on a bug in application code.
+            allowed = false;
+        }
+
+        perConnection.set(instanceId, allowed);
+        return allowed;
+    }
+
+    /** An `auth:` key fired: drop the cached decisions it covers and re-ask. */
+    private reauthorize(key: DepKey): void {
+        for (const [connectionId, scope] of this.scopes) {
+            const affected = authKeysOf(scope).some(owned => ancestorsOf(owned).includes(key));
+
+            if (!affected) {
+                continue;
+            }
+
+            this.authorized.delete(connectionId);
+
+            const owned = this.bindings.get(connectionId);
+
+            if (!owned) {
+                continue;
+            }
+
+            for (const instanceId of new Set(owned.values())) {
+                const instance = this.instances.get(instanceId);
+
+                if (!instance) {
+                    continue;
+                }
+
+                void this.checkAuthorization(connectionId, instanceId, instance.resource, instance.inputs, scope)
+                    .then(allowed => {
+                        if (!allowed) {
+                            this.revoke(connectionId, instanceId);
+                        }
+                    });
+            }
+        }
+    }
+
+    /** End one connection's hold on one instance, telling it why. */
+    private revoke(connectionId: string, instanceId: string): void {
+        for (const sid of this.sidsFor(connectionId, instanceId)) {
+            this.send(connectionId, {
+                t: 'error',
+                sid,
+                code: 'forbidden',
+                message: 'This subscription is no longer authorized for this connection.'
+            });
+            this.release(connectionId, sid);
+        }
+    }
+
+    private scheduleDrop(instanceId: string): void {
+        if (this.subs.hasSubscribers(instanceId)) {
+            return;
+        }
+
+        const instance = this.instances.get(instanceId);
+
+        if (!instance || instance.dropTimer) {
+            return;
+        }
+
+        // Grace period so coming back from a navigation does not recompute
+        // everything the page had a moment ago.
+        instance.dropTimer = setTimeout(() => {
+            if (!this.subs.hasSubscribers(instanceId)) {
+                this.instances.delete(instanceId);
+                this.graph.remove(instanceId);
+            }
+        }, this.config.unsubGraceMs);
+    }
+
+    private startInstanceCreation(
+        instanceId: string,
+        resource: LiveResource,
+        inputs: LiveInputs,
+        scope: LiveScope
+    ): Promise<LiveInstance> {
+        let resolveCreation!: (instance: LiveInstance) => void;
+        let rejectCreation!: (error: unknown) => void;
+        const creation = new Promise<LiveInstance>((resolve, reject) => {
+            resolveCreation = resolve;
+            rejectCreation = reject;
+        });
+
+        this.creating.set(instanceId, creation);
+
+        void this.createInstance(instanceId, resource, inputs, scope).then(
+            instance => {
+                this.clearInstanceCreation(instanceId, creation);
+                resolveCreation(instance);
+            },
+            error => {
+                this.clearInstanceCreation(instanceId, creation);
+                rejectCreation(error);
+            }
+        );
+
+        return creation;
+    }
+
+    private clearInstanceCreation(instanceId: string, creation: Promise<LiveInstance>): void {
+        if (this.creating.get(instanceId) === creation) {
+            this.creating.delete(instanceId);
+        }
+    }
+
+    private async createInstance(
+        instanceId: string,
+        resource: LiveResource,
+        inputs: LiveInputs,
+        scope: LiveScope
+    ): Promise<LiveInstance> {
+        // The same permit as a recompute: a burst of first subscriptions is
+        // as many queries as a fan-out is, and hits the same pool.
+        await this.acquirePermit();
+
+        let data: unknown;
+        let deps;
+
+        try {
+            ({ data, deps } = await this.resources.compute(resource, inputs, { scope }));
+        } finally {
+            this.releasePermit();
+        }
+
+        this.recomputes++;
+        this.graph.setDependencies(instanceId, deps);
+
+        const instance: LiveInstance = {
+            id: instanceId,
+            resource,
+            inputs,
+            scope,
+            patcher: new PatchEngine(resource.meta.key),
+            data,
+            hash: fnv1a64(canonical(data)),
+            revision: 1,
+            computing: null,
+            dirty: false,
+            dropTimer: null
+        };
+
+        this.instances.set(instanceId, instance);
+        return instance;
+    }
+
+    private sendState(
+        connectionId: string,
+        sid: string,
+        instance: LiveInstance,
+        clientHash?: string
+    ): void {
+        if (clientHash && clientHash === instance.hash) {
+            // The screen already holds this exact content. Nothing on the wire.
+            this.send(connectionId, {
+                t: 'current',
+                sid,
+                rev: instance.revision,
+                hash: instance.hash,
+                key: instance.resource.meta.key
+            });
+            return;
+        }
+
+        this.send(connectionId, {
+            t: 'snapshot',
+            sid,
+            rev: instance.revision,
+            hash: instance.hash,
+            data: instance.data,
+            key: instance.resource.meta.key
+        });
+    }
+
+    private onInvalidation(events: InvalidationEvent[]): void {
+        const before = this.pending.size;
+
+        for (const event of events) {
+            if (isAuthKey(event.key)) {
+                // Not data: nothing to recompute, only permissions to re-check.
+                this.reauthorize(event.key);
+                continue;
+            }
+
+            for (const instanceId of this.graph.resolve(event)) {
+                // Grace-held instances have no subscribers but are still cached.
+                if (this.instances.has(instanceId)) {
+                    this.pending.add(instanceId);
+                }
+            }
+        }
+
+        // Newly pending, not total pending: an invalidation that woke nothing
+        // because the instances were already queued did not cost a fan-out.
+        this.metrics.invalidation(events.length, this.pending.size - before);
+
+        if (this.pending.size === 0 || this.flushTimer) {
+            return;
+        }
+
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            void this.flush();
+        }, this.config.coalesceMs);
+    }
+
+    private async flush(): Promise<void> {
+        const batch = [...this.pending];
+        this.pending.clear();
+
+        this.metrics.instances(this.instances.size);
+
+        // A bounded pool, not `Promise.all` over a slice of five hundred. The
+        // permits taken in `runCompute` are what cap the queries; this is what
+        // keeps a fan-out of fifty thousand from materializing fifty thousand
+        // pending promises just to hold them.
+        const workers = Math.min(Math.max(1, this.config.maxConcurrentRecomputes), batch.length);
+        const yieldEvery = Math.max(1, this.config.fanoutQueueThreshold);
+        let next = 0;
+        let finished = 0;
+
+        const run = async (): Promise<void> => {
+            while (next < batch.length) {
+                await this.recompute(batch[next++]!);
+                finished++;
+
+                if (finished % yieldEvery === 0) {
+                    // Yield so a large fan-out does not monopolize the loop
+                    // and stall unrelated requests.
+                    await new Promise(resolve => setTimeout(resolve, 0));
+                }
+            }
+        };
+
+        await Promise.all(Array.from({ length: workers }, () => run()));
+    }
+
+    /** A permit to run one compute, now or when one frees up. */
+    private acquirePermit(): Promise<void> {
+        if (this.inFlight < Math.max(1, this.config.maxConcurrentRecomputes)) {
+            this.inFlight++;
+            return Promise.resolve();
+        }
+
+        return new Promise<void>(resolve => this.waiting.push(resolve));
+    }
+
+    /** Hand the permit straight to the next waiter, so the count never dips. */
+    private releasePermit(): void {
+        const next = this.waiting.shift();
+
+        if (next) {
+            next();
+            return;
+        }
+
+        this.inFlight--;
+    }
+
+    private recompute(instanceId: string): Promise<void> {
+        const instance = this.instances.get(instanceId);
+
+        if (!instance) {
+            return Promise.resolve();
+        }
+
+        if (instance.computing) {
+            // Single-flight: N invalidations arriving during one recompute cost
+            // exactly one more recompute, not N.
+            instance.dirty = true;
+            return instance.computing;
+        }
+
+        instance.computing = this.runCompute(instance).finally(() => {
+            instance.computing = null;
+
+            if (instance.dirty) {
+                instance.dirty = false;
+                void this.recompute(instanceId);
+            }
+        });
+
+        return instance.computing;
+    }
+
+    private async runCompute(instance: LiveInstance): Promise<void> {
+        // Taken before the clock starts, so `live.recompute.ms` keeps meaning
+        // the compute rather than the wait for a free connection.
+        await this.acquirePermit();
+
+        const startedAt = performance.now();
+        let data: unknown;
+        let deps;
+
+        try {
+            ({ data, deps } = await this.resources.compute(
+                instance.resource,
+                instance.inputs,
+                { scope: instance.scope }
+            ));
+        } catch (error) {
+            if (isLiveAuthorizationFailure(error)) {
+                this.revokeInstance(instance.id);
+                return;
+            }
+
+            await this.broadcast(instance, sid => ({ t: 'stale', sid, reason: (error as Error).message }));
+            return;
+        } finally {
+            // Only the compute is held: the hash, the diff and the fan-out
+            // below need no connection.
+            this.releasePermit();
+        }
+
+        this.recomputes++;
+        this.graph.setDependencies(instance.id, deps);
+
+        const hash = fnv1a64(canonical(data));
+
+        if (hash === instance.hash) {
+            // Recompute is not a patch. Coarse invalidation costs CPU, never
+            // traffic and never a re-render. This is the number of §10.
+            this.recomputesWithoutPatch++;
+            this.metrics.recompute(instance.resource.id, false, 0, performance.now() - startedAt);
+            return;
+        }
+
+        const ops = instance.patcher.diff(instance.data, data);
+        const from = instance.revision;
+
+        instance.data = data;
+        instance.hash = hash;
+        instance.revision += 1;
+
+        this.metrics.recompute(instance.resource.id, true, ops.length, performance.now() - startedAt);
+
+        await this.broadcast(instance, sid => ({
+            t: 'patch',
+            sid,
+            from,
+            to: instance.revision,
+            hash,
+            ops
+        }));
+    }
+
+    private async broadcast(
+        instance: LiveInstance,
+        build: (sid: string) => ServerMessage
+    ): Promise<void> {
+        for (const connectionId of [...this.subs.connectionsOf(instance.id)]) {
+            const scope = this.scopes.get(connectionId);
+            const allowed = scope
+                ? await this.checkAuthorization(connectionId, instance.id, instance.resource, instance.inputs, scope)
+                : false;
+
+            if (!allowed) {
+                this.revoke(connectionId, instance.id);
+                continue;
+            }
+
+            for (const sid of this.sidsFor(connectionId, instance.id)) {
+                const message = build(sid);
+
+                if (message.t === 'patch' && this.isBackedUp(connectionId)) {
+                    // The client is behind. Collapse instead of queueing more.
+                    this.send(connectionId, {
+                        t: 'snapshot',
+                        sid,
+                        rev: instance.revision,
+                        hash: instance.hash,
+                        data: instance.data,
+                        key: instance.resource.meta.key
+                    });
+                    this.backpressure.set(connectionId, 0);
+                    continue;
+                }
+
+                this.send(connectionId, message);
+            }
+        }
+    }
+
+    private revokeInstance(instanceId: string): void {
+        const connections = new Set(this.subs.connectionsOf(instanceId));
+
+        for (const connectionId of connections) {
+            this.revoke(connectionId, instanceId);
+        }
+    }
+
+    private sidsFor(connectionId: string, instanceId: string): string[] {
+        const owned = this.bindings.get(connectionId);
+
+        if (!owned) {
+            return [];
+        }
+
+        const sids: string[] = [];
+
+        for (const [sid, boundInstance] of owned) {
+            if (boundInstance === instanceId) {
+                sids.push(sid);
+            }
+        }
+
+        return sids;
+    }
+
+    private isBackedUp(connectionId: string): boolean {
+        return (this.backpressure.get(connectionId) ?? 0) >= this.config.maxPendingPatches;
+    }
+
+    private send(connectionId: string, message: ServerMessage): void {
+        const result = this.transport.send(connectionId, message);
+        const current = this.backpressure.get(connectionId) ?? 0;
+
+        this.backpressure.set(connectionId, result > 0 ? 0 : current + 1);
+    }
+
+    private fail(connectionId: string, sid: string, code: string, message: string): void {
+        this.send(connectionId, { t: 'error', sid, code, message });
+    }
+}