@takodotid/circuit 0.38.0 → 0.39.0

package/dist/types/schema/interfaces.d.ts

@@ -109,7 +109,7 @@ export type Port<V extends string, A extends string, L extends string, F extends
     acl?: A;
     /** The LAG this port is in. Every other setting goes on the LAG. */
     lag?: L;
-    /** Another of our devices at the other end of the cable. */
+    /** Another of our devices at the other end of the cable. Without a `description`, the port is described from it: the far device and the far port as printed on it, such as `firewall-1 port6`. */
     link?: Link;
 };
 /** Settings every interface that is not a physical port shares. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.38.0",
+    "version": "0.39.0",
     "description": "Declarative, vendor-neutral network configuration: describe each device in TypeScript, and Circuit makes the device match. Alpha.",
     "keywords": [
         "network",

package/src/cli/index.ts

@@ -103,12 +103,20 @@ class Cli {
         return new Cli(configPath, network, options);
     }
 
-    /** The config, a TypeScript file. Bun imports it as it is; Node needs jiti, which also resolves imports written without an extension. */
+    /**
+     * The config, a TypeScript file. Bun imports it as it is; Node needs jiti, which also resolves imports written without an extension. A linked port without a description is given one from its far end.
+     */
     private static async load(path: string): Promise<Network> {
-        if (process.versions.bun) return (await import(path)).default;
+        let network: Network;
+
+        if (process.versions.bun) {
+            network = (await import(path)).default;
+        } else {
+            const { createJiti } = await import("jiti");
+            network = await createJiti(import.meta.url).import<Network>(path, { default: true });
+        }
 
-        const { createJiti } = await import("jiti");
-        return createJiti(import.meta.url).import(path, { default: true });
+        return { ...network, devices: Cabling.describeLinks(network.devices) };
     }
 
     private static fail(message: string): never {

package/src/core/cabling.ts

@@ -121,6 +121,36 @@ export class Cabling {
         return findings;
     }
 
+    /**
+     * 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[] {
+        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) } as 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(device: Device, port: string): string {
+        try {
+            return Catalog.spell(device.platform, device.model, port);
+        } catch {
+            return port;
+        }
+    }
+
     /** A system name is the device's name, alone or with a domain after it. */
     private static isDevice(system: string, name: string): boolean {
         return system === name || system.startsWith(`${name}.`);

package/src/helpers/cables.ts

@@ -1,28 +1,19 @@
-import { Catalog, type ModelName, type PlatformName, type PortName } from "../platforms/catalog";
-
-/** 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. */
-export type FarEnd = { device: string; port: string; label: string };
+/** 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 };
 
 /** 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. */
@@ -31,37 +22,26 @@ export 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> & { port: NA }; b: CableEnd<PB, MB> & { port: NB } }) {
+    static link<const NA extends string, const NB extends string>(
+        spec: Shared & { a: { device: string; port: NA }; b: { device: string; port: NB } }
+    ) {
         return {
-            a: { [spec.a.port]: Cables.end(spec, spec.b, spec.b.port) } as Record<NA, CablePort<never>>,
-            b: { [spec.b.port]: Cables.end(spec, spec.a, spec.a.port) } as Record<NB, CablePort<never>>,
+            a: { [spec.a.port]: Cables.end(spec, spec.b.device, spec.b.port) } as Record<NA, CablePort<never>>,
+            b: { [spec.b.port]: Cables.end(spec, spec.a.device, spec.a.port) } as Record<NB, CablePort<never>>,
         };
     }
 
     /**
      * 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> & { lag: LA }; b: CableEnd<PB, MB> & { lag: LB }; cables: C }) {
-        const pairs = Object.entries(spec.cables) as [string, string][];
+    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: { device: string; lag: LB }; cables: C }
+    ) {
+        const pairs = Object.entries(spec.cables);
 
         const taken = new Map<string, string>();
         for (const [near, far] of pairs) {
@@ -70,22 +50,20 @@ export class Cables {
             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: a as Record<keyof C & string, CablePort<LA>>,
-            b: b as Record<NonNullable<C[keyof C]> & string, CablePort<LB>>,
+            b: b as Record<C[keyof C], CablePort<LB>>,
         };
     }
 
     /** A port facing `port` on the far device. */
-    private static end(shared: Shared, far: { device: string; platform: string; model: string }, port: string): CablePort<never> {
-        const farEnd = { device: far.device, port, label: Catalog.spell(far.platform, far.model, port) };
-
+    private static end(shared: Shared, device: string, port: string): CablePort<never> {
         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 }) } : {}),
         };
     }
 }

package/src/helpers/index.ts

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

package/src/helpers/upstreams.ts

@@ -32,6 +32,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; peer: IP })[];
         /** The switch port it arrives on. */
@@ -39,8 +41,8 @@ export type Upstream = {
         /** An exchange's LAN, for `circuit peeringdb`. */
         exchange?: ExchangeLan;
     };
-    /** A GRE tunnel to it. */
-    tunnel?: { local: IP; remote: IP; addresses: readonly InterfaceAddress[]; mtu?: number };
+    /** 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, { address: IP; local_address?: IP }>>;
     /** The sessions are more than one hop away, from this address of ours. They share a group. */
@@ -65,6 +67,29 @@ 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. */
@@ -77,6 +102,19 @@ export type UpstreamPolicies<P extends string> = {
     sources?: readonly IP[];
 };
 
+/** The names a device can refer to, and their patterns when the project gives none. */
+const DEFAULTS = {
+    vlan: "{key}",
+    native: "{key}-native",
+    interface: "{key}",
+    import: "{KEY}-IN",
+    export: "{KEY}-OUT",
+    group: "{key}",
+} as const;
+
+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> = { [K in Key<C>]: C[K] extends { handoff: object } ? K : never }[Key<C>];
@@ -89,35 +127,120 @@ type Grouped<C> = { [K in Key<C>]: C[K] extends { role: "rs" } | { multihop: obj
 /** The upstreams we take routes from. */
 type Importing<C> = { [K in Key<C>]: C[K] extends { 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
+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 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 & { [K in keyof C]: Exact<Upstream, C[K]> }) {
-        type V = Landed<C>;
-        type T = Tagged<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> } = {}
+    ) {
+        type V = Names<C, N, "vlan", Landed<C>>;
+        type T = Names<C, N, "native", Tagged<C>>;
+        type I = Names<C, N, "interface", Landed<C>>;
+        type G = Names<C, N, "interface", Tunneled<C>>;
+        type PolicyName = Names<C, N, "import", Importing<C>> | Names<C, N, "export", Key<C>>;
+        type Group = Names<C, N, "group", Grouped<C>>;
+
+        const names: UpstreamNames = options.names ?? {};
         const all = Object.entries(catalog) as [Key<C>, Upstream][];
         const nameOf = (key: string, upstream: Upstream) => upstream.name ?? key;
-        const policy = (key: string) => key.toUpperCase();
         const grouped = (upstream: Upstream) => upstream.role === "rs" || Boolean(upstream.multihop);
 
+        /** The name built for one upstream: its pattern with the key, the key in capitals and its number filled in. */
+        const named = (field: Field, key: string, upstream: Upstream): string => {
+            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);
+                });
+        };
+
+        // Two upstreams under one name would replace each other on the device.
+        for (const field of Object.keys(DEFAULTS) as Field[]) {
+            const taken = new Map<string, string>();
+
+            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: string, upstream: Upstream) => named("vlan", key, upstream) as V;
+        const native = (key: string, upstream: Upstream) => named("native", key, upstream) as T;
+        const policy = (direction: "import" | "export", key: string, upstream: Upstream) => named(direction, key, upstream) as PolicyName;
+
         /** Each landed upstream's VLAN; with a device, the VLANs and natives of those arriving on its ports. */
         const vlans = <const D extends string | undefined = undefined>(device?: D) => {
             const result: Record<string, Vlan> = {};
@@ -126,33 +249,33 @@ export class Upstreams {
                 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`,
                     };
                 }
             }
 
-            return result as D extends string ? { [K in V]: Vlan } & { [K in T as Native<K>]: Vlan } : { [K in V]: Vlan };
+            return result as D extends string ? { [K in V]: Vlan } & { [K in T]: Vlan } : { [K in V]: Vlan };
         };
 
         const vlansOn = (device: string) =>
-            all.filter(([, upstream]) => upstream.handoff?.port?.device === device).map(([key]) => key as V);
+            all.filter(([, upstream]) => upstream.handoff?.port?.device === device).map(([key, upstream]) => vlan(key, upstream));
 
         const ports = (device: string) => {
-            const result: Record<string, Port<V | Native<T>, never, never, never>> = {};
+            const result: Record<string, Port<V | T, never, never, never>> = {};
 
             for (const [key, upstream] of all) {
                 const handoff = upstream.handoff;
                 if (!handoff?.port || handoff.port.device !== device) continue;
 
                 result[handoff.port.port] = {
-                    description: nameOf(key, upstream),
+                    description: names.port ? names.port(key, upstream) : nameOf(key, upstream),
                     ...(handoff.native !== undefined
-                        ? { trunk_vlans: [key as V], native_vlan: `${key}-native` as Native<T> }
-                        : { access_vlan: key as V }),
+                        ? { 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 } : {}),
@@ -167,26 +290,31 @@ export class Upstreams {
 
             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 as V, description, addresses, ...(exchange ? { exchange } : {}) };
+                    result[name] = { type: "vlan", vlan: vlan(key, upstream), description, addresses, ...(exchange ? { exchange } : {}) };
                 }
             }
 
-            return result as { [K in V]: VlanInterface<V, never> } & { [K in Tunneled<C>]: Gre<never> };
+            return result as { [K in I]: VlanInterface<V, never> } & { [K in G]: Gre<never> };
         };
 
+        /** The router's interfaces toward the internet: every landed upstream's, for NAT and lists like it. */
+        const uplinks = () =>
+            all.filter(([, upstream]) => upstream.handoff).map(([key, upstream]) => named("interface", key, upstream) as I);
+
         /** What a session or its group takes from its upstream. */
-        const settings = (key: string, upstream: Upstream): NeighborSettings<PolicyName<C>> => ({
+        const settings = (key: string, upstream: Upstream): NeighborSettings<PolicyName> => ({
             remote_as: upstream.asn,
             description: nameOf(key, upstream),
             role: upstream.role,
-            ...(upstream.import ? { import: `${policy(key)}-IN` as PolicyName<C> } : {}),
-            export: `${policy(key)}-OUT` as PolicyName<C>,
+            ...(upstream.import ? { import: policy("import", key, upstream) } : {}),
+            export: policy("export", key, upstream),
         });
 
         const groups = () =>
@@ -196,7 +324,7 @@ export class Upstreams {
                     .map(([key, upstream]) => {
                         const multihop = upstream.multihop;
                         return [
-                            key,
+                            named("group", key, upstream),
                             {
                                 ...settings(key, upstream),
                                 ...(multihop
@@ -210,7 +338,7 @@ export class Upstreams {
                             },
                         ];
                     })
-            ) as Record<Grouped<C>, NeighborSettings<PolicyName<C>>>;
+            ) as Record<Group, NeighborSettings<PolicyName>>;
 
         const neighbors = () =>
             Object.fromEntries(
@@ -221,19 +349,19 @@ export 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 } : {}),
                             },
                         ];
                     })
                 )
-            ) as Record<string, Neighbor<PolicyName<C>, Grouped<C>>>;
+            ) as Record<string, Neighbor<PolicyName, Group>>;
 
         const policies = <const P extends string = never>(options: UpstreamPolicies<P> = {}) => {
             const result: Record<string, PolicyRule<P, never>[]> = {};
 
             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),
@@ -243,7 +371,7 @@ export 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 } : {}) })
                         : []),
@@ -259,16 +387,20 @@ export class Upstreams {
                 ];
             }
 
-            return result as Record<PolicyName<C>, PolicyRule<P, never>[]>;
+            return result as Record<PolicyName, PolicyRule<P, never>[]>;
         };
 
         /** The VLANs straight off an upstream, natives included: `untrusted` for `Checks.trustBoundary`. */
-        const untrusted = () => [...all.filter(([, upstream]) => upstream.handoff).map(([key]) => key as V), ...natives()];
+        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]) => `${key}-native` as Native<T>);
+            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]) => key as V);
+        const privateDrops = () =>
+            all.filter(([, upstream]) => upstream.handoff && upstream.drop_private).map(([key, upstream]) => vlan(key, upstream));
 
         const tunnelRules = (): FilterRule<never, never>[] =>
             all.flatMap(([key, upstream]) =>
@@ -293,6 +425,7 @@ export class Upstreams {
             vlansOn,
             ports,
             interfaces,
+            uplinks,
             groups,
             neighbors,
             policies,

package/src/schema/interfaces.ts

@@ -113,7 +113,7 @@ export type Port<V extends string, A extends string, L extends string, F extends
         acl?: A;
         /** The LAG this port is in. Every other setting goes on the LAG. */
         lag?: L;
-        /** Another of our devices at the other end of the cable. */
+        /** Another of our devices at the other end of the cable. Without a `description`, the port is described from it: the far device and the far port as printed on it, such as `firewall-1 port6`. */
         link?: Link;
     };
 

package/dist/chunks/index-6wb41q67.js

@@ -1,62 +0,0 @@
-// 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)));
-  }
-}
-
-export { Catalog };