@carno.js/live 1.8.0 → 1.8.1

package/dist/LiveEngine.d.ts

@@ -45,6 +45,16 @@ export declare class LiveEngine {
     private readonly scopes;
     /** connectionId → instanceId → decision. Cleared when an `auth:` key fires. */
     private readonly authorized;
+    /**
+     * 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;
+    private readonly waiting;
     private flushTimer;
     private unsubscribeBus;
     private recomputes;
@@ -78,6 +88,10 @@ export declare class LiveEngine {
     private sendState;
     private onInvalidation;
     private flush;
+    /** A permit to run one compute, now or when one frees up. */
+    private acquirePermit;
+    /** Hand the permit straight to the next waiter, so the count never dips. */
+    private releasePermit;
     private recompute;
     private runCompute;
     private broadcast;

package/dist/LiveEngine.js

@@ -30,6 +30,16 @@ class LiveEngine {
         this.scopes = new Map();
         /** connectionId → instanceId → decision. Cleared when an `auth:` key fires. */
         this.authorized = new Map();
+        /**
+         * 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.
+         */
+        this.inFlight = 0;
+        this.waiting = [];
         this.flushTimer = null;
         this.unsubscribeBus = null;
         this.recomputes = 0;
@@ -53,6 +63,15 @@ class LiveEngine {
                 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, sid, resourceId, inputs, scope, clientHash) {
         const resource = this.resources.get(resourceId);
@@ -317,7 +336,17 @@ class LiveEngine {
         }
     }
     async createInstance(instanceId, resource, inputs, scope) {
-        const { data, deps } = await this.resources.compute(resource, inputs, { scope });
+        // 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;
+        let deps;
+        try {
+            ({ data, deps } = await this.resources.compute(resource, inputs, { scope }));
+        }
+        finally {
+            this.releasePermit();
+        }
         this.recomputes++;
         this.graph.setDependencies(instanceId, deps);
         const instance = {
@@ -387,15 +416,43 @@ class LiveEngine {
         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));
+        // 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 () => {
+            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. */
+    acquirePermit() {
+        if (this.inFlight < Math.max(1, this.config.maxConcurrentRecomputes)) {
+            this.inFlight++;
+            return Promise.resolve();
         }
+        return new Promise(resolve => this.waiting.push(resolve));
+    }
+    /** Hand the permit straight to the next waiter, so the count never dips. */
+    releasePermit() {
+        const next = this.waiting.shift();
+        if (next) {
+            next();
+            return;
+        }
+        this.inFlight--;
     }
     recompute(instanceId) {
         const instance = this.instances.get(instanceId);
@@ -418,6 +475,9 @@ class LiveEngine {
         return instance.computing;
     }
     async runCompute(instance) {
+        // 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;
         let deps;
@@ -432,6 +492,11 @@ class LiveEngine {
             await this.broadcast(instance, sid => ({ t: 'stale', sid, reason: 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 = (0, hash_1.fnv1a64)((0, canonical_1.canonical)(data));

package/dist/LivePlugin.d.ts

@@ -13,6 +13,15 @@ export interface LivePluginOptions {
      * builder, so a second plugin silently wins and orphans the first.
      */
     gateways?: (new (...args: any[]) => any)[];
+    /**
+     * Turns a handshake into the principal and tenant that key an instance.
+     *
+     * Left out, the default `ConnectionScopeResolver` makes the connection id
+     * the principal, so every `private` resource gets one instance per
+     * connection and the boot logs say so. Passing
+     * `new ConnectionScopeResolver()` explicitly is how an application states
+     * that per-connection instances are what it wants, and silences that.
+     */
     scopeResolver?: LiveScopeResolver;
     /**
      * Decides whether a connection may hold a subscription, and is re-asked

package/dist/LivePlugin.js

@@ -26,6 +26,7 @@ const SocketTransport_1 = require("./transport/SocketTransport");
 const SseTransport_1 = require("./transport/SseTransport");
 const sse_routes_1 = require("./transport/sse-routes");
 const protocol_1 = require("./shared/protocol");
+const scope_warning_1 = require("./scope-warning");
 class LivePlugin {
     static create(options) {
         const config = (0, config_1.resolveLiveConfig)(options.config);
@@ -122,6 +123,17 @@ class LivePlugin {
                 resources.register(ControllerClass, container.get(ControllerClass), routeExecutor);
             }
             teachEtag?.(resources.livePaths());
+            // Both halves of the per-connection trap are known only here: the
+            // resolver comes from the options, the resources from the scan the
+            // loop above just finished.
+            const scopeWarning = (0, scope_warning_1.defaultScopeWarning)({
+                privateResourceIds: resources.idsShared('private'),
+                usingDefaultResolver: options.scopeResolver === undefined,
+                maxInstancesPerNode: config.maxInstancesPerNode
+            });
+            if (scopeWarning) {
+                console.warn(scopeWarning);
+            }
             if (options.pgNotify) {
                 const driver = orm_1.Orm.getInstance().driverInstance;
                 const deliver = (events) => {

package/dist/config.d.ts

@@ -13,8 +13,19 @@ export interface LiveConfig {
     unsubGraceMs: number;
     /** Consecutive back-pressured sends before collapsing to a snapshot. */
     maxPendingPatches: number;
-    /** Above this fan-out, recompute is queued instead of run inline. */
+    /** Recomputes finished in one run before the loop is yielded back. */
     fanoutQueueThreshold: number;
+    /**
+     * Recomputes allowed to run at once, across every path.
+     *
+     * Each one executes the resource's route, and so its queries. Raising it
+     * past the database pool buys no parallelism -- the driver queues the
+     * excess either way -- it only puts live queries in front of the ordinary
+     * HTTP requests competing for the same connections. The default sits well
+     * under Bun's pool default of 10; raise it with the pool, not with the
+     * fan-out.
+     */
+    maxConcurrentRecomputes: number;
     /** Ceiling on live instances held by a single connection. */
     maxInstancesPerConnection: number;
     /** Ceiling on live instances held by this process. */

package/dist/config.js

@@ -9,6 +9,7 @@ exports.DEFAULT_LIVE_CONFIG = {
     unsubGraceMs: 5000,
     maxPendingPatches: 32,
     fanoutQueueThreshold: 500,
+    maxConcurrentRecomputes: 4,
     maxInstancesPerConnection: 64,
     maxInstancesPerNode: 50000,
     ssePath: '/live/sse',

package/dist/graph/DependencyGraph.d.ts

@@ -9,6 +9,18 @@ import type { Dependency, InvalidationEvent } from './types';
 export declare class DependencyGraph {
     private readonly byKey;
     private readonly byInstance;
+    /**
+     * Registered row keys grouped by the key that contains them, so a write
+     * that names a whole table finds its rows instead of being searched for.
+     *
+     * Without it, resolving a table event means walking every key in the
+     * graph: at the configured `maxInstancesPerNode` that is a five-millisecond
+     * scan, run synchronously once per event of the batch, with every HTTP
+     * request in the process waiting behind it. Table events are not the rare
+     * case either -- a write degrades to its table key unless its WHERE clause
+     * is a literal primary-key match.
+     */
+    private readonly byParent;
     /** Replace every dependency held by this instance. */
     setDependencies(instanceId: string, deps: Dependency[]): void;
     /** Forget the instance entirely. */
@@ -23,5 +35,18 @@ export declare class DependencyGraph {
     resolve(event: InvalidationEvent): string[];
     keyCount(): number;
     instanceCount(): number;
+    /** Keys that currently hold indexed rows. Zero when the graph is empty. */
+    parentCount(): number;
+    /**
+     * Record a row key's holders under the key that contains it.
+     *
+     * A table key has no separator and so no parent; it is reached directly.
+     * The holder map is stored rather than the key because it is what
+     * `resolve` actually needs, and because its identity is stable: it is
+     * created once in `setDependencies` and dropped only in `remove`.
+     */
+    private index;
+    private unindex;
     private collect;
+    private collectFrom;
 }

package/dist/graph/DependencyGraph.js

@@ -13,6 +13,18 @@ class DependencyGraph {
     constructor() {
         this.byKey = new Map();
         this.byInstance = new Map();
+        /**
+         * Registered row keys grouped by the key that contains them, so a write
+         * that names a whole table finds its rows instead of being searched for.
+         *
+         * Without it, resolving a table event means walking every key in the
+         * graph: at the configured `maxInstancesPerNode` that is a five-millisecond
+         * scan, run synchronously once per event of the batch, with every HTTP
+         * request in the process waiting behind it. Table events are not the rare
+         * case either -- a write degrades to its table key unless its WHERE clause
+         * is a literal primary-key match.
+         */
+        this.byParent = new Map();
     }
     /** Replace every dependency held by this instance. */
     setDependencies(instanceId, deps) {
@@ -27,6 +39,7 @@ class DependencyGraph {
             if (!holders) {
                 holders = new Map();
                 this.byKey.set(dep.key, holders);
+                this.index(dep.key, holders);
             }
             if (!holders.has(instanceId)) {
                 holders.set(instanceId, dep.columns === null ? null : new Set(dep.columns));
@@ -60,6 +73,7 @@ class DependencyGraph {
             holders.delete(instanceId);
             if (holders.size === 0) {
                 this.byKey.delete(key);
+                this.unindex(key, holders);
             }
         }
         this.byInstance.delete(instanceId);
@@ -76,11 +90,14 @@ class DependencyGraph {
         for (const key of (0, dep_key_1.ancestorsOf)(event.key)) {
             this.collect(key, event.columns, matched);
         }
-        const descendantPrefix = `${event.key}#`;
+        // A key with a `#` is already a row: it has no descendants, and the
+        // ancestor pass above has covered its table.
         if (!event.key.includes('#')) {
-            for (const key of this.byKey.keys()) {
-                if (key.startsWith(descendantPrefix)) {
-                    this.collect(key, event.columns, matched);
+            const rows = this.byParent.get(event.key);
+            if (rows) {
+                // Holder maps, not keys: the key would only be looked up again.
+                for (const holders of rows) {
+                    this.collectFrom(holders, event.columns, matched);
                 }
             }
         }
@@ -92,11 +109,53 @@ class DependencyGraph {
     instanceCount() {
         return this.byInstance.size;
     }
+    /** Keys that currently hold indexed rows. Zero when the graph is empty. */
+    parentCount() {
+        return this.byParent.size;
+    }
+    /**
+     * Record a row key's holders under the key that contains it.
+     *
+     * A table key has no separator and so no parent; it is reached directly.
+     * The holder map is stored rather than the key because it is what
+     * `resolve` actually needs, and because its identity is stable: it is
+     * created once in `setDependencies` and dropped only in `remove`.
+     */
+    index(key, holders) {
+        const separator = key.indexOf('#');
+        if (separator === -1) {
+            return;
+        }
+        const parent = key.slice(0, separator);
+        let rows = this.byParent.get(parent);
+        if (!rows) {
+            rows = new Set();
+            this.byParent.set(parent, rows);
+        }
+        rows.add(holders);
+    }
+    unindex(key, holders) {
+        const separator = key.indexOf('#');
+        if (separator === -1) {
+            return;
+        }
+        const parent = key.slice(0, separator);
+        const rows = this.byParent.get(parent);
+        if (!rows) {
+            return;
+        }
+        rows.delete(holders);
+        if (rows.size === 0) {
+            this.byParent.delete(parent);
+        }
+    }
     collect(key, writtenColumns, into) {
         const holders = this.byKey.get(key);
-        if (!holders) {
-            return;
+        if (holders) {
+            this.collectFrom(holders, writtenColumns, into);
         }
+    }
+    collectFrom(holders, writtenColumns, into) {
         for (const [instanceId, readColumns] of holders) {
             if (intersects(readColumns, writtenColumns)) {
                 into.add(instanceId);

package/dist/index.d.ts

@@ -15,6 +15,8 @@ export type { LiveConfig } from './config';
 export { ConnectionScopeResolver } from './transport/scope-resolver';
 export type { LiveHandshake, LiveScopeResolver } from './transport/scope-resolver';
 export type { LiveExecutionContext, LiveInputs, LiveResourceExecutor, LiveScope } from './resource/types';
+export { defaultScopeWarning } from './scope-warning';
+export type { DefaultScopeWarningInput } from './scope-warning';
 export { AllowAllAuthorizer, authKeysOf, isAuthKey } from './auth/authorizer';
 export type { LiveAuthorizationRequest, LiveAuthorizer } from './auth/authorizer';
 export { InProcessBus } from './bus/InProcessBus';

package/dist/index.js

@@ -14,7 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HYDRATION_ATTRIBUTE = exports.readHydrationPayload = exports.toHydrateMap = exports.hydrationKey = exports.LiveRouteExecutionError = exports.prefetchLive = exports.pathMatcher = exports.LiveETagMiddleware = exports.createSseRoutes = exports.SseTransport = exports.FanTransport = exports.routeIndex = exports.SseClientTransport = exports.PollingTransport = exports.LadderTransport = exports.WebSocketTransport = exports.LiveSlot = exports.liveIdentity = exports.liveStoreOf = exports.liveStore = exports.resourceIdOf = exports.normalizeLiveInputs = exports.fnv1a64 = exports.NonSerializableInputError = exports.canonical = exports.PatchEngine = exports.tableOfKey = exports.PgListener = exports.eventsFromPayload = exports.PgNotifyEmitter = exports.chunkEvents = exports.PgNotifyBus = exports.WriteDuringComputeError = exports.tableKey = exports.rowKey = exports.ancestorsOf = exports.InProcessBus = exports.isAuthKey = exports.authKeysOf = exports.AllowAllAuthorizer = exports.ConnectionScopeResolver = exports.resolveLiveConfig = exports.DEFAULT_LIVE_CONFIG = exports.LiveMetrics = exports.LiveEngine = exports.LiveService = exports.closeLiveRuntime = exports.LivePlugin = exports.LIVE_META = exports.Live = void 0;
+exports.readHydrationPayload = exports.toHydrateMap = exports.hydrationKey = exports.LiveRouteExecutionError = exports.prefetchLive = exports.pathMatcher = exports.LiveETagMiddleware = exports.createSseRoutes = exports.SseTransport = exports.FanTransport = exports.routeIndex = exports.SseClientTransport = exports.PollingTransport = exports.LadderTransport = exports.WebSocketTransport = exports.LiveSlot = exports.liveIdentity = exports.liveStoreOf = exports.liveStore = exports.resourceIdOf = exports.normalizeLiveInputs = exports.fnv1a64 = exports.NonSerializableInputError = exports.canonical = exports.PatchEngine = exports.tableOfKey = exports.PgListener = exports.eventsFromPayload = exports.PgNotifyEmitter = exports.chunkEvents = exports.PgNotifyBus = exports.WriteDuringComputeError = exports.tableKey = exports.rowKey = exports.ancestorsOf = exports.InProcessBus = exports.isAuthKey = exports.authKeysOf = exports.AllowAllAuthorizer = exports.defaultScopeWarning = exports.ConnectionScopeResolver = exports.resolveLiveConfig = exports.DEFAULT_LIVE_CONFIG = exports.LiveMetrics = exports.LiveEngine = exports.LiveService = exports.closeLiveRuntime = exports.LivePlugin = exports.LIVE_META = exports.Live = void 0;
+exports.HYDRATION_ATTRIBUTE = void 0;
 require("reflect-metadata");
 // Decorator and metadata
 var Live_1 = require("./decorators/Live");
@@ -40,6 +41,8 @@ Object.defineProperty(exports, "resolveLiveConfig", { enumerable: true, get: fun
 // Scope
 var scope_resolver_1 = require("./transport/scope-resolver");
 Object.defineProperty(exports, "ConnectionScopeResolver", { enumerable: true, get: function () { return scope_resolver_1.ConnectionScopeResolver; } });
+var scope_warning_1 = require("./scope-warning");
+Object.defineProperty(exports, "defaultScopeWarning", { enumerable: true, get: function () { return scope_warning_1.defaultScopeWarning; } });
 // Authorization
 var authorizer_1 = require("./auth/authorizer");
 Object.defineProperty(exports, "AllowAllAuthorizer", { enumerable: true, get: function () { return authorizer_1.AllowAllAuthorizer; } });

package/dist/resource/ResourceRegistry.d.ts

@@ -1,5 +1,6 @@
 import 'reflect-metadata';
 import type { Dependency } from '../graph/types';
+import { type LiveShared } from '../metadata';
 import type { LiveExecutionContext, LiveInputs, LiveResource, LiveResourceExecutor } from './types';
 export declare class LiveValidationError extends Error {
     constructor(message: string);
@@ -16,6 +17,8 @@ export declare class ResourceRegistry {
     register(ControllerClass: new (...args: any[]) => any, instance: any, executor: LiveResourceExecutor): void;
     get(id: string): LiveResource | undefined;
     ids(): string[];
+    /** Ids declared with this sharing mode, in registration order. */
+    idsShared(shared: LiveShared): string[];
     /** Every live route, as the HTTP layer addresses it. */
     livePaths(): {
         method: string;

package/dist/resource/ResourceRegistry.js

@@ -99,6 +99,12 @@ class ResourceRegistry {
     ids() {
         return [...this.resources.keys()];
     }
+    /** Ids declared with this sharing mode, in registration order. */
+    idsShared(shared) {
+        return [...this.resources.values()]
+            .filter(resource => resource.meta.shared === shared)
+            .map(resource => resource.id);
+    }
     /** Every live route, as the HTTP layer addresses it. */
     livePaths() {
         return [...this.resources.values()].map(resource => ({

package/dist/scope-warning.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The one trap the default configuration sets, reported at boot.
+ *
+ * `@Live()` defaults to `shared: 'private'` and `ConnectionScopeResolver`
+ * makes the connection id the principal, so with neither configured the
+ * instance identity carries a connection id: two tabs of one user are two
+ * instances, and N viewers of the same data are N computes, N diffs and N
+ * queries. That is the safe default — nothing can leak between connections —
+ * but it scales in connections rather than in data, and it is silent.
+ *
+ * Both halves are known at bootstrap, so this is a fact rather than a
+ * heuristic: no sampling of a live instance rate is needed to state it.
+ */
+export interface DefaultScopeWarningInput {
+    /** Ids of the resources that resolved to `shared: 'private'`. */
+    privateResourceIds: string[];
+    /** False as soon as the application passes any resolver of its own. */
+    usingDefaultResolver: boolean;
+    /** `LiveConfig.maxInstancesPerNode`, the ceiling this default runs into. */
+    maxInstancesPerNode: number;
+}
+/**
+ * The warning text, or null when there is nothing to warn about.
+ *
+ * Returned rather than printed so the decision is testable without capturing
+ * the console.
+ */
+export declare function defaultScopeWarning(input: DefaultScopeWarningInput): string | null;

package/dist/scope-warning.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * The one trap the default configuration sets, reported at boot.
+ *
+ * `@Live()` defaults to `shared: 'private'` and `ConnectionScopeResolver`
+ * makes the connection id the principal, so with neither configured the
+ * instance identity carries a connection id: two tabs of one user are two
+ * instances, and N viewers of the same data are N computes, N diffs and N
+ * queries. That is the safe default — nothing can leak between connections —
+ * but it scales in connections rather than in data, and it is silent.
+ *
+ * Both halves are known at bootstrap, so this is a fact rather than a
+ * heuristic: no sampling of a live instance rate is needed to state it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultScopeWarning = defaultScopeWarning;
+/** Resource ids listed inline before the message collapses to a count. */
+const MAX_LISTED = 8;
+/**
+ * The warning text, or null when there is nothing to warn about.
+ *
+ * Returned rather than printed so the decision is testable without capturing
+ * the console.
+ */
+function defaultScopeWarning(input) {
+    if (!input.usingDefaultResolver || input.privateResourceIds.length === 0) {
+        return null;
+    }
+    const count = input.privateResourceIds.length;
+    const listed = input.privateResourceIds.slice(0, MAX_LISTED).join(', ');
+    const rest = count - Math.min(count, MAX_LISTED);
+    const names = rest > 0 ? `${listed} and ${rest} more` : listed;
+    const noun = count === 1 ? 'live resource is' : 'live resources are';
+    return [
+        '[carno:live] No `scopeResolver` was passed to LivePlugin.create(), so the default',
+        'ConnectionScopeResolver keys every instance by connection id.',
+        `  ${count} ${noun} private (the @Live() default) and will get one instance per`,
+        '  connection rather than one per user:',
+        `    ${names}`,
+        '  Two tabs of the same user are two instances, and N viewers of the same data are N',
+        `  computes, N diffs and N queries — against the ceiling of ${input.maxInstancesPerNode} instances per node`,
+        '  (LiveConfig.maxInstancesPerNode), past which subscriptions are refused.',
+        '  Fix: pass a `scopeResolver` whose principal is a user id, or declare the resources',
+        '  that are genuinely shared as @Live({ shared: \'public\' }) or @Live({ shared: \'tenant\' }).',
+        '  To keep per-connection instances and silence this, pass',
+        '  `scopeResolver: new ConnectionScopeResolver()` explicitly.'
+    ].join('\n');
+}

package/dist/shared/canonical.d.ts

@@ -5,6 +5,30 @@
  * the instance id and the content hash are derived from it, so a divergence
  * silently breaks subscription dedupe and the hydration handshake instead of
  * failing loudly.
+ *
+ * It also runs on every recompute, over the whole payload, which makes it the
+ * most expensive step of a recompute that changes nothing. Building the string
+ * in JavaScript loses to `JSON.stringify` by roughly an order of magnitude, so
+ * the common case does not build it: one walk normalizes the value into the
+ * shape `JSON.stringify` would already render canonically -- keys sorted,
+ * nothing unserializable left in it -- and the native serializer does the rest.
+ *
+ * What that walk has to do, and `JSON.stringify` cannot:
+ *
+ * - order object keys, which is the whole point;
+ * - refuse values with no agreed wire form, which `JSON.stringify` accepts
+ *   silently (a Date becomes a string, a Map becomes `{}`, a NaN becomes null).
+ *
+ * What it deliberately leaves to `JSON.stringify`, which already agrees:
+ * string escaping, number formatting including negative zero, dropping
+ * undefined properties, and rendering an array hole as null.
+ *
+ * The escape hatch is `writeCanonical` below. A JavaScript object cannot hold
+ * an integer-like key anywhere but the front -- `{ '': 1, '1': 2 }` always
+ * enumerates as `1` then `''` -- so an object carrying one cannot be emitted
+ * in lexicographic order at all. Those values fall back to building the string
+ * here, where the order is ours to choose. Both paths are held to the same
+ * output by the differential test.
  */
 export declare class NonSerializableInputError extends Error {
     readonly path: string;