statewire 0.23.0 → 0.24.1

package/src/client/sessionStore.ts

@@ -12,6 +12,7 @@ export const SessionStorageContext = createContext<
 export const createMemorySessionStore = (): StatewireClient.SessionStorage => {
   let record: StatewireClient.SessionRecord | null = null;
   return {
+    durable: false,
     load: () => record,
     save: (next) => {
       record = next;
@@ -28,6 +29,7 @@ export const LinkContext = createContext<{
   canOvertake?:
     | Readonly<Record<string, StatewireClient.CanOvertake>>
     | undefined;
+  onSettled?: StatewireClient.OnSettled | undefined;
 }>({});
 
 export const DocumentStorageContext = createContext<

package/src/host/host.ts

@@ -151,7 +151,9 @@ export type CommandsInvocation = {
   readonly id?: string;
   readonly clientId?: string;
   /** Present while the queued command is held. */
-  readonly hold?: { meta?: unknown };
+  readonly held?: true;
+  /** Client-only data persisted with an outbox entry. */
+  readonly localMeta?: unknown;
 };
 
 export type CommandsOutcome =
@@ -161,12 +163,17 @@ export type CommandsOutcome =
 export type CommandsListener = {
   onStart: (inv: CommandsInvocation) => void;
   onPosted?: (inv: CommandsInvocation) => void;
-  /** The invocation's seq or hold changed in place. */
+  /** The invocation's seq, hold or local meta changed in place. */
   onChange?: (inv: CommandsInvocation) => void;
   onApplied: (inv: CommandsInvocation) => void;
   /** Canonical state now covers the invocation's effect — drop any overlay. */
   onCovered?: (inv: CommandsInvocation) => void;
-  onSettle: (inv: CommandsInvocation, outcome: CommandsOutcome) => void;
+  /** `durable`: the session persisted the settled update and delivers it itself. */
+  onSettle: (
+    inv: CommandsInvocation,
+    outcome: CommandsOutcome,
+    durable?: boolean,
+  ) => void;
 };
 
 export type CommandsSubmission = {

package/src/indexedDb.ts

@@ -0,0 +1,167 @@
+import { useEffect, useMemo, useState } from "react";
+import { resource, useResource } from "@assistant-ui/tap";
+import { KeyValueSessionStorage } from "./storage";
+import type { StatewireClient } from "./statewire";
+import { randomId } from "./util/randomId";
+
+const STORE = "sessions";
+
+const request = <T>(req: IDBRequest<T>) =>
+  new Promise<T>((resolve, reject) => {
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+
+const backends = new Map<string, KeyValueSessionStorage.Backend>();
+
+/** A key-value backend over one IndexedDB database; writes broadcast to other runtimes. */
+export const indexedDbBackend = (
+  database: string,
+): KeyValueSessionStorage.Backend => {
+  const existing = backends.get(database);
+  if (existing) return existing;
+  if (typeof indexedDB === "undefined")
+    throw new Error("statewire: IndexedDbSession requires indexedDB");
+  let opened: Promise<IDBDatabase> | undefined;
+  const db = () =>
+    (opened ??= (() => {
+      const open = indexedDB.open(database, 1);
+      open.onupgradeneeded = () => open.result.createObjectStore(STORE);
+      return request(open);
+    })());
+  // Writes resolve once their transaction commits.
+  const run = async <T>(
+    mode: IDBTransactionMode,
+    fn: (store: IDBObjectStore) => IDBRequest<T>,
+  ) => {
+    const tx = (await db()).transaction(STORE, mode);
+    const committed =
+      mode === "readonly"
+        ? undefined
+        : new Promise<void>((resolve, reject) => {
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+            tx.onabort = () => reject(tx.error);
+          });
+    const result = await request(fn(tx.objectStore(STORE)));
+    await committed;
+    return result;
+  };
+  const channel = new BroadcastChannel(`statewire-idb:${database}`);
+  const announce = (key: string) => channel.postMessage(key);
+  const backend: KeyValueSessionStorage.Backend = {
+    getItem: async (key) =>
+      ((await run("readonly", (s) => s.get(key))) as string | undefined) ??
+      null,
+    setItem: async (key, value) => {
+      await run("readwrite", (s) => s.put(value, key));
+      announce(key);
+    },
+    removeItem: async (key) => {
+      await run("readwrite", (s) => s.delete(key));
+      announce(key);
+    },
+    getAllKeys: async () =>
+      (await run("readonly", (s) => s.getAllKeys())) as string[],
+    withUnused: (key, action) =>
+      navigator.locks.request(
+        `statewire-active:${database}:${key}`,
+        { ifAvailable: true },
+        (lock) =>
+          lock === null
+            ? undefined
+            : navigator.locks.request(
+                `statewire-session:${database}:${key}`,
+                { ifAvailable: true },
+                (inner) => (inner === null ? undefined : action()),
+              ),
+      ),
+    subscribe: (listener) => {
+      const own = new BroadcastChannel(`statewire-idb:${database}`);
+      own.onmessage = (event: MessageEvent<string>) => listener(event.data);
+      return () => own.close();
+    },
+  };
+  backends.set(database, backend);
+  return backend;
+};
+
+const holdLock = (name: string, mode: LockMode = "exclusive") => {
+  let release: (() => void) | undefined;
+  let disposed = false;
+  void navigator.locks
+    .request(name, { mode }, () => {
+      if (disposed) return;
+      return new Promise<void>((resolve) => {
+        release = resolve;
+      });
+    })
+    .catch(() => {});
+  return () => {
+    disposed = true;
+    release?.();
+  };
+};
+
+const useIndexedDbSession = ({
+  database = "statewire",
+  key,
+  namespace = "statewire-session:",
+  ...options
+}: IndexedDbSession.Options): StatewireClient.SessionStorage => {
+  if (typeof navigator === "undefined" || navigator.locks === undefined)
+    throw new Error(
+      "statewire: IndexedDbSession requires the Web Locks API (navigator.locks)",
+    );
+  const backend = indexedDbBackend(database);
+  const storageKey = namespace + key;
+  const [tabId] = useState(randomId);
+  useEffect(() => holdLock(`statewire-tab:${tabId}`), [tabId]);
+  useEffect(
+    () => holdLock(`statewire-active:${database}:${storageKey}`, "shared"),
+    [database, storageKey],
+  );
+  const storage = useResource(
+    KeyValueSessionStorage({ ...options, backend, key, namespace }),
+  );
+  return useMemo(
+    (): StatewireClient.SessionStorage => ({
+      ...storage,
+      lock: (fn) =>
+        navigator.locks.request(
+          `statewire-session:${database}:${storageKey}`,
+          async () => fn(),
+        ),
+      notifyLock: (fn) =>
+        navigator.locks.request(
+          `statewire-notify:${database}:${storageKey}`,
+          fn,
+        ),
+      owner: {
+        id: tabId,
+        whenGone: (id, signal) =>
+          navigator.locks.request(`statewire-tab:${id}`, { signal }, () => {}),
+      },
+      subscribe: (listener) =>
+        backend.subscribe!((changed) => {
+          if (changed === storageKey) listener();
+        }),
+    }),
+    [storage, backend, database, storageKey, tabId],
+  );
+};
+
+/** Shared session storage on IndexedDB: sharers serialize through Web Locks and hear each other over a BroadcastChannel. */
+export const IndexedDbSession = resource(useIndexedDbSession);
+
+export namespace IndexedDbSession {
+  export type Options = Omit<
+    KeyValueSessionStorage.Options,
+    "backend" | "namespace"
+  > & {
+    /** IndexedDB database name; default "statewire". */
+    database?: string;
+    /** Default "statewire-session:". */
+    namespace?: string;
+  };
+}

package/src/statewire.ts

@@ -46,6 +46,7 @@ const useSessionTransport = ({
     canOvertake?:
       | Readonly<Record<string, StatewireClient.CanOvertake>>
       | undefined;
+    onSettled?: StatewireClient.OnSettled | undefined;
   };
 }): Statewire<unknown> =>
   useContextProvider(SessionStorageContext, session, () =>
@@ -97,6 +98,8 @@ export const useStatewire = <
       keyPrefixes: options.keyPrefixes,
     }),
   };
+  const handlesUpdates = options.onCommandChange !== undefined;
+  const coreRef = useRef<ReturnType<typeof useStatewireCore> | null>(null);
   const link = useMemo(
     () => ({
       ...(options.isNew === undefined ? {} : { isNew: options.isNew }),
@@ -104,8 +107,14 @@ export const useStatewire = <
       ...(options.canOvertake === undefined
         ? {}
         : { canOvertake: options.canOvertake }),
+      ...(handlesUpdates && {
+        onSettled: (update: Statewire.CommandUpdate) =>
+          latest.current.onCommandChange?.(update as never, {
+            state: coreRef.current?.getState() as never,
+          }),
+      }),
     }),
-    [options.isNew, options.context, options.canOvertake],
+    [options.isNew, options.context, options.canOvertake, handlesUpdates],
   );
   const value = useResource(
     SessionTransport({
@@ -125,6 +134,7 @@ export const useStatewire = <
       localContext(protocol, context);
   }, [options.context, localContext]);
   const core = useStatewireCore(() => latest.current, value);
+  coreRef.current = core;
   useEffect(() => core.rematerialize(), [core, options.materializeKey]);
   const [subscribe] = useState(
     () => (listener: () => void) =>
@@ -137,11 +147,6 @@ export const useStatewire = <
     core.getState,
   ) as TState;
   const isBusy = useSyncExternalStore(subscribe, core.getBusy, core.getBusy);
-  const failed = useSyncExternalStore(
-    subscribe,
-    core.getFailed,
-    core.getFailed,
-  );
   const outboxEntries = useSyncExternalStore(
     subscribe,
     core.getOutbox,
@@ -153,7 +158,6 @@ export const useStatewire = <
     selection,
     invoke: transportInvoke,
     setContext: transportSetContext,
-    failures: transportFailures,
     outbox: transportOutbox,
   } = value;
 
@@ -183,12 +187,6 @@ export const useStatewire = <
   );
 
   return useMemo(() => {
-    const failures = (): NonNullable<typeof transportFailures> => {
-      if (!transportFailures) {
-        throw new Error("statewire: this transport has no failed-send lane");
-      }
-      return transportFailures;
-    };
     const outbox = (): NonNullable<typeof transportOutbox> => {
       if (!transportOutbox) {
         throw new Error("statewire: this transport has no outbox");
@@ -205,16 +203,13 @@ export const useStatewire = <
       connection,
       commands: core.commands as Statewire.CommandsProxy<TCommands>,
       isBusy,
-      failed,
-      retryFailed: (entry: StatewireClient.FailedCommand) =>
-        failures().retry(entry),
-      discardFailed: (entry: StatewireClient.FailedCommand) =>
-        failures().discard(entry),
       outbox: {
         entries: outboxEntries,
-        hold: (entry, meta) => outbox().hold(entry, meta),
-        release: (entry) => outbox().release(entry),
-        remove: (entry) => outbox().remove(entry),
+        hold: (id) => outbox().hold(id),
+        release: (id) => outbox().release(id),
+        remove: (id) => outbox().remove(id),
+        update: (id, fn) => outbox().update(id, fn),
+        insert: (entry) => outbox().insert(entry),
       },
     };
   }, [
@@ -222,13 +217,11 @@ export const useStatewire = <
     transportOutbox,
     state,
     isBusy,
-    failed,
     connection,
     core,
     source,
     selection,
     invoke,
-    transportFailures,
     setContext,
   ]);
 };
@@ -286,18 +279,6 @@ export class StatewireClient<
     return this.root.getValue().isBusy;
   }
 
-  get failed(): readonly StatewireClient.FailedCommand[] {
-    return this.root.getValue().failed;
-  }
-
-  retryFailed(entry: StatewireClient.FailedCommand): Promise<unknown> {
-    return this.root.getValue().retryFailed(entry);
-  }
-
-  discardFailed(entry: StatewireClient.FailedCommand): void {
-    this.root.getValue().discardFailed(entry);
-  }
-
   get outbox(): StatewireClient.Outbox {
     return this.root.getValue().outbox;
   }
@@ -345,17 +326,19 @@ export namespace StatewireClient {
       state: NonNullable<TState>,
       ctx: { changes: Statewire.Changes },
     ) => void;
+    /**
+     * queued, posted and applied updates are best-effort and in memory. A
+     * durable session persists each `settled` update before the command leaves
+     * the record and delivers it to one sharer at a time: at-least-once under
+     * the same `id`, acked once the returned promise resolves; a pending
+     * delivery blocks later ones for the same session.
+     */
     onCommandChange?: (
       update: Statewire.CommandUpdate<TCommands>,
       ctx: { state: NonNullable<TState> },
-    ) => void;
+    ) => unknown;
     onConnectionChange?: (connection: Connection) => void;
     onError?: (error: ConnectionError) => void;
-    /** Drops a retained failed entry once a canonical snapshot shows its effect landed; checked against each new snapshot. */
-    failureCovered?: (
-      state: NonNullable<TState>,
-      entry: FailedCommand,
-    ) => boolean;
   };
 
   export type Helpers<
@@ -379,25 +362,40 @@ export namespace StatewireClient {
     commands: Statewire.CommandsProxy<TCommands>;
     /** Negation of the server's broadcast idle level (a transport without idle is always busy). */
     isBusy: boolean;
-    /** Non-accepted sends retained in the session record; reload with it. */
-    failed: readonly FailedCommand[];
-    /** Re-enqueues the entry's command on fresh clocks and removes the entry. */
-    retryFailed: (entry: FailedCommand) => Promise<unknown>;
-    /** Removes the entry. */
-    discardFailed: (entry: FailedCommand) => void;
-    /** Commands queued without a seq yet; a transport without a session has an empty outbox whose methods throw. */
+    /** Unsettled commands in queue order; a transport without a session has an empty outbox whose methods throw. */
     outbox: Outbox;
   };
 
-  /** The queued commands no sharer has stamped yet, and the operations on them. */
+  /** The unsettled commands across sharers, and the operations on them; every verb throws `outbox: no entry <id>` or `outbox: <id> is in flight`. */
   export type Outbox = {
     readonly entries: readonly OutboxEntry[];
-    /** Keeps the entry out of every flush until released; `meta` persists with it. */
-    hold: (entry: OutboxEntry, meta?: unknown) => Promise<"held" | "stamped">;
-    /** Lets the next flush stamp the entry. */
-    release: (entry: OutboxEntry) => Promise<"released" | "stamped">;
-    /** Drops the entry; its send rejects `{ fate: "aborted", cause: "removed" }`. */
-    remove: (entry: OutboxEntry) => Promise<"removed" | "stamped">;
+    /** queued → held: no flush stamps it until released. */
+    hold: (id: string) => void;
+    /** held → queued; settles with the command's outcome. */
+    release: (id: string) => Promise<unknown>;
+    /** Drops a queued or held entry; its pending send rejects `{ fate: "aborted", cause: "removed" }`. */
+    remove: (id: string) => void;
+    /** Patches the entry under the storage lock; `fn` gets the current entry. */
+    update: (id: string, fn: (entry: OutboxEntry) => OutboxPatch) => void;
+    /** Adds a command no send awaits, at the lane's tail or next to `after`/`before`; returns its id. */
+    insert: (entry: OutboxInsert) => string;
+  };
+
+  export type OutboxPatch = {
+    held?: boolean;
+    localMeta?: unknown;
+    command?: { params: readonly unknown[] };
+  };
+
+  export type OutboxInsert = {
+    /** The `settled` update this re-inserts: the insert acks it in the same write, so a redelivery never inserts twice. */
+    from?: string;
+    protocol: string;
+    command: { method: string; params: readonly unknown[] };
+    held?: boolean;
+    localMeta?: unknown;
+    after?: string;
+    before?: string;
   };
 
   /** Connection lifecycle and whether its current state warrants a problem indicator. */
@@ -448,17 +446,20 @@ export namespace StatewireClient {
   ) => void;
 
   export type OptimisticContext = {
+    /** Enqueue time. */
     ts: number;
     /** Absent while the command waits in the outbox. */
     seq?: number;
     clientId?: string;
-    /** The outbox hold, with its meta; null when not held. */
-    held: null | { meta: unknown };
+    state: OutboxState;
+    localMeta: unknown;
   };
 
   export type InvokeOptions = {
-    /** Enqueue the command already held, with the hold's meta. */
-    hold?: { meta?: unknown };
+    /** Enqueue the command held. */
+    hold?: boolean;
+    /** Client-only data persisted with the entry, never sent. */
+    localMeta?: unknown;
   };
 
   /**
@@ -469,7 +470,7 @@ export namespace StatewireClient {
    */
   export type FlushReason = "enqueue" | "reconnect" | "reload" | "release";
 
-  /** Runs in the sharer about to stamp, under the storage lock, once per reason; `outbox.hold` and `outbox.remove` on these entries apply synchronously. */
+  /** Runs in the sharer about to stamp, under the storage lock, once per reason; outbox verbs on these entries apply synchronously before stamping. */
   export type OnFlush = (flush: {
     commands: readonly OutboxEntry[];
     reason: FlushReason;
@@ -508,7 +509,7 @@ export namespace StatewireClient {
     | { fate: "expired"; cause: "server" }
     | {
         fate: "aborted";
-        cause: "unmount" | "stream-gone" | "session-lost" | "removed";
+        cause: "unmount" | "stream-gone" | "session-lost" | "removed" | "quota";
         predecessorLost?: true;
       }
     | {
@@ -516,10 +517,15 @@ export namespace StatewireClient {
         cause: "unmount" | "stream-gone" | "session-lost";
       };
 
-  /** Held commands a proven record gap settled `{fate: "lost", cause: "session-lost"}`; return "requeue" to re-enqueue them on the reset clocks. */
+  /**
+   * Temporary and discouraged; removed in a later release. A proven record gap
+   * settles the lane's commands `{ fate: "lost", cause: "session-lost" }` and
+   * drops its outbox. Returning "requeue" instead re-enqueues this client's
+   * lost stamps (fresh ids, at the tail) and keeps the outbox.
+   */
   export type OnSessionLost = (
     pending: ReadonlyArray<{
-      id?: string;
+      id: string;
       method: string;
       params: readonly unknown[];
       ts: number;
@@ -528,19 +534,18 @@ export namespace StatewireClient {
     }>,
   ) => "requeue" | "drop";
 
-  /** A non-accepted send retained for the user: the wire statement, its failure, and its original clocks. */
-  export type FailedCommand = {
-    readonly protocol: string;
-    readonly produced?: SessionCommand["produced"];
-    readonly command: string;
-    readonly params: readonly unknown[];
-    readonly meta?: unknown;
-    readonly failure: SendFailure;
-    readonly ts: number;
-    readonly seq: number;
-  };
+  /** Reports a deprecated code path firing, so its use can be measured before removal. */
+  export type OnDeprecatedPath = (event: {
+    kind: "session-lost-requeue";
+    count: number;
+  }) => void;
+
+  /** Delivers one durable `settled` update; acked once the returned promise resolves. */
+  export type OnSettled = (update: Statewire.CommandUpdate) => unknown;
 
-  /** A queued command without a seq, as persisted. */
+  export type OutboxState = "queued" | "held" | "sending";
+
+  /** A queued command as persisted. */
   export type OutboxCommand = {
     id: string;
     produced?: {
@@ -549,30 +554,41 @@ export namespace StatewireClient {
     };
     method: string;
     params: unknown[];
+    /** Encoding of non-JSON params. */
     meta?: unknown;
+    /** Enqueue time. */
     ts: number;
     /** Present while held. */
-    hold?: { meta?: unknown };
+    held?: true;
+    localMeta?: unknown;
     /** Its hold was released; the next flush reports reason "release". */
     released?: true;
     /** The enqueuing sharer's `SessionStorage.owner.id` (shared storage only). */
     by?: string;
   };
 
-  /** A queued command without a seq, in queue order. */
+  /** An unsettled command, in queue order. */
   export type OutboxEntry = {
     readonly id: string;
     readonly protocol: string;
-    readonly command: { method: string; params: readonly unknown[] };
-    /** The hold, with its meta; null when not held. */
-    readonly held: null | { readonly meta: unknown };
+    readonly command: {
+      readonly method: string;
+      readonly params: readonly unknown[];
+    };
+    /** Enqueue time. */
+    readonly ts: number;
+    readonly state: OutboxState;
+    /** Client-only, persisted, never sent. */
+    readonly localMeta: unknown;
+    /** False when the entry lives in page memory only. */
+    readonly durable: boolean;
   };
 
-  /** Whether `entry` may move ahead of `ahead`, a held entry or one waiting behind a hold. */
+  /** Whether `entry` may move ahead of `ahead`, a held entry or one waiting behind one. */
   export type CanOvertake = (entry: OutboxEntry, ahead: OutboxEntry) => boolean;
 
   /** A stamped command as persisted while un-durable: its lane seq, the sharer that stamped it, plus the wire statement. */
-  export type SessionCommand = Omit<OutboxCommand, "hold" | "released"> & {
+  export type SessionCommand = Omit<OutboxCommand, "held" | "released"> & {
     seq: number;
     /** The stamping sharer's `SessionStorage.owner.id` (shared storage only). */
     owner?: string;
@@ -583,12 +599,26 @@ export namespace StatewireClient {
     nextSeq: number;
     commands: readonly SessionCommand[];
     outbox?: readonly OutboxCommand[];
-    /** Entries another sharer removed, kept until their enqueuer (`by`) rejects them or is gone (shared storage only). */
-    removed?: readonly { id: string; by: string }[];
+    /** Entries another sharer settled unsent, kept until their enqueuer (`by`) rejects them or is gone (shared storage only); no failure means removed. */
+    removed?: readonly { id: string; by: string; failure?: SendFailure }[];
     /** Terminal verdicts parked for the sharer that minted the seq (shared storage only). */
     verdicts?: readonly SessionVerdict[];
-    /** Non-accepted sends retained for the user; survive record rebases and resets. */
-    failed?: readonly FailedCommand[];
+    /** Terminal `settled` updates awaiting their `onCommandChange` ack. */
+    inbox?: readonly StoredSettled[];
+  };
+
+  /** A terminal update as persisted: the stored command plus its outcome. */
+  export type StoredSettled = {
+    id: string;
+    method: string;
+    params: unknown[];
+    meta?: unknown;
+    ts: number;
+    seq?: number;
+    localMeta?: unknown;
+    /** The accepted result, encoded as a one-element param list. */
+    result?: { value: unknown[]; meta?: unknown };
+    failure?: SendFailure;
   };
 
   /** The persisted session: the client identity plus one lane per durable protocol. */
@@ -611,6 +641,10 @@ export namespace StatewireClient {
 
   /** Session storage seam with optional asynchronous hydration and persistence. */
   export type SessionStorage = {
+    /** False when the record lives in page memory only. */
+    durable?: boolean;
+    /** Re-reads the stored record; awaited under `lock` when present. */
+    read?: () => Promise<SessionRecord | null>;
     /** Resolves when a synchronous load can return the hydrated record. */
     ready?: Promise<void>;
     /** Resolves after all queued saves are persisted; awaited before sending statements. */
@@ -631,6 +665,17 @@ export namespace StatewireClient {
       id: string;
       whenGone: (id: string, signal: AbortSignal) => Promise<void>;
     };
+    /** Exclusive across sharers while a durable `settled` update is delivered; required alongside `lock`. */
+    notifyLock?: <T>(fn: () => Promise<T>) => Promise<T>;
+    /** Reports failure notices the session dropped. */
+    onEvict?: (event: Omit<EvictEvent, "key">) => void;
+  };
+
+  export type EvictEvent = {
+    key: string;
+    reason: "expired" | "overflow" | "quota" | "inbox";
+    /** The undelivered `settled` updates that went with it. */
+    dropped: readonly Statewire.CommandUpdate[];
   };
 
   /** Static headers, or a resolver invoked per request/attach; `staleAuth` is true right after an auth rejection. */
@@ -648,6 +693,7 @@ export namespace StatewireClient {
     headers?: HeadersOption;
     fetch?: typeof globalThis.fetch;
     onSessionLost?: OnSessionLost;
+    onDeprecatedPath?: OnDeprecatedPath;
     onFlush?: OnFlush;
     /** Per protocol: lets an outbox entry move ahead of held or waiting ones; default never. */
     canOvertake?: Readonly<Record<string, CanOvertake>>;
@@ -669,6 +715,7 @@ export namespace StatewireClient {
       | (() => Record<string, string> | Promise<Record<string, string>>);
     webSocket?: new (url: string, protocols?: string | string[]) => WebSocket;
     onSessionLost?: OnSessionLost;
+    onDeprecatedPath?: OnDeprecatedPath;
     onFlush?: OnFlush;
     /** Per protocol: lets an outbox entry move ahead of held or waiting ones; default never. */
     canOvertake?: Readonly<Record<string, CanOvertake>>;