@classytic/stage 0.3.0 → 0.4.0

package/dist/networking/models/airtime.mjs

@@ -0,0 +1,130 @@
+//#region src/networking/models/airtime.ts
+/**
+* One channel, several devices, and the thing everyone is actually sharing.
+*
+* A switch gives every port its own wire. Wi-Fi gives everybody the same air, so devices take turns,
+* and what they are taking turns at is TIME rather than bandwidth. That one substitution explains the
+* most confusing thing about a home network: a laptop sitting beside the router, showing a perfect
+* signal, can be slow because of a phone in a distant bedroom.
+*
+* The mechanism has a name, the 802.11 performance anomaly, and it is worth stating precisely because
+* it is so counter-intuitive. The access point gives each device roughly the same number of turns.
+* A device with a weak signal negotiates a low data rate, so ITS turn takes far longer to deliver the
+* same bytes. While that turn runs, nobody else may transmit at all. With one device at 260 Mbps and
+* one at 15 Mbps, the fast device does not get 260: both end up near 14, because the slow device is
+* occupying the channel for most of every round.
+*
+* So chapter 1 is not finished when a room reaches a usable signal. A room that is merely usable
+* drags down every other room, and the fix for a slow house is often to improve the WORST corner
+* rather than to buy a faster router. That is the opposite of what the advertising suggests and it
+* follows from one line of arithmetic.
+*/
+/**
+* Bits carried in one transmission opportunity.
+*
+* Not one frame. Modern Wi-Fi aggregates dozens of frames into a single transmission, precisely
+* because the fixed cost below would otherwise dominate at high rates. Modelling a lone 1500-byte
+* frame would show a 300 Mbps link delivering 60 Mbps, which is what 802.11 looked like twenty years
+* ago and would teach an efficiency problem that has since been solved.
+*/
+const PAYLOAD_BITS = 8 * 1500 * 32;
+/**
+* Fixed cost of taking a turn, in microseconds.
+*
+* Contention, the gap before transmitting, the preamble and the acknowledgement. It is paid per turn
+* regardless of how fast the device is, which is why it hurts fast devices most and why aggregation
+* exists.
+*/
+const TURN_OVERHEAD_US = 200;
+/**
+* Data rate a device negotiates from its signal, in Mbps.
+*
+* A staircase rather than a curve, because rate selection is a ladder of modulation schemes and a
+* device drops a whole rung at a time. The figures are for a two-stream client on a modern 5 GHz
+* channel. The shape is what matters: rate holds up and then falls off a cliff, so a room that is
+* merely "usable" is already several rungs down.
+*/
+function rateFromRssi(rssiDbm) {
+	if (rssiDbm >= -50) return 400;
+	if (rssiDbm >= -58) return 260;
+	if (rssiDbm >= -65) return 150;
+	if (rssiDbm >= -70) return 80;
+	if (rssiDbm >= -75) return 40;
+	if (rssiDbm >= -80) return 15;
+	if (rssiDbm >= -85) return 6;
+	return 0;
+}
+/**
+* Share the channel between devices that all want to send at once.
+*
+* Each device gets an equal number of turns, so a round is the sum of everyone's turn length, and
+* every device delivers one payload per round. That is why the effective rates come out EQUAL: the
+* arithmetic makes the fast device wait through the slow one's turn, every round, forever.
+*/
+function shareAirtime(clients) {
+	const active = clients.filter((client) => rateFromRssi(client.rssiDbm) > 0);
+	if (!active.length) return {
+		shares: [],
+		totalMbps: 0,
+		aloneMbps: 0,
+		worstShare: 0
+	};
+	const turns = active.map((client) => {
+		const rateMbps = rateFromRssi(client.rssiDbm);
+		return {
+			client,
+			rateMbps,
+			turnUs: 200 + PAYLOAD_BITS / rateMbps
+		};
+	});
+	const roundUs = turns.reduce((sum, turn) => sum + turn.turnUs, 0);
+	const perClientMbps = PAYLOAD_BITS / roundUs;
+	const shares = turns.map((turn) => ({
+		client: turn.client,
+		rateMbps: turn.rateMbps,
+		turnUs: turn.turnUs,
+		airtimeShare: turn.turnUs / roundUs,
+		effectiveMbps: perClientMbps
+	}));
+	const fastest = turns.reduce((best, turn) => turn.rateMbps > best.rateMbps ? turn : best, turns[0]);
+	return {
+		shares,
+		totalMbps: perClientMbps * active.length,
+		aloneMbps: PAYLOAD_BITS / fastest.turnUs,
+		worstShare: Math.max(...shares.map((share) => share.airtimeShare))
+	};
+}
+/** A device's signal placed into words, so a share can be read without decoding dBm. */
+function signalWord(rssiDbm) {
+	if (rssiDbm >= -58) return "beside the router";
+	if (rssiDbm >= -67) return "same floor";
+	if (rssiDbm >= -75) return "through a wall";
+	if (rssiDbm >= -85) return "far bedroom";
+	return "out of range";
+}
+/** A household worth arguing about: three healthy devices and one in the corner that is not. */
+const HOUSEHOLD = [
+	{
+		id: "desk",
+		label: "Laptop by the router",
+		rssiDbm: -45
+	},
+	{
+		id: "sofa",
+		label: "TV in the living room",
+		rssiDbm: -60
+	},
+	{
+		id: "kitchen",
+		label: "Phone in the kitchen",
+		rssiDbm: -68
+	},
+	{
+		id: "far",
+		label: "Tablet in the far bedroom",
+		rssiDbm: -82
+	}
+];
+
+//#endregion
+export { HOUSEHOLD, PAYLOAD_BITS, TURN_OVERHEAD_US, rateFromRssi, shareAirtime, signalWord };

package/dist/networking/models/cellular.d.mts

@@ -0,0 +1,157 @@
+//#region src/networking/models/cellular.d.ts
+/**
+ * Mobile generations, as a trade rather than a league table.
+ *
+ * "5G is faster than 4G" is the whole of what most students are told, and it explains nothing they
+ * can see. It does not explain why their 5G phone shows 4G indoors, why coverage maps are patchy in
+ * exactly the places the advertising features, or why an operator would keep a twenty-year-old
+ * 900 MHz band running at all.
+ *
+ * The thing that explains all three is that a generation is not one number, it is a position on a
+ * trade. A higher frequency has more spectrum free, so it carries more data. The same higher
+ * frequency travels less far, so its cell is smaller. Cell area falls with the SQUARE of the radius,
+ * so a modest drop in reach multiplies the number of towers needed to cover the same city. Capacity
+ * is bought with civil engineering, and that is why the rollout looks the way it does.
+ *
+ * The second half is the part even the trade press gets wrong. What 5G actually changed is LATENCY,
+ * not throughput. 4G already carries 4K video comfortably; what it cannot do is answer in ten
+ * milliseconds. Anything interactive at a distance, which now includes every request to a model that
+ * streams its answer back, is bounded by the round trip and not by the bit rate. A learner who has
+ * seen the reachable region expand downward rather than rightward owns that distinction.
+ */
+/** Speed of light is not needed here; the propagation model is empirical. */
+type GenerationId = "1g" | "2g" | "3g" | "4g" | "5g" | "5g-mmwave";
+interface Generation {
+  id: GenerationId;
+  label: string;
+  /** First widely deployed. */
+  year: number;
+  /** A representative band, in MHz, for the radius model. */
+  megahertz: number;
+  /** What a user realistically gets, in Mbps. 1G carried no data at all. */
+  typicalMbps: number;
+  /**
+   * Round trip to the first server, in ms. The number that decides how a thing FEELS.
+   *
+   * Meaningless for 1G, which had no data service to measure, and quoted there only so the field is
+   * total. Read it alongside `typicalMbps`: a generation carrying no data has no round trip either.
+   */
+  latencyMs: number;
+  /**
+   * How a voice call is carried.
+   *
+   * Worth its own field rather than being folded into the data rate, because for most of this
+   * history a call was NOT data. It rode a dedicated circuit held open for its whole duration,
+   * which is why a call connected on a 2G network that could not load a web page, and why a phone
+   * showing one bar can still ring. Voice became data only with VoLTE.
+   */
+  voice: "analogue-circuit" | "digital-circuit" | "over-data";
+  note: string;
+}
+/**
+ * Representative bands and realistic user-experienced figures, not peak laboratory numbers.
+ *
+ * Quoting peaks is how the marketing gets away with it. A 5G peak of several gigabits is real and
+ * nobody has ever seen it on a phone, so the typical column below is what a learner should compare.
+ */
+declare const GENERATIONS: Generation[];
+/**
+ * Link budget for a macro cell, in dB.
+ *
+ * A base station transmits around 43 dBm into an antenna with roughly 18 dBi of gain, and a handset
+ * stops working near -100 dBm. The difference is how much loss the path is allowed to introduce.
+ */
+declare const MAX_PATH_LOSS_DB = 161;
+type Terrain = "city" | "suburb" | "open";
+interface TerrainSpec {
+  id: Terrain;
+  label: string;
+  /** Extra loss in dB beyond the base model: buildings cost reach. */
+  extraDb: number;
+  note: string;
+}
+declare const TERRAIN: Record<Terrain, TerrainSpec>;
+/**
+ * Cell radius in km, from the COST-231 Hata model for a 30 m base station antenna.
+ *
+ *   PL = 46.3 + 33.9·log10(f) - 13.82·log10(h) + (44.9 - 6.55·log10(h))·log10(d) + C
+ *
+ * Solved for d at the maximum tolerable path loss. This is the model a network planner actually
+ * reaches for, which is why it is worth using rather than inventing a curve: at 900 MHz it returns
+ * cells of several kilometres and at 28 GHz a few hundred metres, and both match what is deployed.
+ *
+ * It is specified only up to about 2 GHz, so the millimetre-wave figure is an extrapolation. It
+ * lands in the right place for the wrong reasons, and a learner should be told that rather than
+ * shown a number that looks authoritative.
+ */
+declare function cellRadiusKm(megahertz: number, terrain?: Terrain): number;
+/**
+ * Path loss at a distance, in dB, from the same model the cell radius comes from.
+ *
+ * Exposed because the next chapter needs the loss at every point along a road rather than only at
+ * the edge of a cell. Deriving both from one pair of coefficients is the whole reason to factor it
+ * out: a handover lab built on a second, slightly different propagation model would put its cell
+ * boundaries in a different place from the coverage lab, and a learner comparing the two figures
+ * would be looking at a discrepancy we invented.
+ */
+declare function pathLossDb(distanceKm: number, megahertz: number, terrain?: Terrain): number;
+/**
+ * Effective radiated power of a macro cell, in dBm, and the level below which a handset gives up.
+ *
+ * Their difference is `MAX_PATH_LOSS_DB`, which is what makes the cell radius and the signal level
+ * along a road two views of one calculation rather than two separate claims.
+ */
+declare const EIRP_DBM = 61;
+declare const HANDSET_SENSITIVITY_DBM: number;
+/** Signal a handset sees from one mast at a given distance, in dBm. */
+declare const rssiFromMast: (distanceKm: number, megahertz: number, terrain?: Terrain) => number;
+/**
+ * Area one cell serves, in km².
+ *
+ * Cells are drawn as hexagons because hexagons tile a plane with no gaps and no overlap, and are the
+ * closest tiling shape to the circle a transmitter actually produces. A regular hexagon whose
+ * circumradius is r has area 3√3/2 · r², which is about 2.598 r².
+ */
+declare const cellAreaKm2: (radiusKm: number) => number;
+/**
+ * Towers needed to cover an area.
+ *
+ * This is the number that carries the lesson, because it goes as 1/r². Halving the reach does not
+ * double the tower count, it quadruples it, and that single square is most of the economics of every
+ * rollout since 3G.
+ */
+declare const towersFor: (areaKm2: number, radiusKm: number) => number;
+interface Task {
+  id: string;
+  label: string;
+  /** Sustained rate the task needs, in Mbps. */
+  needMbps: number;
+  /** Round trip the task tolerates before it stops feeling usable, in ms. */
+  needLatencyMs: number;
+  /**
+   * True when a dedicated voice circuit can carry this instead of the data service.
+   *
+   * Only a phone call qualifies, and it is the reason every generation serves one. Without this the
+   * model says 1G could not make a call, which is exactly backwards: making calls was the only
+   * thing it did.
+   */
+  onVoiceCircuit?: boolean;
+  note: string;
+}
+/**
+ * Things a person actually tries to do, with the two numbers each of them needs.
+ *
+ * Two numbers rather than one, because that is the whole point. A task fails if either the rate or
+ * the round trip is missing, and the tasks that separate the recent generations fail on LATENCY
+ * while having rate to spare.
+ */
+declare const TASKS: Task[];
+type Blocker = "rate" | "latency" | "both" | null;
+/** Why a generation cannot serve a task, or null when it can. Naming the blocker IS the lesson. */
+declare function blockedBy(generation: Generation, task: Task): Blocker;
+declare const canServe: (generation: Generation, task: Task) => boolean;
+/** The first generation able to serve a task, which is the honest way to date a capability. */
+declare function firstGenerationFor(task: Task): Generation | undefined;
+declare const generationById: (id: string) => Generation;
+//#endregion
+export { Blocker, EIRP_DBM, GENERATIONS, Generation, GenerationId, HANDSET_SENSITIVITY_DBM, MAX_PATH_LOSS_DB, TASKS, TERRAIN, Task, Terrain, TerrainSpec, blockedBy, canServe, cellAreaKm2, cellRadiusKm, firstGenerationFor, generationById, pathLossDb, rssiFromMast, towersFor };

package/dist/networking/models/cellular.mjs

@@ -0,0 +1,252 @@
+//#region src/networking/models/cellular.ts
+/**
+* Representative bands and realistic user-experienced figures, not peak laboratory numbers.
+*
+* Quoting peaks is how the marketing gets away with it. A 5G peak of several gigabits is real and
+* nobody has ever seen it on a phone, so the typical column below is what a learner should compare.
+*/
+const GENERATIONS = [
+	{
+		id: "1g",
+		label: "1G",
+		year: 1981,
+		megahertz: 450,
+		typicalMbps: 0,
+		latencyMs: 500,
+		voice: "analogue-circuit",
+		note: "Analogue voice, and nothing else. There was no data service to be slow, and anyone with a scanner could listen to a call."
+	},
+	{
+		id: "2g",
+		label: "2G",
+		year: 1991,
+		megahertz: 900,
+		typicalMbps: .05,
+		latencyMs: 600,
+		voice: "digital-circuit",
+		note: "Digital, which brought encryption and SMS. Data arrived later as GPRS, and at these rates a single photograph was a genuine wait."
+	},
+	{
+		id: "3g",
+		label: "3G",
+		year: 2001,
+		megahertz: 2100,
+		typicalMbps: 2,
+		latencyMs: 150,
+		voice: "digital-circuit",
+		note: "The web on a phone, and the first video calls. The move to 2100 MHz is where cells started shrinking and tower counts started climbing."
+	},
+	{
+		id: "4g",
+		label: "4G LTE",
+		year: 2009,
+		megahertz: 1800,
+		typicalMbps: 50,
+		latencyMs: 50,
+		voice: "over-data",
+		note: "Enough for HD video, which is most of what anyone does. Operators deliberately used lower bands here, buying back the reach that 3G had spent."
+	},
+	{
+		id: "5g",
+		label: "5G mid band",
+		year: 2019,
+		megahertz: 3500,
+		typicalMbps: 300,
+		latencyMs: 10,
+		voice: "over-data",
+		note: "The real 5G most people meet. The headline is the data rate and the change that matters is the latency, which is five times better."
+	},
+	{
+		id: "5g-mmwave",
+		label: "5G millimetre wave",
+		year: 2019,
+		megahertz: 28e3,
+		typicalMbps: 1e3,
+		latencyMs: 8,
+		voice: "over-data",
+		note: "Enormous capacity over a few hundred metres. Deployed at stadiums and transport hubs, because covering a city this way is not affordable."
+	}
+];
+/**
+* Link budget for a macro cell, in dB.
+*
+* A base station transmits around 43 dBm into an antenna with roughly 18 dBi of gain, and a handset
+* stops working near -100 dBm. The difference is how much loss the path is allowed to introduce.
+*/
+const MAX_PATH_LOSS_DB = 161;
+const TERRAIN = {
+	city: {
+		id: "city",
+		label: "Dense city",
+		extraDb: 3,
+		note: "Tall buildings block and reflect. Cells are smallest here, and it is also where the most people need serving."
+	},
+	suburb: {
+		id: "suburb",
+		label: "Suburb",
+		extraDb: -5,
+		note: "Lower buildings and more open ground, so the same equipment reaches noticeably further."
+	},
+	open: {
+		id: "open",
+		label: "Open country",
+		extraDb: -14,
+		note: "Very little in the way. One tower can cover a whole district, which is the only reason rural coverage is affordable at all."
+	}
+};
+/**
+* Cell radius in km, from the COST-231 Hata model for a 30 m base station antenna.
+*
+*   PL = 46.3 + 33.9·log10(f) - 13.82·log10(h) + (44.9 - 6.55·log10(h))·log10(d) + C
+*
+* Solved for d at the maximum tolerable path loss. This is the model a network planner actually
+* reaches for, which is why it is worth using rather than inventing a curve: at 900 MHz it returns
+* cells of several kilometres and at 28 GHz a few hundred metres, and both match what is deployed.
+*
+* It is specified only up to about 2 GHz, so the millimetre-wave figure is an extrapolation. It
+* lands in the right place for the wrong reasons, and a learner should be told that rather than
+* shown a number that looks authoritative.
+*/
+function cellRadiusKm(megahertz, terrain = "city") {
+	const { intercept, slope } = hataTerms(megahertz, terrain);
+	return 10 ** ((161 - intercept) / slope);
+}
+/** The two coefficients of the model, so radius and loss are solved from ONE set of numbers. */
+function hataTerms(megahertz, terrain) {
+	const logH = Math.log10(30);
+	return {
+		intercept: 46.3 + 33.9 * Math.log10(megahertz) - 13.82 * logH + TERRAIN[terrain].extraDb,
+		slope: 44.9 - 6.55 * logH
+	};
+}
+/**
+* Path loss at a distance, in dB, from the same model the cell radius comes from.
+*
+* Exposed because the next chapter needs the loss at every point along a road rather than only at
+* the edge of a cell. Deriving both from one pair of coefficients is the whole reason to factor it
+* out: a handover lab built on a second, slightly different propagation model would put its cell
+* boundaries in a different place from the coverage lab, and a learner comparing the two figures
+* would be looking at a discrepancy we invented.
+*/
+function pathLossDb(distanceKm, megahertz, terrain = "city") {
+	const { intercept, slope } = hataTerms(megahertz, terrain);
+	return intercept + slope * Math.log10(Math.max(.02, distanceKm));
+}
+/**
+* Effective radiated power of a macro cell, in dBm, and the level below which a handset gives up.
+*
+* Their difference is `MAX_PATH_LOSS_DB`, which is what makes the cell radius and the signal level
+* along a road two views of one calculation rather than two separate claims.
+*/
+const EIRP_DBM = 61;
+const HANDSET_SENSITIVITY_DBM = 61 - 161;
+/** Signal a handset sees from one mast at a given distance, in dBm. */
+const rssiFromMast = (distanceKm, megahertz, terrain = "city") => 61 - pathLossDb(distanceKm, megahertz, terrain);
+/**
+* Area one cell serves, in km².
+*
+* Cells are drawn as hexagons because hexagons tile a plane with no gaps and no overlap, and are the
+* closest tiling shape to the circle a transmitter actually produces. A regular hexagon whose
+* circumradius is r has area 3√3/2 · r², which is about 2.598 r².
+*/
+const cellAreaKm2 = (radiusKm) => 3 * Math.sqrt(3) / 2 * radiusKm * radiusKm;
+/**
+* Towers needed to cover an area.
+*
+* This is the number that carries the lesson, because it goes as 1/r². Halving the reach does not
+* double the tower count, it quadruples it, and that single square is most of the economics of every
+* rollout since 3G.
+*/
+const towersFor = (areaKm2, radiusKm) => Math.max(1, Math.ceil(areaKm2 / cellAreaKm2(radiusKm)));
+/**
+* Things a person actually tries to do, with the two numbers each of them needs.
+*
+* Two numbers rather than one, because that is the whole point. A task fails if either the rate or
+* the round trip is missing, and the tasks that separate the recent generations fail on LATENCY
+* while having rate to spare.
+*/
+const TASKS = [
+	{
+		id: "voice",
+		label: "Phone call",
+		needMbps: .013,
+		needLatencyMs: 300,
+		onVoiceCircuit: true,
+		note: "A compressed voice codec is about 13 kbps. Every generation since the first carries this easily."
+	},
+	{
+		id: "text",
+		label: "Send a message",
+		needMbps: .001,
+		needLatencyMs: 2e3,
+		note: "Almost free, and tolerant of delay. This is why a text gets through where a call will not connect."
+	},
+	{
+		id: "web",
+		label: "Load a web page",
+		needMbps: 1,
+		needLatencyMs: 1e3,
+		note: "Modest by modern standards. It was the thing 3G was built to make possible."
+	},
+	{
+		id: "video-call",
+		label: "Video call",
+		needMbps: 1.5,
+		needLatencyMs: 200,
+		note: "Needs the round trip as much as the rate. Beyond about 200 ms people start talking over each other."
+	},
+	{
+		id: "hd",
+		label: "Stream HD video",
+		needMbps: 5,
+		needLatencyMs: 2e3,
+		note: "Buffered, so delay barely matters. It needs rate and nothing else, which is why 4G was enough."
+	},
+	{
+		id: "uhd",
+		label: "Stream 4K video",
+		needMbps: 25,
+		needLatencyMs: 2e3,
+		note: "Four times the pixels and still buffered. 4G already carries this, which is worth noticing before believing a 5G advertisement."
+	},
+	{
+		id: "cloud-game",
+		label: "Cloud gaming",
+		needMbps: 15,
+		needLatencyMs: 30,
+		note: "The first ordinary thing that 4G cannot do. Not for want of speed: the round trip is what breaks it."
+	},
+	{
+		id: "agent",
+		label: "A model that answers as you type",
+		needMbps: 2,
+		needLatencyMs: 40,
+		note: "The rate is trivial. How quickly the first words appear is bounded by the round trip, so this lives or dies on latency."
+	},
+	{
+		id: "remote-control",
+		label: "Controlling a machine at a distance",
+		needMbps: 10,
+		needLatencyMs: 10,
+		note: "Remote surgery and industrial control. This is the case 5G was genuinely designed for, and it is a latency requirement."
+	}
+];
+/** Why a generation cannot serve a task, or null when it can. Naming the blocker IS the lesson. */
+function blockedBy(generation, task) {
+	if (task.onVoiceCircuit) return null;
+	const slowRate = generation.typicalMbps < task.needMbps;
+	const slowTrip = generation.latencyMs > task.needLatencyMs;
+	if (slowRate && slowTrip) return "both";
+	if (slowRate) return "rate";
+	if (slowTrip) return "latency";
+	return null;
+}
+const canServe = (generation, task) => blockedBy(generation, task) === null;
+/** The first generation able to serve a task, which is the honest way to date a capability. */
+function firstGenerationFor(task) {
+	return [...GENERATIONS].sort((a, b) => a.year - b.year || a.typicalMbps - b.typicalMbps).find((generation) => canServe(generation, task));
+}
+const generationById = (id) => GENERATIONS.find((item) => item.id === id) ?? GENERATIONS[0];
+
+//#endregion
+export { EIRP_DBM, GENERATIONS, HANDSET_SENSITIVITY_DBM, MAX_PATH_LOSS_DB, TASKS, TERRAIN, blockedBy, canServe, cellAreaKm2, cellRadiusKm, firstGenerationFor, generationById, pathLossDb, rssiFromMast, towersFor };

package/dist/networking/models/encapsulation.d.mts

@@ -0,0 +1,98 @@
+//#region src/networking/models/encapsulation.d.ts
+/**
+ * Encapsulation: what a message actually becomes, and what survives the trip.
+ *
+ * The stack is normally taught as a mnemonic, which is why students can recite seven layer names
+ * and still cannot say what a router changes. Two facts do the real work, and both are checkable:
+ *
+ * 1. Going down, each layer WRAPS what it was given and never edits it. The message you sent is
+ *    still the same bytes at the bottom, sitting inside a few dozen bytes of addressing. For a big
+ *    download that overhead is a rounding error; for a single keystroke it is most of the traffic.
+ *
+ * 2. Going across, the MAC pair is replaced at every routed hop and the IP pair is not. That is the
+ *    whole difference between the two kinds of address: one names the next box on this wire, the
+ *    other names the far end of the journey. Exams ask it constantly and it is nearly always missed.
+ *
+ * The one honest caveat is NAT, which does rewrite the source IP at the boundary of a home or
+ * office network. The scenario here is deliberately inside one organisation so the rule holds
+ * exactly, and the lab says so rather than quietly hoping nobody asks.
+ */
+type LayerKind = "application" | "transport" | "network" | "data-link";
+interface Header {
+  kind: LayerKind;
+  protocol: string;
+  /** Bytes this layer adds. Real sizes: a reader can check them against a capture. */
+  bytes: number;
+  /**
+   * Of those bytes, how many go AFTER the payload. Only Ethernet has any: its 4-byte checksum sits
+   * at the end of the frame, which is the whole reason the word "trailer" exists. Drawing it at the
+   * front would be neater and would teach a frame layout that does not exist.
+   */
+  trailerBytes?: number;
+  /** What kind of address this header carries, if any. */
+  addressing: string | null;
+  /** The question this header exists to answer. */
+  answers: string;
+}
+/** Outermost last: this is the order the headers are ADDED going down the stack. */
+declare const HEADERS: Header[];
+declare const OVERHEAD_BYTES: number;
+interface Encapsulation {
+  payloadBytes: number;
+  headers: Header[];
+  /** Headers added so far, going down. `depth` 0 is the bare message. */
+  depth: number;
+  onWireBytes: number;
+  overheadBytes: number;
+  /** Overhead as a share of what is actually transmitted, 0 to 1. */
+  overheadShare: number;
+}
+/** Wrap a payload in the first `depth` headers. Full depth is the frame that goes on the wire. */
+declare function encapsulate(payloadBytes: number, depth?: number): Encapsulation;
+/** Unwrap one layer. The payload is never touched, which is the point. */
+declare const decapsulate: (state: Encapsulation) => Encapsulation;
+type NodeKind = "host" | "switch" | "router";
+interface PathNode {
+  id: string;
+  name: string;
+  kind: NodeKind;
+  mac: string;
+  /** Hosts have one; routers have one per side, so the scene names them by segment instead. */
+  ip?: string;
+}
+/** How deep a device opens the frame before it can do its job. */
+declare const opensTo: (kind: NodeKind) => LayerKind;
+interface EncapsulationSegment {
+  /** Layer-2 endpoints of this stretch of wire. */
+  fromMac: string;
+  toMac: string;
+  from: PathNode;
+  to: PathNode;
+  /** Switches sit inside a segment without ending it: they are invisible at layer 3. */
+  through: PathNode[];
+}
+/**
+ * Split a path at its layer-3 boundaries. A switch forwards a frame without terminating it, so it
+ * does not start a new segment. A router does, because it builds a brand new frame for the next
+ * wire. The number of segments is therefore routers + 1, however many switches are in the way.
+ */
+declare function segmentsOf(path: PathNode[]): EncapsulationSegment[];
+interface WireFrame {
+  segment: EncapsulationSegment;
+  mac: {
+    from: string;
+    to: string;
+  };
+  /** The same on every segment. That is the whole lesson. */
+  ip: {
+    from: string;
+    to: string;
+  };
+  note: string;
+}
+declare function frameOn(segment: EncapsulationSegment, source: PathNode, destination: PathNode): WireFrame;
+/** Every frame the message travels in, end to end. */
+declare const journey: (path: PathNode[]) => WireFrame[];
+declare const DEFAULT_PATH: PathNode[];
+//#endregion
+export { DEFAULT_PATH, Encapsulation, EncapsulationSegment, HEADERS, Header, LayerKind, NodeKind, OVERHEAD_BYTES, PathNode, WireFrame, decapsulate, encapsulate, frameOn, journey, opensTo, segmentsOf };