@mark1russell7/highways 0.4.0 → 0.4.2

package/src/bench/screen/screen.ts

@@ -1,8 +1,13 @@
 import { highwayRouterStrategy } from "../../highways/router.ts";
-import type { Graph, Result } from "../../model.ts";
+import type { Graph, Result, Route } from "../../model.ts";
+import { stableOrderStrategy } from "../../order/index.ts";
+import { repairStrategy } from "../../repair/index.ts";
 import { STRATEGIES } from "../../strategies/builtins.ts";
-import { createRegistry, getStrategy, listStrategies, STEPS, type AnyStrategy, type Registry, type Strategy } from "../../strategies/model.ts";
+import { asRouter, createRegistry, getStrategy, listStrategies, register, STEPS, type AnyStrategy, type Registry, type Strategy } from "../../strategies/model.ts";
 import { compareStep, type CompareRow, type CompareStep, type StepComparison } from "../compare.ts";
+import { bundledShare, bundleStretch, mergeAngle } from "../measures/bundles.ts";
+import { highwayEdits } from "../measures/highways.ts";
+import { orderFragility } from "../measures/order.ts";
 import { paretoFront, type Objective } from "../measures/pareto.ts";
 import { routeStability } from "../measures/stability.ts";
 import { quantile } from "../measures/stats.ts";
@@ -26,6 +31,15 @@ export const SCREEN_STEPS: readonly ScreenStep[] = ["group", "router", "highway"
 /** The routers that the screen of the step `highway` also runs by default. They are the baselines of the note on highways. */
 export const HIGHWAY_BASE_ROUTERS: readonly string[] = ["corners", "shared", "trunks"];
 
+/**
+ * A wrapper of each router of a screen. `stable` routes the edges in the stable order of WILD-053 (`stableOrderStrategy`).
+ * `repair` runs the repair step of RULE-046 after the router (`repairStrategy`).
+ */
+export type ScreenWrap = "stable" | "repair";
+
+/** The wrappers of `ScreenWrap`. */
+export const SCREEN_WRAPS: readonly ScreenWrap[] = ["stable", "repair"];
+
 /** The hard rules of the routes of a router, or of a plan after `follow`. */
 const ROUTE_RULES: readonly string[] = ["complete", "ends-at-plugs", "fixed-plugs", "no-pass-through", "counts-sum", "link-ends", "bundle-trunk", "run-shared", "same-twice"];
 
@@ -59,8 +73,24 @@ export interface ScreenOptions {
    * The default is `HIGHWAY_BASE_ROUTERS`. The other steps do not read it.
    */
   readonly baseRouters?: readonly string[];
-  /** The seed of the small change of the stability measures. The default is 1. */
+  /** The seed of the small change of the stability measures, and of the first random order of `shuffles`. The default is 1. */
   readonly seed?: number;
+  /**
+   * The wrappers of each router of the steps `router` and `highway`. Each wrapper `w` adds the router `<name>+<w>` as a new strategy, beside the router `<name>`.
+   * The default is none. The steps `group` and `curve` do not read it.
+   */
+  readonly wrap?: readonly ScreenWrap[];
+  /**
+   * The number of random orders of the edges for the order fragility (W3, from WILD-056). Each router routes each input this number of times more.
+   * The default is 0: no measure of the order fragility. The steps `group` and `curve` do not read it.
+   */
+  readonly shuffles?: number;
+  /**
+   * The number of seeded edits of the step `highway` (BUILD-W2A). Each highway strategy runs again after each edit of `highwayEdits`, with its plan before the edit.
+   * The records then get `Z10.edits.*`, the churn of the highways and the share of the highways that keep their id.
+   * The default is 0: no edits. The other steps and the base routers do not read it.
+   */
+  readonly edits?: number;
   /** The commit of the code, for the records. */
   readonly commit?: string;
   /** The predictions of the run. Each record names the first prediction with its strategy, its set and its input. */
@@ -175,8 +205,11 @@ function screenRegistry(step: ScreenStep, strategies: readonly (Strategy<ScreenS
 /** This function tells if a step of the screen gives routes. The step `router` gives routes, and the step `highway` gives routes after `follow`. */
 const givesRoutes = (step: ScreenStep): step is "router" | "highway" => step === "router" || step === "highway";
 
-/** This function gives the values of a row of `compareStep`, with the measures of `measureQuality` for a router. */
-function rowValues(step: ScreenStep, graph: Graph, row: CompareRow): Record<string, number> {
+/**
+ * This function gives the values of a row of `compareStep`, with the measures of `measureQuality` for a router.
+ * A router also gets the bundled share (B2), the merge angle (B6) and the bundle stretch (B3) against the routes `base` of `corners`.
+ */
+function rowValues(step: ScreenStep, graph: Graph, row: CompareRow, base: () => readonly Route[]): Record<string, number> {
   const values: Record<string, number> = { ...row.values };
   delete values["ms"];
   if (givesRoutes(step) && row.result) {
@@ -186,6 +219,11 @@ function rowValues(step: ScreenStep, graph: Graph, row: CompareRow): Record<stri
     values["R8.tight"] = q.tight;
     values["R10.plugAngle"] = q.plugAngle;
     values["R15.inflections"] = q.inflections;
+    values["B2.share"] = bundledShare(row.result);
+    const st = bundleStretch(row.result.routes, base());
+    values["B3.median"] = st.median;
+    values["B3.q95"] = st.q95;
+    values["B6.max"] = mergeAngle(row.result.routes);
   }
   return values;
 }
@@ -208,6 +246,20 @@ function rowRules(step: ScreenStep, graph: Graph, row: CompareRow, again: Compar
   return { hard: { ...countRules(rules, []), "same-twice": deterministic ? 0 : 1 }, deterministic };
 }
 
+/** This function adds the router `<name>+<w>` for each router of the registry and each wrapper `w`. It gives the new registry and the new names. */
+function wrapRouters(registry: Registry, wraps: readonly ScreenWrap[]): { registry: Registry; added: string[] } {
+  const routers = listStrategies(registry, "router");
+  const added: AnyStrategy[] = [];
+  for (const w of wraps) for (const s of routers) added.push((w === "stable" ? stableOrderStrategy(s) : repairStrategy(s)) as AnyStrategy);
+  return { registry: added.length === 0 ? registry : register(registry, ...added), added: added.map((s) => s.name) };
+}
+
+/** This function gives the name of a router without the suffix of a wrapper, for example `shared` for `shared+repair`. */
+export function unwrappedName(name: string): string {
+  for (const w of SCREEN_WRAPS) if (name.endsWith(`+${w}`)) return name.slice(0, -(w.length + 1));
+  return name;
+}
+
 /** This function keeps the finite values and gives them the names of a record. */
 function named(values: Readonly<Record<string, number>>): Record<string, number> {
   const out: Record<string, number> = {};
@@ -232,15 +284,26 @@ export function screen(step: ScreenStep, strategies: readonly (Strategy<ScreenSt
   const candidates = screened.candidates;
   // The step `highway` runs as the step `router`. Each highway strategy with `follow` is a router, after the base routers.
   const base = step === "highway" ? (options.baseRouters ?? HIGHWAY_BASE_ROUTERS).map((name) => getStrategy(STRATEGIES, "router", name)) : [];
-  const registry =
+  const unwrapped =
     step === "highway"
       ? createRegistry([...base, ...listStrategies(screened.registry, "highway").map((s) => highwayRouterStrategy(s))] as readonly AnyStrategy[])
       : screened.registry;
+  const wrapped = givesRoutes(step) ? wrapRouters(unwrapped, options.wrap ?? []) : { registry: unwrapped, added: [] };
+  const registry = wrapped.registry;
+  for (const name of wrapped.added) candidates.add(name);
   const compareAs: CompareStep = step === "highway" ? "router" : step;
   const baseNames = new Set(base.map((s) => s.name));
-  const stepOf = (name: string): ScreenStep => (baseNames.has(name) ? "router" : step);
-  const own = options.options ?? {};
+  const stepOf = (name: string): ScreenStep => (baseNames.has(unwrappedName(name)) ? "router" : step);
+  // A wrapped router gets the options of its router, unless the call gives its own.
+  const own: Record<string, object> = { ...options.options };
+  for (const name of wrapped.added) {
+    const from = options.options?.[unwrappedName(name)];
+    if (own[name] === undefined && from !== undefined) own[name] = from;
+  }
+  const shuffles = givesRoutes(step) ? Math.max(0, Math.floor(options.shuffles ?? 0)) : 0;
   const seed = options.seed ?? 1;
+  const edits = step === "highway" ? Math.max(0, Math.floor(options.edits ?? 0)) : 0;
+  const plans = new Map(listStrategies(screened.registry, "highway").map((s) => [s.name, s]));
   const log = options.log ?? ((): void => {});
   const families = options.families;
   const inputs = (options.inputs ?? screenInputs(set)).filter((i) => families?.includes(i.family) ?? true);
@@ -259,6 +322,10 @@ export function screen(step: ScreenStep, strategies: readonly (Strategy<ScreenSt
     comparisons.push(cmp);
     log(`${input.id}: ${graph.nodes.length} nodes, ${graph.edges.length} edges, ${cmp.rows.map((r) => `${r.strategy} ${r.ms.toFixed(0)}`).join(", ")}`);
     if (bases.has(input.id)) kept.set(input.id, { graph, results: new Map(cmp.rows.flatMap((r) => (r.result ? [[r.strategy, r.result] as const] : []))) });
+    // The routes of `corners` on the input: the base of the bundle stretch (B3). The row of `corners` gives them, or one more run.
+    let cornersRoutes: readonly Route[] | undefined;
+    const cornersBase = (): readonly Route[] =>
+      (cornersRoutes ??= (cmp.rows.find((r) => r.strategy === "corners" && r.result)?.result ?? asRouter(getStrategy(STRATEGIES, "router", "corners")).route(graph)).routes);
     cmp.rows.forEach((row, i) => {
       const strategy = byName.get(row.strategy)!;
       const head = {
@@ -282,7 +349,18 @@ export function screen(step: ScreenStep, strategies: readonly (Strategy<ScreenSt
         return;
       }
       const { hard, deterministic } = rowRules(step, graph, row, again?.rows[i]);
-      const record = { ...head, measures: named(rowValues(step, graph, row)), hard, tolerance: { through: TOLERANCE }, deterministic, ms: row.ms, ...tail };
+      const values = rowValues(step, graph, row, cornersBase);
+      if (shuffles > 0 && row.result) {
+        const router = asRouter(strategy as Strategy<"router">, own[row.strategy]);
+        const f = orderFragility(graph, (g) => router.route(g), { orders: shuffles, seed, base: row.result });
+        Object.assign(values, { "W3.crossings": f.crossings, "W3.detour": f.detour, "W3.inkSaved": f.inkSaved, "W3.ink": f.ink, "W3.changed": f.changed, "W3.poa": f.poa });
+      }
+      const plan = edits > 0 && row.result ? plans.get(row.strategy) : undefined;
+      if (plan) {
+        const z = highwayEdits(graph, plan, own[row.strategy], edits, seed);
+        Object.assign(values, { "Z10.edits.mean": z.mean, "Z10.edits.moved": z.moved, "Z10.churn": z.churn, "Z10.ids": z.ids });
+      }
+      const record = { ...head, measures: named(values), hard, tolerance: { through: TOLERANCE }, deterministic, ms: row.ms, ...tail };
       records.push(record);
       if (givesRoutes(step) && input.base !== undefined && row.result) variants.push({ record, base: input.base, result: row.result });
     });

package/src/highways/base.ts

@@ -0,0 +1,126 @@
+import { dist, type Point } from "../geom.ts";
+import type { Graph, Result, Route } from "../model.ts";
+import { byCollection } from "../routers/trunks.ts";
+import { CORRIDOR_DEFAULTS, corridorPlan } from "./corridors/index.ts";
+import { follow } from "./follow.ts";
+import type { Highway, HighwayInput, HighwayMember, HighwayPlan } from "./model.ts";
+import { sharedWaysPlan } from "./shared-ways/index.ts";
+
+/**
+ * The plan that a post step changes. `none` is the empty plan: `follow` then routes each edge as the router `corners` does.
+ * `shared-ways` and `corridors` are the plans of those highway strategies, with their defaults.
+ */
+export type HighwayBase = "none" | "shared-ways" | "corridors";
+
+/** The values of `HighwayBase`. */
+export const HIGHWAY_BASES: readonly HighwayBase[] = Object.freeze(["none", "shared-ways", "corridors"]);
+
+/** This function gives the plan of a base. */
+export function basePlan(input: HighwayInput, base: HighwayBase): HighwayPlan {
+  if (base === "shared-ways") return sharedWaysPlan(input, { rule: byCollection });
+  if (base === "corridors") return corridorPlan(input, CORRIDOR_DEFAULTS);
+  return { highways: [] };
+}
+
+/** This function gives the routes of a plan after `follow`, with the default way finder. The plan `none` gives the first routes of the edges. */
+export function planRoutes(graph: Graph, plan: HighwayPlan): Result {
+  return follow(graph, plan);
+}
+
+/** This function gives the first route of each edge: the route of `input.routes`, or the route of the empty plan after `follow`. */
+export function firstRoutes(input: HighwayInput): Map<string, readonly Point[]> {
+  const given = routeIndex(input.routes?.routes ?? []);
+  const known = new Set(input.graph.edges.map((e) => e.id));
+  if (input.graph.edges.every((e) => given.has(e.id))) return given;
+  const made = routeIndex(planRoutes(input.graph, { highways: [] }).routes);
+  for (const [edge, points] of given) if (known.has(edge)) made.set(edge, points);
+  return made;
+}
+
+/** One stop of the trip of an edge: the index of the highway in the plan, and the member. */
+export interface TripStop {
+  readonly h: number;
+  readonly m: HighwayMember;
+}
+
+/** This function gives the trip of each edge of a plan. The trip is its highways in the order of `seq`, then in the order of the plan. */
+export function tripsOf(plan: HighwayPlan): Map<string, TripStop[]> {
+  const trips = new Map<string, TripStop[]>();
+  plan.highways.forEach((h, hi) => {
+    for (const m of h.members) {
+      const list = trips.get(m.edge);
+      if (list) list.push({ h: hi, m });
+      else trips.set(m.edge, [{ h: hi, m }]);
+    }
+  });
+  for (const list of trips.values()) list.sort((a, b) => a.m.seq - b.m.seq || a.h - b.h);
+  return trips;
+}
+
+/**
+ * This function gives a plan with the same trips, and with `seq` from 0 to the number of highways of the edge less 1.
+ * A post step can give `seq` values with gaps or below 0, and this function makes them whole again.
+ * It also drops each highway with fewer than two members, and gives the highways new ids in order.
+ */
+export function tidyPlan(plan: HighwayPlan): HighwayPlan {
+  const kept = plan.highways.filter((h) => h.members.length >= 2);
+  const seq = new Map<string, number>();
+  for (const list of tripsOf({ highways: kept }).values()) list.forEach((stop, i) => seq.set(`${stop.h}\u0000${stop.m.edge}`, i));
+  const highways: Highway[] = kept.map((h, hi) => ({
+    ...h,
+    id: `h${hi}`,
+    lanes: h.lanes.filter((e) => h.members.some((m) => m.edge === e)),
+    members: h.members.map((m) => ({ ...m, seq: seq.get(`${hi}\u0000${m.edge}`) ?? 0 })),
+  }));
+  return { highways };
+}
+
+/** This function gives the place along a polyline (as a length from its first point) of the point of the polyline nearest to `p`. */
+export function arcPlace(line: readonly Point[], p: Point): number {
+  let best = Infinity;
+  let at = 0;
+  let walked = 0;
+  for (let i = 1; i < line.length; i++) {
+    const a = line[i - 1]!;
+    const b = line[i]!;
+    const len = dist(a, b);
+    const u = len > 0 ? Math.max(0, Math.min(1, ((p.x - a.x) * (b.x - a.x) + (p.y - a.y) * (b.y - a.y)) / (len * len))) : 0;
+    const d = dist(p, { x: a.x + (b.x - a.x) * u, y: a.y + (b.y - a.y) * u });
+    if (d < best) [best, at] = [d, walked + u * len];
+    walked += len;
+  }
+  return at;
+}
+
+/** This function gives the place on a spine (the index of a point plus the share of the next leg) of the point of the spine nearest to `p`. */
+export function nearestPlace(spine: readonly Point[], p: Point): number {
+  let best = Infinity;
+  let at = 0;
+  for (let i = 1; i < spine.length; i++) {
+    const a = spine[i - 1]!;
+    const b = spine[i]!;
+    const len2 = (b.x - a.x) ** 2 + (b.y - a.y) ** 2;
+    const u = len2 > 0 ? Math.max(0, Math.min(1, ((p.x - a.x) * (b.x - a.x) + (p.y - a.y) * (b.y - a.y)) / len2)) : 0;
+    const d = dist(p, { x: a.x + (b.x - a.x) * u, y: a.y + (b.y - a.y) * u });
+    if (d < best) [best, at] = [d, i - 1 + u];
+  }
+  return at;
+}
+
+/**
+ * This function gives a plan where the `seq` of each member follows the place of its merge point along the route of its edge.
+ * A post step that adds highways to the trips of edges uses it. Equal places keep the order of `seq`.
+ */
+export function orderAlongRoutes(plan: HighwayPlan, routes: ReadonlyMap<string, readonly Point[]>): HighwayPlan {
+  const rank = new Map<string, number>();
+  for (const [edge, list] of tripsOf(plan)) {
+    const route = routes.get(edge);
+    const placed = list.map((stop, i) => ({ stop, i, at: route ? arcPlace(route, stop.m.merge) : i }));
+    placed.sort((a, b) => a.at - b.at || a.i - b.i);
+    placed.forEach((p, k) => rank.set(`${p.stop.h}\u0000${edge}`, k));
+  }
+  return { highways: plan.highways.map((h, hi) => ({ ...h, members: h.members.map((m) => ({ ...m, seq: rank.get(`${hi}\u0000${m.edge}`) ?? m.seq })) })) };
+}
+
+/** This function gives the route of each edge by its id. */
+export const routeIndex = (routes: readonly Route[]): Map<string, readonly Point[]> => new Map(routes.map((r) => [r.edge, r.points]));

package/src/highways/flow-field/index.ts

@@ -0,0 +1,49 @@
+import type { Point } from "../../geom.ts";
+import { WayFinder, type WayOptions } from "../../ways.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { edgePlugs, sharedStretches, type KeyedWay } from "../stretches.ts";
+
+/** The end of the edges that gets a field: the target of a fan-in, or the source of a fan-out. */
+export type FieldEnd = "target" | "source";
+
+/** The options of the highway strategy `flow-field` (EDA-046 with HWY-037 of the notes). */
+export interface FlowFieldOptions extends Pick<WayOptions, "margin" | "k"> {
+  /** An end with this number of edges or more on one side of its box gets a field. The default is 2. */
+  readonly minFanIn: number;
+  /** The end that gets a field. The default is `target`. */
+  readonly end: FieldEnd;
+}
+
+/** The default options of the strategy `flow-field`. */
+export const FLOW_FIELD_DEFAULTS: Readonly<Required<Omit<FlowFieldOptions, "margin" | "k">>> = Object.freeze({ minFanIn: 2, end: "target" });
+
+/**
+ * This function gives the highways of a flow field for each target (EDA-046, HWY-037).
+ * The edges into one side of one box make a fan. The root of the fan is the point out of the median plug of the fan.
+ * Each edge of the fan goes the shortest way from the point out of its other plug to the root, through the corner graph.
+ * The shortest ways to one root make a tree, so they merge like streams and do not cross. Each stretch that two ways share is one highway.
+ * With the end `source`, the same holds for the edges out of one side of one box.
+ */
+export function flowFieldPlan(input: HighwayInput, o: Readonly<FlowFieldOptions>): HighwayPlan {
+  const finder = new WayFinder(input.graph.nodes, { ...(o.margin === undefined ? {} : { margin: o.margin }), ...(o.k === undefined ? {} : { k: o.k }) });
+  const fans = new Map<string, { edge: string; root: Point; far: Point; along: number }[]>();
+  for (const { edge, ps, pt } of edgePlugs(input.graph)) {
+    const [near, far, node] = o.end === "target" ? [pt, ps, edge.target.node] : [ps, pt, edge.source.node];
+    const key = `${node}\u0000${near.normal.x},${near.normal.y}`;
+    const item = { edge: edge.id, root: finder.out(near), far: finder.out(far), along: near.normal.x === 0 ? near.point.x : near.point.y };
+    const list = fans.get(key);
+    if (list) list.push(item);
+    else fans.set(key, [item]);
+  }
+  const ways: KeyedWay[] = [];
+  for (const [key, fan] of fans) {
+    if (fan.length < Math.max(2, o.minFanIn)) continue;
+    const sorted = [...fan].sort((a, b) => a.along - b.along || (a.edge < b.edge ? -1 : a.edge > b.edge ? 1 : 0));
+    const root = sorted[Math.floor((sorted.length - 1) / 2)]!.root;
+    for (const f of fan) {
+      const way = finder.corners.path(f.far, root);
+      if (way) ways.push({ edge: f.edge, key, points: o.end === "target" ? way : [...way].reverse() });
+    }
+  }
+  return sharedStretches(ways, { minSize: 2, pull: (p) => finder.corners.pull(p) });
+}

package/src/highways/gates/ambiguity/index.ts

@@ -0,0 +1,110 @@
+import type { Graph } from "../../../model.ts";
+import type { HighwayInput, HighwayPlan } from "../../model.ts";
+import { keepMembers, type Gate } from "../model.ts";
+
+/** The options of the gate `ambiguity` (HWY-049). */
+export interface AmbiguityGuardOptions {
+  /** Two groups of edges merge only when the merge adds this share of false pairs, or less. The default is 0.5. */
+  readonly maxAmbiguity: number;
+  /** With `node`, the default, two groups merge only when they share an end node. With `any`, only `maxAmbiguity` decides. */
+  readonly link: "node" | "any";
+}
+
+/** The default options of the gate `ambiguity`. */
+export const AMBIGUITY_GUARD_DEFAULTS: Readonly<AmbiguityGuardOptions> = Object.freeze({ maxAmbiguity: 0.5, link: "node" });
+
+/** The adjacency of the nodes of a graph: the neighbours of each node, by the edges. */
+function adjacency(graph: Graph): Map<string, Set<string>> {
+  const out = new Map<string, Set<string>>();
+  const add = (a: string, b: string): void => {
+    const set = out.get(a);
+    if (set) set.add(b);
+    else out.set(a, new Set([b]));
+  };
+  for (const e of graph.edges) {
+    add(e.source.node, e.target.node);
+    add(e.target.node, e.source.node);
+  }
+  return out;
+}
+
+/**
+ * This function gives the ambiguity of a set of nodes: the share of the pairs of distinct nodes without an edge between them.
+ * The nodes are the ends of the edges of one highway. A set with fewer than two nodes gives 0.
+ */
+export function nodeAmbiguity(nodes: ReadonlySet<string>, adj: ReadonlyMap<string, ReadonlySet<string>>): number {
+  const n = nodes.size;
+  if (n < 2) return 0;
+  let linked = 0;
+  for (const v of nodes) for (const w of adj.get(v) ?? []) if (w !== v && nodes.has(w)) linked++;
+  return 1 - linked / 2 / ((n * (n - 1)) / 2);
+}
+
+/** A group of the members of one highway: the edges, their end nodes and the ambiguity of the nodes. */
+interface Group {
+  readonly edges: string[];
+  readonly nodes: Set<string>;
+  readonly amb: number;
+  /** The first lane of the group, for a fixed order. */
+  readonly first: number;
+}
+
+/**
+ * This function applies the ambiguity guard of HWY-049 to a plan. A highway joins edges that belong together.
+ *
+ * Two nodes are a false pair when their edges share a highway and no edge joins them. The ambiguity of a group of edges is the share of false pairs among the pairs of its end nodes.
+ * In each highway, each edge starts as a group. Two groups merge only when `amb(A ∪ B) - max(amb A, amb B)` is at most `maxAmbiguity`.
+ * With the link `node`, they also must share an end node. The merge with the smallest rise comes first.
+ *
+ * The largest group stays on the highway. The other edges leave it and go alone.
+ */
+export function ambiguityPlan(input: HighwayInput, plan: HighwayPlan, options: Readonly<AmbiguityGuardOptions>): HighwayPlan {
+  const adj = adjacency(input.graph);
+  const ends = new Map(input.graph.edges.map((e) => [e.id, [e.source.node, e.target.node] as const]));
+  const stay = new Map<string, Set<string>>();
+  for (const h of plan.highways) {
+    let groups: Group[] = h.lanes.flatMap((edge, i): Group[] => {
+      const end = ends.get(edge);
+      if (!end) return [];
+      const nodes = new Set(end);
+      return [{ edges: [edge], nodes, amb: nodeAmbiguity(nodes, adj), first: i }];
+    });
+    for (;;) {
+      let best: { a: number; b: number; rise: number; group: Group } | undefined;
+      for (let a = 0; a < groups.length; a++)
+        for (let b = a + 1; b < groups.length; b++) {
+          const ga = groups[a]!;
+          const gb = groups[b]!;
+          if (options.link === "node" && ![...gb.nodes].some((v) => ga.nodes.has(v))) continue;
+          const nodes = new Set([...ga.nodes, ...gb.nodes]);
+          const amb = nodeAmbiguity(nodes, adj);
+          const rise = amb - Math.max(ga.amb, gb.amb);
+          if (rise > options.maxAmbiguity + 1e-12) continue;
+          if (best === undefined || rise < best.rise - 1e-12)
+            best = { a, b, rise, group: { edges: [...ga.edges, ...gb.edges], nodes, amb, first: Math.min(ga.first, gb.first) } };
+        }
+      if (!best) break;
+      const merged = best.group;
+      const { a, b } = best;
+      groups = groups.filter((_, i) => i !== a && i !== b);
+      groups.push(merged);
+      groups.sort((p, q) => p.first - q.first);
+    }
+    let top: Group | undefined;
+    for (const g of groups) if (top === undefined || g.edges.length > top.edges.length) top = g;
+    stay.set(h.id, new Set(top?.edges ?? []));
+  }
+  return keepMembers(plan, (h, m) => stay.get(h.id)?.has(m.edge) ?? false);
+}
+
+/** The gate `ambiguity` (HWY-049): the ambiguity guard. A highway does not join edges whose end nodes have no edges between them. */
+export const ambiguityGate: Gate<AmbiguityGuardOptions> = {
+  name: "ambiguity",
+  describe: "The gate `ambiguity` (HWY-049) keeps on each highway the largest group of edges that a reader can tell apart. A merge of two groups must add few false pairs of nodes.",
+  defaults: AMBIGUITY_GUARD_DEFAULTS,
+  schema: {
+    maxAmbiguity: { type: "number", min: 0, max: 1, step: 0.05, marks: [0.3, 0.5], default: 0.5, describe: "Two groups merge only when the merge adds this share of false pairs, or less." },
+    link: { type: "enum", values: ["node", "any"], default: "node", describe: "With `node`, two groups merge only when they share an end node. With `any`, only `maxAmbiguity` decides." },
+  },
+  apply: (input, plan, options) => ambiguityPlan(input, plan, options),
+};

package/src/highways/gates/breakeven/index.ts

@@ -0,0 +1,62 @@
+import type { WayOptions } from "../../../ways.ts";
+import { lengthBetween, type HighwayInput, type HighwayPlan } from "../../model.ts";
+import { edgeLengths, keepMembers, type Gate } from "../model.ts";
+
+/** The options of the gate `breakeven` (HWY-047). */
+export interface BreakEvenOptions {
+  /**
+   * The exponent of the cost law: a stretch with `n` edges costs `n^shareAlpha` times its length. Each edge pays the share `n^(shareAlpha - 1)`.
+   * With 0, a shared stretch is one line, as the ink of B1 counts it. The default is 0.5, as the break-even floor of `corridors`.
+   */
+  readonly shareAlpha: number;
+}
+
+/** The default options of the gate `breakeven`. */
+export const BREAK_EVEN_DEFAULTS: Readonly<BreakEvenOptions> = Object.freeze({ shareAlpha: 0.5 });
+
+/**
+ * This function applies the break-even law of HWY-047 to a plan. An edge stays on its highways only when sharing saves ink.
+ *
+ * The edge pays `n^(shareAlpha - 1)` of each shared stretch, with `n` the members of the highway. Thus it saves `(1 - n^(shareAlpha - 1)) L` on a stretch of the length `L`.
+ * It adds the length of its route along the plan less the length of its route alone. An edge stays when the saving is as large as the added length.
+ * For two parallel edges at the gap `d`, this rule gives the break-even overlap `d √((2 + t) / (2 - t))` with `t = 2^shareAlpha`.
+ *
+ * An edge that does not save ink leaves each of its highways. Then the other members of those highways save less, so the test repeats until no edge leaves.
+ */
+export function breakEvenPlan(input: HighwayInput, plan: HighwayPlan, options: Readonly<BreakEvenOptions>, way: WayOptions = {}): HighwayPlan {
+  const lengths = edgeLengths(input.graph, plan, way);
+  let now = plan;
+  for (;;) {
+    const saving = new Map<string, number>();
+    for (const h of now.highways) {
+      const share = 1 - Math.pow(h.members.length, options.shareAlpha - 1);
+      for (const m of h.members) saving.set(m.edge, (saving.get(m.edge) ?? 0) + share * lengthBetween(h.spine, Math.min(m.on, m.off), Math.max(m.on, m.off)));
+    }
+    const out = new Set<string>();
+    for (const [edge, saved] of saving) {
+      const l = lengths.get(edge);
+      if (l && saved < l.route - l.alone) out.add(edge);
+    }
+    if (out.size === 0) return now;
+    now = keepMembers(now, (_, m) => !out.has(m.edge));
+  }
+}
+
+/** The gate `breakeven` (HWY-047): an edge stays on a highway only when sharing saves ink. */
+export const breakEvenGate: Gate<BreakEvenOptions> = {
+  name: "breakeven",
+  describe: "The gate `breakeven` (HWY-047) keeps an edge on a highway only when its share of the highway saves more ink than its detour adds.",
+  defaults: BREAK_EVEN_DEFAULTS,
+  schema: {
+    shareAlpha: {
+      type: "number",
+      min: 0,
+      max: 0.9,
+      step: 0.1,
+      marks: [0, 0.5],
+      default: 0.5,
+      describe: "The exponent of the cost law. An edge pays the share `n^(shareAlpha - 1)` of a stretch with `n` edges.",
+    },
+  },
+  apply: breakEvenPlan,
+};

package/src/highways/gates/hysteresis/index.ts

@@ -0,0 +1,48 @@
+import type { HighwayInput, HighwayPlan } from "../../model.ts";
+import { commonEdges, matchHighways, type Gate } from "../model.ts";
+
+/** The options of the gate `hysteresis` (HWY-046). */
+export interface HysteresisOptions {
+  /** A new highway needs this number of edges or more. The default is 3. */
+  readonly kOn: number;
+  /** A highway of the earlier plan stays while it has this number of edges or more. The default is 2. */
+  readonly kOff: number;
+}
+
+/** The default options of the gate `hysteresis`. */
+export const HYSTERESIS_DEFAULTS: Readonly<HysteresisOptions> = Object.freeze({ kOn: 3, kOff: 2 });
+
+/** Two highways of two plans are the same highway when the Jaccard index of their edges is this value or more. */
+export const SAME_HIGHWAY = 0.5;
+
+/**
+ * This function applies the count threshold with hysteresis of HWY-046 to a plan.
+ * A highway with `kOn` edges or more stays. A highway with fewer than `kOff` edges goes away.
+ * A highway between the two limits stays only when it was in the earlier plan, `input.previous`.
+ * The highway of the earlier plan with the most common edges is its match, with a Jaccard index of `SAME_HIGHWAY` or more.
+ *
+ * Thus an edit that adds or removes one edge near the limit does not make a highway come and go. Without an earlier plan, the limit is `kOn`.
+ */
+export function hysteresisPlan(input: HighwayInput, plan: HighwayPlan, options: Readonly<HysteresisOptions>): HighwayPlan {
+  const matched = input.previous ? matchHighways(input.previous.plan, plan, SAME_HIGHWAY, commonEdges(input.previous.graph, input.graph)) : new Map<number, number>();
+  const kOff = Math.max(2, Math.min(options.kOff, options.kOn));
+  const highways = plan.highways.filter((h, i) => {
+    const n = h.members.length;
+    if (n >= options.kOn) return true;
+    if (n < kOff) return false;
+    return matched.has(i);
+  });
+  return highways.length === plan.highways.length ? plan : { highways };
+}
+
+/** The gate `hysteresis` (HWY-046): a highway forms at `kOn` edges and goes away below `kOff` edges. */
+export const hysteresisGate: Gate<HysteresisOptions> = {
+  name: "hysteresis",
+  describe: "The gate `hysteresis` (HWY-046) keeps a new highway with `kOn` edges or more. A highway of the earlier plan stays while it has `kOff` edges or more.",
+  defaults: HYSTERESIS_DEFAULTS,
+  schema: {
+    kOn: { type: "integer", min: 2, max: 16, step: 1, default: 3, describe: "A new highway needs this number of edges or more." },
+    kOff: { type: "integer", min: 2, max: 16, step: 1, default: 2, describe: "A highway of the earlier plan stays while it has this number of edges or more." },
+  },
+  apply: (input, plan, options) => hysteresisPlan(input, plan, options),
+};

package/src/highways/gates/ids/index.ts

@@ -0,0 +1,59 @@
+import type { Highway, HighwayInput, HighwayPlan } from "../../model.ts";
+import { commonEdges, matchHighways, type Gate } from "../model.ts";
+
+/** The options of the gate `ids` (HWY-054). */
+export interface StableIdOptions {
+  /** A new highway takes the id of an old highway when the Jaccard index of their edges is this value or more. The default is 0.5. */
+  readonly minJaccard: number;
+}
+
+/** The default options of the gate `ids`. */
+export const STABLE_ID_DEFAULTS: Readonly<StableIdOptions> = Object.freeze({ minJaccard: 0.5 });
+
+/** This function gives the number at the end of an id, or -1 for an id without a number at its end. */
+function numberOf(id: string): number {
+  let start = id.length;
+  while (start > 0 && id.charCodeAt(start - 1) >= 48 && id.charCodeAt(start - 1) <= 57) start--;
+  return start === id.length ? -1 : Number(id.slice(start));
+}
+
+/**
+ * This function gives stable ids to the highways of a plan (HWY-054). The earlier plan is `input.previous`.
+ * Each new highway takes the id of the old highway with the most common edges.
+ * The pairs with the largest Jaccard index of their edges come first.
+ *
+ * A pair needs an index of `minJaccard` or more, and only the edges of both graphs count.
+ * A new highway without a match gets a new id `h<n>` that no old highway and no new highway has. Thus the old highway of a new id ends.
+ * The gate changes only the ids, so the routes do not change. Without an earlier plan, the plan does not change.
+ */
+export function stableIdPlan(input: HighwayInput, plan: HighwayPlan, options: Readonly<StableIdOptions>): HighwayPlan {
+  if (!input.previous) return plan;
+  const before = input.previous.plan;
+  const matched = matchHighways(before, plan, options.minJaccard, commonEdges(input.previous.graph, input.graph));
+  const taken = new Set<string>([...before.highways.map((h) => h.id)]);
+  for (const [, i0] of matched) taken.add(before.highways[i0]!.id);
+  let next = 1 + Math.max(-1, ...before.highways.map((h) => numberOf(h.id)), ...plan.highways.map((h) => numberOf(h.id)));
+  const fresh = (): string => {
+    while (taken.has(`h${next}`)) next++;
+    const id = `h${next++}`;
+    taken.add(id);
+    return id;
+  };
+  const highways = plan.highways.map((h, i): Highway => {
+    const i0 = matched.get(i);
+    const id = i0 === undefined ? fresh() : before.highways[i0]!.id;
+    return id === h.id ? h : { ...h, id };
+  });
+  return { highways };
+}
+
+/** The gate `ids` (HWY-054): stable highway ids across edits. A highway keeps the id of its match in the earlier plan. */
+export const stableIdGate: Gate<StableIdOptions> = {
+  name: "ids",
+  describe: "The gate `ids` (HWY-054) gives each highway the id of the highway of the earlier plan with the most common edges. The routes do not change.",
+  defaults: STABLE_ID_DEFAULTS,
+  schema: {
+    minJaccard: { type: "number", min: 0.3, max: 0.8, step: 0.05, default: 0.5, describe: "A new highway takes the id of an old highway when the Jaccard index of their edges is this value or more." },
+  },
+  apply: (input, plan, options) => stableIdPlan(input, plan, options),
+};

package/src/highways/gates/index.ts

@@ -0,0 +1,6 @@
+export { commonEdges, edgeLengths, gateStrategy, jaccard, keepMembers, matchHighways, type EdgeLengths, type Gate } from "./model.ts";
+export { BREAK_EVEN_DEFAULTS, breakEvenGate, breakEvenPlan, type BreakEvenOptions } from "./breakeven/index.ts";
+export { STRETCH_DEFAULTS, stretchGate, stretchPlan, type StretchOptions } from "./stretch/index.ts";
+export { AMBIGUITY_GUARD_DEFAULTS, ambiguityGate, ambiguityPlan, nodeAmbiguity, type AmbiguityGuardOptions } from "./ambiguity/index.ts";
+export { HYSTERESIS_DEFAULTS, hysteresisGate, hysteresisPlan, SAME_HIGHWAY, type HysteresisOptions } from "./hysteresis/index.ts";
+export { STABLE_ID_DEFAULTS, stableIdGate, stableIdPlan, type StableIdOptions } from "./ids/index.ts";