@takodotid/circuit 0.38.0 → 0.39.0

package/dist/chunks/{index-yzw86rc8.js → index-k38bby43.js}

@@ -1,10 +1,68 @@
-import {
-  Catalog
-} from "./index-6wb41q67.js";
 import {
   Address2
 } from "./index-n7w3tg5y.js";
 
+// src/platforms/fortios/models.ts
+var models = {
+  "FG-3700D": {
+    ports: { "40g": 4, "10g": 28, "1g": 2 },
+    spelling: { "40g": "port{n}", "10g": "port{n+4}", "1g": "mgmt{n}" }
+  }
+};
+
+// src/platforms/junos/models.ts
+var models2 = {
+  "QFX5100-48S-6Q": {
+    ports: { "40g": 6, "10g": 48, "1g": 2 },
+    spelling: { "40g": "et-0/0/{n+47}", "10g": "xe-0/0/{n-1}", "1g": "em{n-1}" }
+  }
+};
+
+// src/platforms/raisecom-ros/models.ts
+var models3 = {
+  "RAX721-C-6C48": {
+    ports: { "100g": 6, "25g": 24, "10g": 24 },
+    spelling: { "100g": "hundredgige 1/1/{n}", "25g": "twenty-fivegige 1/2/{n}", "10g": "tengigabitethernet 1/3/{n}" }
+  }
+};
+
+// src/platforms/routeros/models.ts
+var models4 = {
+  "CCR2216-1G-12XS-2XQ": {
+    ports: { "100g": 2, "25g": 12, "1g": 1 },
+    spelling: { "100g": "qsfp28-{n}-1", "25g": "sfp28-{n}", "1g": "ether{n}" },
+    limits: { lag_members: 8, switch_port_ranges: 5 }
+  }
+};
+
+// src/platforms/vrp/models.ts
+var models5 = {
+  "CE6855-48S6Q-HI": { ports: { "10g": 48, "40g": 6 }, spelling: { "10g": "10GE1/0/{n}", "40g": "40GE1/0/{n}" } }
+};
+
+// src/platforms/catalog.ts
+class Catalog {
+  static MODELS = { routeros: models4, vrp: models5, "raisecom-ros": models3, junos: models2, fortios: models };
+  static ports(platform, model) {
+    const spec = Catalog.MODELS[platform]?.[model];
+    if (!spec)
+      throw new Error(`${platform} has no model ${model}`);
+    return Object.entries(spec.ports).flatMap(([speed, count]) => Array.from({ length: count }, (_, i) => `${speed}-${i + 1}`));
+  }
+  static limits(platform, model) {
+    const spec = Catalog.MODELS[platform]?.[model];
+    return spec?.limits ?? {};
+  }
+  static spell(platform, model, port) {
+    const spec = Catalog.MODELS[platform]?.[model];
+    const parts = /^(\d+[gm])-(\d+)$/.exec(port);
+    const template = parts && spec?.spelling[parts[1]];
+    if (!template)
+      throw new Error(`${model} has no port ${port}`);
+    return template.replace(/\{n([+-]\d+)?\}/, (_, shift) => String(Number(parts[2]) + Number(shift ?? 0)));
+  }
+}
+
 // src/core/topology.ts
 class Builder {
   nodes = new Map;
@@ -918,4 +976,4 @@ class StudioModel {
   }
 }
 
-export { Topology, AddressSpace, StudioModel };
+export { Catalog, Topology, AddressSpace, StudioModel };

package/dist/chunks/{server-cxr9ynxc.js → server-ggertnce.js}

@@ -1,6 +1,6 @@
 import {
   StudioModel
-} from "./index-yzw86rc8.js";
+} from "./index-k38bby43.js";
 
 // src/studio/server.ts
 import { execFile as execFile2, spawn } from "node:child_process";

package/dist/cli/index.js

@@ -4,13 +4,11 @@ import {
   Secrets2
 } from "../chunks/index-20kcjxjg.js";
 import {
+  Catalog,
   Topology,
   AddressSpace,
   StudioModel
-} from "../chunks/index-yzw86rc8.js";
-import {
-  Catalog
-} from "../chunks/index-6wb41q67.js";
+} from "../chunks/index-k38bby43.js";
 import {
   Address2
 } from "../chunks/index-n7w3tg5y.js";
@@ -3750,6 +3748,28 @@ class Cabling {
     }
     return findings;
   }
+  static describeLinks(devices) {
+    const byName = new Map(devices.map((device) => [device.name, device]));
+    return devices.map((device) => {
+      const ports = Object.entries(device.ports ?? {});
+      if (!ports.some(([, port]) => port?.link && port.description === undefined))
+        return device;
+      const described = ports.map(([name, port]) => {
+        const far = port?.link ? byName.get(port.link.device) : undefined;
+        if (!port?.link || port.description !== undefined || !far)
+          return [name, port];
+        return [name, { ...port, description: `${far.name} ${Cabling.labelOf(far, port.link.port)}` }];
+      });
+      return { ...device, ports: Object.fromEntries(described) };
+    });
+  }
+  static labelOf(device, port) {
+    try {
+      return Catalog.spell(device.platform, device.model, port);
+    } catch {
+      return port;
+    }
+  }
   static isDevice(system, name) {
     return system === name || system.startsWith(`${name}.`);
   }
@@ -11569,10 +11589,14 @@ class Cli {
     return new Cli(configPath, network, options);
   }
   static async load(path) {
-    if (process.versions.bun)
-      return (await import(path)).default;
-    const { createJiti } = await import("jiti");
-    return createJiti(import.meta.url).import(path, { default: true });
+    let network;
+    if (process.versions.bun) {
+      network = (await import(path)).default;
+    } else {
+      const { createJiti } = await import("jiti");
+      network = await createJiti(import.meta.url).import(path, { default: true });
+    }
+    return { ...network, devices: Cabling.describeLinks(network.devices) };
   }
   static fail(message) {
     console.error(message);
@@ -12377,7 +12401,7 @@ Renamed. Run circuit validate, then circuit apply ${to}: the device keeps its ol
     const port = Number(flags.port);
     if (!Number.isInteger(port) || port < 1 || port > 65535)
       Cli.fail("--port takes a number from 1 to 65535");
-    const { StudioServer } = await import("../chunks/server-cxr9ynxc.js");
+    const { StudioServer } = await import("../chunks/server-ggertnce.js");
     const host = flags.host;
     const allowHosts = (flags.allowHost ?? "").split(",").filter(Boolean);
     if (!StudioServer.isLoopback(host) && !allowHosts.length) {

package/dist/helpers/index.js

@@ -1,6 +1,3 @@
-import {
-  Catalog
-} from "../chunks/index-6wb41q67.js";
 import {
   Address2
 } from "../chunks/index-n7w3tg5y.js";
@@ -235,8 +232,8 @@ class Bgp {
 class Cables {
   static link(spec) {
     return {
-      a: { [spec.a.port]: Cables.end(spec, spec.b, spec.b.port) },
-      b: { [spec.b.port]: Cables.end(spec, spec.a, spec.a.port) }
+      a: { [spec.a.port]: Cables.end(spec, spec.b.device, spec.b.port) },
+      b: { [spec.b.port]: Cables.end(spec, spec.a.device, spec.a.port) }
     };
   }
   static lag(spec) {
@@ -248,18 +245,17 @@ class Cables {
         throw new Error(`Cables.lag: ${spec.b.device} ${far} is cabled to both ${other} and ${near} on ${spec.a.device}`);
       taken.set(far, near);
     }
-    const a = Object.fromEntries(pairs.map(([near, far]) => [near, { ...Cables.end(spec, spec.b, far), lag: spec.a.lag }]));
-    const b = Object.fromEntries(pairs.map(([near, far]) => [far, { ...Cables.end(spec, spec.a, near), lag: spec.b.lag }]));
+    const a = Object.fromEntries(pairs.map(([near, far]) => [near, { ...Cables.end(spec, spec.b.device, far), lag: spec.a.lag }]));
+    const b = Object.fromEntries(pairs.map(([near, far]) => [far, { ...Cables.end(spec, spec.a.device, near), lag: spec.b.lag }]));
     return {
       a,
       b
     };
   }
-  static end(shared, far, port) {
-    const farEnd = { device: far.device, port, label: Catalog.spell(far.platform, far.model, port) };
+  static end(shared, device, port) {
     return {
-      description: shared.describe ? shared.describe(farEnd) : `${farEnd.device} ${farEnd.label}`,
-      link: { device: far.device, port, ...shared.through ? { through: shared.through } : {} }
+      link: { device, port, ...shared.through ? { through: shared.through } : {} },
+      ...shared.describe ? { description: shared.describe({ device, port }) } : {}
     };
   }
 }
@@ -668,21 +664,61 @@ class Filters {
   }
 }
 // src/helpers/upstreams.ts
+var DEFAULTS = {
+  vlan: "{key}",
+  native: "{key}-native",
+  interface: "{key}",
+  import: "{KEY}-IN",
+  export: "{KEY}-OUT",
+  group: "{key}"
+};
+
 class Upstreams {
-  static define(catalog) {
+  static define(catalog, options = {}) {
+    const names = options.names ?? {};
     const all = Object.entries(catalog);
     const nameOf = (key, upstream) => upstream.name ?? key;
-    const policy = (key) => key.toUpperCase();
     const grouped = (upstream) => upstream.role === "rs" || Boolean(upstream.multihop);
+    const named = (field, key, upstream) => {
+      const given = names[field];
+      const pattern = given === undefined || typeof given === "string" ? given ?? DEFAULTS[field] : (upstream.tunnel && "tunnel" in given ? given.tunnel : given[upstream.role]) ?? DEFAULTS[field];
+      return pattern.replaceAll("{key}", key).replaceAll("{KEY}", key.toUpperCase()).replaceAll("{number}", () => {
+        const number = upstream.handoff?.number ?? upstream.tunnel?.number;
+        if (number === undefined)
+          throw new Error(`Upstreams: ${key} needs a number for ${field} name ${pattern}`);
+        return String(number);
+      });
+    };
+    for (const field of Object.keys(DEFAULTS)) {
+      const taken = new Map;
+      for (const [key, upstream] of all) {
+        if (field === "native" && upstream.handoff?.native === undefined)
+          continue;
+        if (field === "import" && !upstream.import)
+          continue;
+        if (field === "group" && !grouped(upstream))
+          continue;
+        if (field === "vlan" && !upstream.handoff || field === "interface" && !upstream.handoff && !upstream.tunnel)
+          continue;
+        const name = named(field, key, upstream);
+        const other = taken.get(name);
+        if (other)
+          throw new Error(`Upstreams: ${other} and ${key} both have the ${field} name ${name}`);
+        taken.set(name, key);
+      }
+    }
+    const vlan = (key, upstream) => named("vlan", key, upstream);
+    const native = (key, upstream) => named("native", key, upstream);
+    const policy = (direction, key, upstream) => named(direction, key, upstream);
     const vlans = (device) => {
       const result = {};
       for (const [key, upstream] of all) {
         const handoff = upstream.handoff;
         if (!handoff || device !== undefined && handoff.port?.device !== device)
           continue;
-        result[key] = { id: handoff.vlan, description: nameOf(key, upstream) };
+        result[vlan(key, upstream)] = { id: handoff.vlan, description: nameOf(key, upstream) };
         if (device !== undefined && handoff.native !== undefined) {
-          result[`${key}-native`] = {
+          result[native(key, upstream)] = {
             id: handoff.native,
             description: `Native toward ${nameOf(key, upstream)}, nothing else in it`
           };
@@ -690,7 +726,7 @@ class Upstreams {
       }
       return result;
     };
-    const vlansOn = (device) => all.filter(([, upstream]) => upstream.handoff?.port?.device === device).map(([key]) => key);
+    const vlansOn = (device) => all.filter(([, upstream]) => upstream.handoff?.port?.device === device).map(([key, upstream]) => vlan(key, upstream));
     const ports = (device) => {
       const result = {};
       for (const [key, upstream] of all) {
@@ -698,8 +734,8 @@ class Upstreams {
         if (!handoff?.port || handoff.port.device !== device)
           continue;
         result[handoff.port.port] = {
-          description: nameOf(key, upstream),
-          ...handoff.native !== undefined ? { trunk_vlans: [key], native_vlan: `${key}-native` } : { access_vlan: key },
+          description: names.port ? names.port(key, upstream) : nameOf(key, upstream),
+          ...handoff.native !== undefined ? { trunk_vlans: [vlan(key, upstream)], native_vlan: native(key, upstream) } : { access_vlan: vlan(key, upstream) },
           lldp: false,
           stp: false,
           ...handoff.port.storm_control ? { storm_control: handoff.port.storm_control } : {}
@@ -711,27 +747,29 @@ class Upstreams {
       const result = {};
       for (const [key, upstream] of all) {
         const description = nameOf(key, upstream);
+        const name = named("interface", key, upstream);
         if (upstream.tunnel) {
           const { local, remote, addresses, mtu } = upstream.tunnel;
-          result[key] = { type: "gre", description, local, remote, addresses, ...mtu ? { mtu } : {} };
+          result[name] = { type: "gre", description, local, remote, addresses, ...mtu ? { mtu } : {} };
         } else if (upstream.handoff) {
           const { addresses, exchange } = upstream.handoff;
-          result[key] = { type: "vlan", vlan: key, description, addresses, ...exchange ? { exchange } : {} };
+          result[name] = { type: "vlan", vlan: vlan(key, upstream), description, addresses, ...exchange ? { exchange } : {} };
         }
       }
       return result;
     };
+    const uplinks = () => all.filter(([, upstream]) => upstream.handoff).map(([key, upstream]) => named("interface", key, upstream));
     const settings = (key, upstream) => ({
       remote_as: upstream.asn,
       description: nameOf(key, upstream),
       role: upstream.role,
-      ...upstream.import ? { import: `${policy(key)}-IN` } : {},
-      export: `${policy(key)}-OUT`
+      ...upstream.import ? { import: policy("import", key, upstream) } : {},
+      export: policy("export", key, upstream)
     });
     const groups = () => Object.fromEntries(all.filter(([, upstream]) => grouped(upstream)).map(([key, upstream]) => {
       const multihop = upstream.multihop;
       return [
-        key,
+        named("group", key, upstream),
         {
           ...settings(key, upstream),
           ...multihop ? {
@@ -749,7 +787,7 @@ class Upstreams {
         name,
         {
           ...session,
-          ...grouped(upstream) ? { group: key } : settings(key, upstream),
+          ...grouped(upstream) ? { group: named("group", key, upstream) } : settings(key, upstream),
           ...limit ? { max_prefixes: limit } : {}
         }
       ];
@@ -757,7 +795,7 @@ class Upstreams {
     const policies = (options = {}) => {
       const result = {};
       for (const [key, upstream] of all) {
-        result[`${policy(key)}-OUT`] = [
+        result[policy("export", key, upstream)] = [
           ...options.actions?.(key, upstream) ?? [],
           ...upstream.export ?? [],
           ...Bgp.announce(upstream.announce)
@@ -766,7 +804,7 @@ class Upstreams {
         if (!taken)
           continue;
         const tag = options.tag?.(key, upstream);
-        result[`${policy(key)}-IN`] = [
+        result[policy("import", key, upstream)] = [
           ...taken.default ? Bgp.defaultOnly({ ...taken.default, ...options.sources ? { sources: options.sources } : {} }) : [],
           ...taken.learn ? Bgp.learn({
             ...taken.learn.before ? { before: taken.learn.before } : {},
@@ -779,9 +817,12 @@ class Upstreams {
       }
       return result;
     };
-    const untrusted = () => [...all.filter(([, upstream]) => upstream.handoff).map(([key]) => key), ...natives()];
-    const natives = () => all.filter(([, upstream]) => upstream.handoff?.native !== undefined).map(([key]) => `${key}-native`);
-    const privateDrops = () => all.filter(([, upstream]) => upstream.handoff && upstream.drop_private).map(([key]) => key);
+    const untrusted = () => [
+      ...all.filter(([, upstream]) => upstream.handoff).map(([key, upstream]) => vlan(key, upstream)),
+      ...natives()
+    ];
+    const natives = () => all.filter(([, upstream]) => upstream.handoff?.native !== undefined).map(([key, upstream]) => native(key, upstream));
+    const privateDrops = () => all.filter(([, upstream]) => upstream.handoff && upstream.drop_private).map(([key, upstream]) => vlan(key, upstream));
     const tunnelRules = () => all.flatMap(([key, upstream]) => upstream.tunnel ? [
       {
         description: `GRE from ${nameOf(key, upstream)}`,
@@ -798,6 +839,7 @@ class Upstreams {
       vlansOn,
       ports,
       interfaces,
+      uplinks,
       groups,
       neighbors,
       policies,

package/dist/types/core/cabling.d.ts

@@ -31,6 +31,12 @@ export declare class Cabling {
      * Only ports where both ends run LLDP, by the config, are compared, and only on devices whose neighbors were read. A link `through` a carrier is not compared. LLDP can be off at the far end, so each is a warning.
      */
     static compare(devices: readonly Device[], neighbors: ReadonlyMap<string, readonly Neighbor[]>): Finding[];
+    /**
+     * Each linked port without a description gets one from its far end: the far device and the far port as printed on it, such as `firewall-1 port6`. The far device's own file has its platform and model, so the label is never written twice. A port whose far device is not in the network keeps none.
+     */
+    static describeLinks(devices: readonly Device[]): Device[];
+    /** A port as printed on the device, or Circuit's name for it when the model has no spelling for it. */
+    private static labelOf;
     /** A system name is the device's name, alone or with a domain after it. */
     private static isDevice;
     private static deviceOf;

package/dist/types/helpers/cables.d.ts

@@ -1,32 +1,24 @@
-import { type ModelName, type PlatformName, type PortName } from "../platforms/catalog.js";
-/** One end of a cable: the device, and its platform and model, which name its ports. */
-export type CableEnd<P extends PlatformName, M extends ModelName<P>> = {
-    device: string;
-    platform: P;
-    model: M;
-};
-/** The far end of a port, for its description: the device, the port by Circuit's name, and by the name printed on the device. */
+/** The far end of a port, for a description of your own: the device and its port by Circuit's name. */
 export type FarEnd = {
     device: string;
     port: string;
-    label: string;
 };
 /** What every cable of one entry shares. */
 type Shared = {
     /** What is between the two ends, such as a carrier's local loop. Both ends get it on their `link`. */
     through?: string;
-    /** A port's description from its far end. The far device and the far port's label when absent, such as `firewall-1 port6`. */
+    /** A port's description from its far end. When absent, Circuit writes the far device and the far port as printed on it, such as `firewall-1 port6`, from the far device's own file. */
     describe?: (far: FarEnd) => string;
 };
-/** A port a cable builds: what it is, the LAG it is in, and the other end. */
+/** A port a cable builds: the other end, the LAG it is in, and a description when `describe` gives one. */
 type CablePort<L extends string> = {
-    description: string;
     link: {
         device: string;
         port: string;
         through?: string;
     };
     lag?: L;
+    description?: string;
 };
 /** Ports for both ends of the cables between two of our devices, each cable written once. */
 export declare class Cables {
@@ -34,15 +26,17 @@ export declare class Cables {
      * One cable, both ends. Spread each end into its device's `ports`:
      *
      * ```ts
-     * const uplink = Cables.link({ a: { device: "router-1", platform: "routeros", model: "CCR2216-1G-12XS-2XQ", port: "25g-1" }, b: { ... } });
+     * const uplink = Cables.link({ a: { device: "router-1", port: "25g-1" }, b: { device: "switch-1", port: "10g-48" } });
      * // router-1: ports: { ...uplink.a }
      * ```
      */
-    static link<const PA extends PlatformName, const MA extends ModelName<PA>, const NA extends PortName<PA, MA>, const PB extends PlatformName, const MB extends ModelName<PB>, const NB extends PortName<PB, MB>>(spec: Shared & {
-        a: CableEnd<PA, MA> & {
+    static link<const NA extends string, const NB extends string>(spec: Shared & {
+        a: {
+            device: string;
             port: NA;
         };
-        b: CableEnd<PB, MB> & {
+        b: {
+            device: string;
             port: NB;
         };
     }): {
@@ -52,17 +46,19 @@ export declare class Cables {
     /**
      * The cables of a LAG, both ends, from one list read from end A: `{ "25g-1": "10g-2" }` is a cable from A's 25g-1 to B's 10g-2. Each port is a member of its end's LAG. Spread each end into its device's `ports`; the LAG itself stays on each device.
      */
-    static lag<const PA extends PlatformName, const MA extends ModelName<PA>, const LA extends string, const PB extends PlatformName, const MB extends ModelName<PB>, const LB extends string, const C extends Partial<Record<PortName<PA, MA>, PortName<PB, MB>>>>(spec: Shared & {
-        a: CableEnd<PA, MA> & {
+    static lag<const LA extends string, const LB extends string, const C extends Readonly<Record<string, string>>>(spec: Shared & {
+        a: {
+            device: string;
             lag: LA;
         };
-        b: CableEnd<PB, MB> & {
+        b: {
+            device: string;
             lag: LB;
         };
         cables: C;
     }): {
         a: Record<keyof C & string, CablePort<LA>>;
-        b: Record<NonNullable<C[keyof C]> & string, CablePort<LB>>;
+        b: Record<C[keyof C], CablePort<LB>>;
     };
     /** A port facing `port` on the far device. */
     private static end;

package/dist/types/helpers/index.d.ts

@@ -1,7 +1,7 @@
 export { Bgp } from "./bgp.js";
 export type { Announced, CommunityScheme, DefaultOnlyOptions, LearnOptions, SanityLengths } from "./bgp.js";
 export { Cables } from "./cables.js";
-export type { CableEnd, FarEnd } from "./cables.js";
+export type { FarEnd } from "./cables.js";
 export { Checks } from "./checks.js";
 export type { TrustBoundary } from "./checks.js";
 export { Exchange } from "./exchange.js";

package/dist/types/helpers/upstreams.d.ts

@@ -13,6 +13,8 @@ export type Upstream = {
         vlan: number;
         /** It sends its VLAN tagged: its port gets a native VLAN of its own with this ID, which nothing else is in. Untagged when absent. */
         native?: number;
+        /** Its number in names with `{number}`, such as `core-ipt01-transita`. Written here, so removing another upstream renumbers nothing. */
+        number?: number;
         /** Our addresses on it. `{ address, peer }` for a point-to-point address whose far end is outside its own prefix. */
         addresses: readonly (InterfaceAddress | {
             address: InterfaceAddress;
@@ -27,12 +29,13 @@ export type Upstream = {
         /** An exchange's LAN, for `circuit peeringdb`. */
         exchange?: ExchangeLan;
     };
-    /** A GRE tunnel to it. */
+    /** A GRE tunnel to it. `number` is its number in names with `{number}`. */
     tunnel?: {
         local: IP;
         remote: IP;
         addresses: readonly InterfaceAddress[];
         mtu?: number;
+        number?: number;
     };
     /** Our BGP sessions with it, by name: its address, and ours when it is not the interface's. */
     sessions: Readonly<Record<string, {
@@ -72,6 +75,36 @@ export type Upstream = {
 };
 /** Upstreams by key. The key names everything built from it. */
 export type UpstreamCatalog = Readonly<Record<string, Upstream>>;
+/** A name made from an upstream: `{key}` is its key, `{KEY}` the key in capitals, `{number}` its `handoff.number` or `tunnel.number`. */
+type Pattern = string;
+/** A pattern for every upstream, or one per role. A role left out takes the default. */
+type ByRole = Pattern | {
+    readonly provider?: Pattern;
+    readonly rs?: Pattern;
+    readonly peer?: Pattern;
+};
+/** How the names built from each upstream are made. Each one left out takes its default. */
+export type UpstreamNames = {
+    /** The VLAN a handoff is on. `{key}` when absent. */
+    vlan?: ByRole;
+    /** The native VLAN of a handoff sent tagged. `{key}-native` when absent. */
+    native?: Pattern;
+    /** The router's interface: per role, and `tunnel` for one reached over a tunnel. `{key}` when absent. */
+    interface?: Pattern | {
+        readonly provider?: Pattern;
+        readonly rs?: Pattern;
+        readonly peer?: Pattern;
+        readonly tunnel?: Pattern;
+    };
+    /** The import policy. `{KEY}-IN` when absent. */
+    import?: Pattern;
+    /** The export policy. `{KEY}-OUT` when absent. */
+    export?: Pattern;
+    /** The BGP group of an exchange's route servers or of multihop sessions. `{key}` when absent. */
+    group?: Pattern;
+    /** The description of a handoff's switch port. Its `name` when absent. No device names it, so it may be any function. */
+    port?: (key: string, upstream: Upstream) => string;
+};
 /** How each upstream's policies are written: shared by every upstream of a catalog. */
 export type UpstreamPolicies<P extends string> = {
     /** A policy holding `Bgp.sanity()` that each import calls. The sanity rules are written in each import when absent. */
@@ -83,6 +116,17 @@ export type UpstreamPolicies<P extends string> = {
     /** The source address for routes of its family, one per family. */
     sources?: readonly IP[];
 };
+/** The names a device can refer to, and their patterns when the project gives none. */
+declare const DEFAULTS: {
+    readonly vlan: "{key}";
+    readonly native: "{key}-native";
+    readonly interface: "{key}";
+    readonly import: "{KEY}-IN";
+    readonly export: "{KEY}-OUT";
+    readonly group: "{key}";
+};
+type Defaults = typeof DEFAULTS;
+type Field = keyof Defaults;
 type Key<C> = keyof C & string;
 /** The upstreams that land on a VLAN of ours. */
 type Landed<C> = {
@@ -118,37 +162,76 @@ type Importing<C> = {
         import: object;
     } ? K : never;
 }[Key<C>];
-/** A native VLAN's name. */
-type Native<K extends string> = `${K}-native`;
-/** Each upstream's policies: `TRANSIT_A-IN` and `TRANSIT_A-OUT`. */
-type PolicyName<C> = `${Uppercase<Importing<C>>}-IN` | `${Uppercase<Key<C>>}-OUT`;
+/** The project's pattern for a name, or the default. */
+type PatternOf<N, F extends Field> = N extends {
+    [X in F]: infer P;
+} ? P : Defaults[F];
+/** The pattern an upstream takes: the only one, its tunnel's, its role's, or the default. */
+type Chosen<P, U, F extends Field> = P extends string ? P : U extends {
+    tunnel: object;
+} ? P extends {
+    tunnel: infer T extends string;
+} ? T : Defaults[F] : U extends {
+    role: infer R extends string;
+} ? P extends {
+    [X in R]: infer T extends string;
+} ? T : Defaults[F] : Defaults[F];
+/** Every `From` in `S` replaced. */
+type Replace<S extends string, From extends string, To extends string> = S extends `${infer A}${From}${infer B}` ? `${A}${To}${Replace<B, From, To>}` : S;
+/** An upstream's `handoff.number` or `tunnel.number`. */
+type NumberOf<U> = U extends {
+    handoff: {
+        number: infer N extends number;
+    };
+} ? N : U extends {
+    tunnel: {
+        number: infer N extends number;
+    };
+} ? N : number;
+/** The name built for upstream `K`: its pattern with the key, the key in capitals and its number filled in. */
+type Named<C, N, F extends Field, K extends Key<C>> = Replace<Replace<Replace<Chosen<PatternOf<N, F>, C[K], F>, "{key}", K>, "{KEY}", Uppercase<K>>, "{number}", `${NumberOf<C[K]>}`>;
+/** Each of these upstreams' names. */
+type Names<C, N, F extends Field, Ks extends Key<C>> = {
+    [K in Ks]: Named<C, N, F, K>;
+}[Ks];
 /** The catalog as written, with any key the shape does not have refused, at every level. */
-type Exact<S, T> = T extends readonly unknown[] | string | number | boolean | Secret ? T : {
+type Exact<S, T> = T extends readonly unknown[] | string | number | boolean | Secret | ((...args: never[]) => unknown) ? T : {
     [K in keyof T]: K extends keyof S ? Exact<NonNullable<S[K]>, T[K]> : never;
 };
+/** The names as written, with a name or a role Upstreams does not make refused. */
+type ExactNames<N> = {
+    [F in keyof N]: F extends keyof UpstreamNames ? N[F] extends string | ((...args: never[]) => unknown) ? N[F] : {
+        [R in keyof N[F]]: R extends "provider" | "rs" | "peer" | "tunnel" ? N[F][R] : never;
+    } : never;
+};
 /** A network's upstreams written once, and each device's part built from them. */
 export declare class Upstreams {
     /**
-     * Each upstream written once: its AS, where it lands, its sessions, limits and policy. Everything a device needs is built from it, under names made from each key, so a device that names one is checked:
+     * Each upstream written once: its AS, where it lands, its sessions, limits and policy. Everything a device needs is built from it, under names made from each key, so a device that names one is checked. By default:
      *
      * - VLAN `<key>`, and `<key>-native` for one that sends its VLAN tagged. The router's interface is `<key>` too, a VLAN interface or a GRE tunnel.
      * - Policies `<KEY>-IN` and `<KEY>-OUT`; a BGP group `<key>` for an exchange's route servers or multihop sessions.
      *
-     * On the router: `vlans()`, `interfaces()`, `groups()`, `neighbors()`, `policies({ ... })`, `tunnelRules()`, `addresses()`. On a switch: `vlans(device)`, `ports(device)`, `vlansOn(device)`. For checks and ACLs: `untrusted()`, `natives()`, `privateDrops()`. Lists follow the catalog's order, where order counts on a device.
+     * `names` gives patterns of your own, such as `{ interface: { provider: "core-ipt0{number}-{key}" } }`; see `UpstreamNames`.
+     *
+     * On the router: `vlans()`, `interfaces()`, `uplinks()`, `groups()`, `neighbors()`, `policies({ ... })`, `tunnelRules()`, `addresses()`. On a switch: `vlans(device)`, `ports(device)`, `vlansOn(device)`. For checks and ACLs: `untrusted()`, `natives()`, `privateDrops()`. Lists follow the catalog's order, where order counts on a device.
      */
-    static define<const C extends UpstreamCatalog>(catalog: C & {
+    static define<const C extends UpstreamCatalog, const N extends UpstreamNames = {}>(catalog: C & {
         [K in keyof C]: Exact<Upstream, C[K]>;
+    }, options?: {
+        names?: N & ExactNames<N>;
     }): {
-        vlans: <const D extends string | undefined = undefined>(device?: D) => D extends string ? { [K in Landed<C>]: Vlan; } & { [K in Tagged<C> as Native<K>]: Vlan; } : { [K in Landed<C>]: Vlan; };
-        vlansOn: (device: string) => Landed<C>[];
-        ports: (device: string) => Record<string, Port<`${Tagged<C>}-native` | Landed<C>, never, never, never>>;
-        interfaces: () => { [K in Landed<C>]: VlanInterface<Landed<C>, never>; } & { [K in Tunneled<C>]: Gre<never>; };
-        groups: () => Record<Grouped<C>, NeighborSettings<PolicyName<C>>>;
-        neighbors: () => Record<string, Neighbor<PolicyName<C>, Grouped<C>>>;
-        policies: <const P extends string = never>(options?: UpstreamPolicies<P>) => Record<PolicyName<C>, PolicyRule<P, never>[]>;
-        untrusted: () => (`${Tagged<C>}-native` | Landed<C>)[];
-        natives: () => `${Tagged<C>}-native`[];
-        privateDrops: () => Landed<C>[];
+        vlans: <const D extends string | undefined = undefined>(device?: D) => D extends string ? { [K in Names<C, N, "vlan", Landed<C>>]: Vlan; } & { [K in Names<C, N, "native", Tagged<C>>]: Vlan; } : { [K in Names<C, N, "vlan", Landed<C>>]: Vlan; };
+        vlansOn: (device: string) => Names<C, N, "vlan", Landed<C>>[];
+        ports: (device: string) => Record<string, Port<Names<C, N, "native", Tagged<C>> | Names<C, N, "vlan", Landed<C>>, never, never, never>>;
+        interfaces: () => { [K in Names<C, N, "interface", Landed<C>>]: VlanInterface<Names<C, N, "vlan", Landed<C>>, never>; } & { [K in Names<C, N, "interface", Tunneled<C>>]: Gre<never>; };
+        uplinks: () => Names<C, N, "interface", Landed<C>>[];
+        groups: () => Record<Names<C, N, "group", Grouped<C>>, NeighborSettings<Names<C, N, "export", Key<C>> | Names<C, N, "import", Importing<C>>>>;
+        neighbors: () => Record<string, Neighbor<Names<C, N, "export", Key<C>> | Names<C, N, "import", Importing<C>>, Names<C, N, "group", Grouped<C>>>>;
+        policies: <const P extends string = never>(options?: UpstreamPolicies<P>) => Record<Names<C, N, "export", Key<C>> | Names<C, N, "import", Importing<C>>, PolicyRule<P, never>[]>;
+        untrusted: () => (Names<C, N, "native", Tagged<C>> | Names<C, N, "vlan", Landed<C>>)[];
+        natives: () => Names<C, N, "native", Tagged<C>>[];
+        privateDrops: () => Names<C, N, "vlan", Landed<C>>[];
         tunnelRules: () => FilterRule<never, never>[];
         addresses: () => IP[];
     };