@classytic/stage 0.2.0 → 0.4.0

package/dist/circuit/network.mjs

@@ -0,0 +1,440 @@
+import { solveDC } from "./dc.mjs";
+import { findBridgeShape, findDangling as findDangling$1, findParallelGroup, findSelfLoop, findSeriesPair, isReduced, mergedId, validateTopology } from "./topology.mjs";
+
+//#region src/circuit/network.ts
+/**
+* @classytic/stage/circuit/network — Network reduction: turning a circuit nobody can read into one component, one move at a time.
+*
+* A student who can only apply `V = IR` is stuck the moment a question shows six resistors in a
+* shape that is neither series nor parallel. The skill that unsticks them is not algebra, it is
+* SEEING: noticing that two of those components share both ends, or that a node in the middle joins
+* exactly two of them and nothing else, collapsing that pair, and looking again. Do it four times
+* and the shape everyone was afraid of is a single number.
+*
+* That is the skill this kernel models, and the reason it returns a list of steps rather than an
+* answer. `solveDC` in `@classytic/stage/circuit` already returns the answer, correctly, for any
+* network: it assembles a modified nodal analysis matrix and inverts it. What it cannot do is
+* teach, because Gaussian elimination is not how a person reduces a circuit and watching a matrix
+* invert teaches nobody to look at a bridge and think "those two are in parallel".
+*
+* So the two engines do different jobs, and the tests pit them against each other: every reduction
+* this file performs is checked against the MNA solver's independent answer for the same network.
+* The narrative has to be not just readable but RIGHT, and an independent solver is the only honest
+* way to know it is.
+*
+* ── Resistors and capacitors are ONE engine, with the rules swapped ─────────────────────────────
+* Every rule below is about the SHAPE of the network: which components share a node, which node
+* joins only two. Shape does not care what is plugged into it. Only the arithmetic differs, and it
+* differs in exactly one way:
+*
+*              series            parallel
+*   resistance  R₁ + R₂           1/(1/R₁ + 1/R₂)
+*   capacitance 1/(1/C₁ + 1/C₂)   C₁ + C₂
+*
+* which is the single most-confused pair of formulas on the syllabus, precisely because students
+* meet them months apart and memorise them as four unrelated facts. Here they are two facts and a
+* swap, and a student can flip the same drawing between the two and watch which rule moves.
+*
+* The balanced bridge does not even need the swap. Working through the divider ratios, a capacitive
+* bridge balances when C_P/C_Q = C_R/C_S, the SAME form as P/Q = R/S for resistors, because the
+* reciprocal in a capacitor's impedance cancels top and bottom. That is not a coincidence worth
+* hiding; it is why one `findBalancedBridge` serves both.
+*
+* ── The rules, in the order a person actually uses them ─────────────────────────────────────────
+* Order matters for the narrative, not for the answer. These are applied in the sequence an
+* experienced solver reaches for them, so the steps read like someone thinking rather than like a
+* program searching:
+*
+*   1. dangling     a component hanging off a dead end is in no closed loop, so delete it.
+*                   Students lose marks to this one constantly: a branch that leads nowhere is
+*                   still drawn on the page, and it still looks like it must matter.
+*   2. shorted      both ends on the same node, so there is no potential difference across it.
+*                   Same deletion, different reason, and worth separating because the reasons are
+*                   what is being taught.
+*   3. parallel     two or more components sharing BOTH ends.
+*   4. series       a node that is not a terminal and joins exactly two components.
+*   5. bridge       a Wheatstone whose arms balance: P/Q = R/S puts both midpoints at the same
+*                   potential, so the bridging component carries nothing whatever its value, and
+*                   deleting it leaves two simple series pairs in parallel. This is the trick
+*                   question in every admission paper, and the one students most often grind
+*                   through with three simultaneous equations instead.
+*
+* Steps 1-4 alone cannot finish every network; a bridge that does NOT balance defeats all of them,
+* which is exactly why the star-delta transform exists and why `reduce` reports the network it got
+* stuck on rather than pretending.
+*/
+const PHYSICS = {
+	resistance: {
+		symbol: "R",
+		unit: "Ω",
+		unitTex: "\\,\\Omega",
+		seriesAdds: true,
+		seriesReason: "so every coulomb through one must go through the other. Same current means series, and resistances in series add.",
+		parallelReason: "so they share the same potential difference. That is parallel, and the combination is always SMALLER than the smallest of them, because you have opened another path."
+	},
+	capacitance: {
+		symbol: "C",
+		unit: "µF",
+		unitTex: "\\,\\mu\\mathrm{F}",
+		seriesAdds: false,
+		seriesReason: "so the same charge is pushed onto both, while their potential differences add. Equal charge and a bigger total p.d. means a SMALLER capacitance, so capacitors in series combine like resistors in parallel.",
+		parallelReason: "so they share the same potential difference, and each stores its own charge on top of the other. Capacitance in parallel simply ADDS, which is the opposite way round from resistance."
+	}
+};
+const plainSum = (values) => values.reduce((sum, v) => sum + v, 0);
+const reciprocalSum = (values) => 1 / values.reduce((sum, v) => sum + 1 / v, 0);
+/** Combine components that are in series, for this quantity. */
+function combineSeries(quantity, values) {
+	return PHYSICS[quantity].seriesAdds ? plainSum(values) : reciprocalSum(values);
+}
+/** Combine components that are in parallel, for this quantity. */
+function combineParallel(quantity, values) {
+	return PHYSICS[quantity].seriesAdds ? reciprocalSum(values) : plainSum(values);
+}
+const finiteNonNegative = (value, what) => {
+	if (!Number.isFinite(value) || value < 0) throw new RangeError(`${what} must be zero or more`);
+	return value;
+};
+/** A value so small the step narrative should treat it as a degenerate component. */
+const NEGLIGIBLE = 1e-9;
+function validateNetwork(network) {
+	validateTopology({
+		edges: network.components,
+		terminals: network.terminals
+	});
+	if (!(network.quantity in PHYSICS)) throw new RangeError(`unknown quantity ${network.quantity}`);
+	for (const c of network.components) finiteNonNegative(c.value, `component ${c.id}`);
+	return network;
+}
+const clone = (n) => ({
+	quantity: n.quantity,
+	components: n.components.map((c) => ({ ...c })),
+	terminals: [...n.terminals]
+});
+/**
+* The network seen as pure shape, which is what `topology.ts` operates on.
+*
+* A `Component` is already an `Edge` plus a value, so this is a rename rather than a conversion.
+* Every structural question below is asked of the topology and every arithmetic one of the values,
+* which is the split that let the AC engine reuse this walk instead of copying it.
+*/
+const asTopology = (network) => ({
+	edges: network.components,
+	terminals: network.terminals
+});
+/** Look a component back up by the id a topology finder returned. */
+const byId = (network, id) => network.components.find((c) => c.id === id);
+/** Value to 3 decimal places, for the step text only. */
+const show = (value) => String(Math.round(value * 1e3) / 1e3);
+const withComponents = (network, components) => ({
+	quantity: network.quantity,
+	terminals: [...network.terminals],
+	components
+});
+const without = (network, ids) => network.components.filter((c) => !ids.has(c.id)).map((c) => ({ ...c }));
+/**
+* A component with a free end. Not a terminal, joins nothing else, so it sits in no closed loop.
+*
+* Deliberately checked first. A dead-end branch is the cheapest thing on the page to eliminate and
+* the one most likely to frighten a student into thinking the network is bigger than it is.
+*/
+function findDangling(network) {
+	const found = findDangling$1(asTopology(network));
+	if (!found) return null;
+	const c = byId(network, found.edge.id);
+	return {
+		rule: "dangling",
+		consumed: [{ ...c }],
+		produced: null,
+		at: found.node,
+		reason: `Nothing else meets ${found.node}, so ${c.id} is not part of any closed loop. A branch with a dead end can never affect what happens between the terminals, whatever its value.`,
+		arithmetic: "",
+		after: withComponents(network, without(network, new Set([c.id])))
+	};
+}
+/** Both ends on one node: no potential difference across it, so it does nothing. */
+function findShorted(network) {
+	const loop = findSelfLoop(asTopology(network));
+	if (!loop) return null;
+	const c = byId(network, loop.id);
+	return {
+		rule: "shorted",
+		consumed: [{ ...c }],
+		produced: null,
+		at: c.a,
+		reason: `Both ends of ${c.id} are at ${c.a}, so there is no potential difference across it and it plays no part.`,
+		arithmetic: "",
+		after: withComponents(network, without(network, new Set([c.id])))
+	};
+}
+/**
+* Two or more components sharing BOTH ends.
+*
+* Collapsed all at once rather than in pairs. Three components between the same two nodes is a
+* single observation to a person ("those three are all in parallel"), and splitting it into two
+* steps would make the narrative longer than the thought it represents.
+*/
+function findParallel(network) {
+	const topology = asTopology(network);
+	const edges = findParallelGroup(topology);
+	if (!edges) return null;
+	const group = edges.map((e) => byId(network, e.id));
+	const first = group[0];
+	const physics = PHYSICS[network.quantity];
+	const values = group.map((c) => c.value);
+	const value = combineParallel(network.quantity, values);
+	const produced = {
+		id: mergedId(topology, edges),
+		a: first.a,
+		b: first.b,
+		value
+	};
+	const ids = new Set(group.map((c) => c.id));
+	return {
+		rule: "parallel",
+		consumed: group.map((c) => ({ ...c })),
+		produced,
+		at: null,
+		reason: `${group.map((c) => c.id).join(", ")} all run between ${first.a} and ${first.b}, ${physics.parallelReason}`,
+		arithmetic: combineTex(network.quantity, values, value, false),
+		after: withComponents(network, [...without(network, ids), produced])
+	};
+}
+/**
+* A node that is not a terminal and joins exactly two components, so they are in series.
+*
+* The check that it is not a terminal is the whole subtlety. A node joining two components IS a
+* series junction, unless the measurement is being taken there, in which case collapsing it would
+* delete the very point the question asks about.
+*/
+function findSeries(network) {
+	const topology = asTopology(network);
+	const pair = findSeriesPair(topology);
+	if (!pair) return null;
+	const c1 = byId(network, pair.edges[0].id);
+	const c2 = byId(network, pair.edges[1].id);
+	const physics = PHYSICS[network.quantity];
+	const values = [c1.value, c2.value];
+	const value = combineSeries(network.quantity, values);
+	const produced = {
+		id: mergedId(topology, pair.edges),
+		a: pair.ends[0],
+		b: pair.ends[1],
+		value
+	};
+	const ids = new Set([c1.id, c2.id]);
+	return {
+		rule: "series",
+		consumed: [{ ...c1 }, { ...c2 }],
+		produced,
+		at: pair.node,
+		reason: `${pair.node} joins ${c1.id} and ${c2.id} and nothing else, ${physics.seriesReason}`,
+		arithmetic: combineTex(network.quantity, values, value, true),
+		after: withComponents(network, [...without(network, ids), produced])
+	};
+}
+/** The arithmetic, as LaTeX, in whichever of the two forms this combination actually takes. */
+function combineTex(quantity, values, result, series) {
+	const physics = PHYSICS[quantity];
+	const { symbol, unitTex } = physics;
+	if (series === physics.seriesAdds) return `${symbol} = ${values.map(show).join(" + ")} = ${show(result)}${unitTex}`;
+	if (!Number.isFinite(result)) return `\\frac{1}{${symbol}} = \\infty \\Rightarrow ${symbol} = 0`;
+	return `\\frac{1}{${symbol}} = ${values.map((v) => `\\frac{1}{${show(v)}}`).join(" + ")} \\Rightarrow ${symbol} = ${show(result)}${unitTex}`;
+}
+/**
+* A bridge whose arms balance, so the bridging component can be deleted.
+*
+* Detection is structural, not by pattern-matching a drawing: look for a component whose two ends
+* BOTH have degree three, then check whether the four remaining arms form two paths from one
+* terminal to the other through those midpoints. If P/Q = R/S the midpoints sit at equal potential,
+* the bridge carries nothing, and it goes.
+*
+* The SAME ratio test serves capacitance. A capacitive divider puts the midpoint at
+* C_P/(C_P + C_Q) of the supply rather than R_Q/(R_P + R_Q), and setting the two midpoints equal
+* rearranges to C_P/C_Q = C_R/C_S either way, so the reciprocal cancels out of the condition.
+*
+* Worth its own rule rather than leaving it to the star-delta transform, because the insight is the
+* point. A student who spots the balance does the question in two lines; one who does not is
+* looking at three simultaneous equations for the same answer.
+*/
+function findBalancedBridge(network) {
+	const shape = findBridgeShape(asTopology(network));
+	if (!shape) return null;
+	const p = byId(network, shape.p.id);
+	const q = byId(network, shape.q.id);
+	const r = byId(network, shape.r.id);
+	const s = byId(network, shape.s.id);
+	const bridge = byId(network, shape.bridge.id);
+	if (q.value <= 0 || s.value <= 0) return null;
+	const left = p.value / q.value;
+	const right = r.value / s.value;
+	if (Math.abs(left - right) > 1e-9 * Math.max(1, left, right)) return null;
+	return {
+		rule: "balanced-bridge",
+		consumed: [{ ...bridge }],
+		produced: null,
+		at: null,
+		reason: `${p.id}/${q.id} = ${r.id}/${s.id}, so ${shape.m1} and ${shape.m2} sit at the same potential. With no potential difference across it, ${bridge.id} carries nothing and can be removed whatever its value.`,
+		arithmetic: `\\frac{${show(p.value)}}{${show(q.value)}} = \\frac{${show(r.value)}}{${show(s.value)}} = ${show(left)}`,
+		after: withComponents(network, without(network, new Set([bridge.id])))
+	};
+}
+const RULES = [
+	findDangling,
+	findShorted,
+	findParallel,
+	findSeries,
+	findBalancedBridge
+];
+/**
+* Reduce until one component spans the terminals, or until no rule applies.
+*
+* The step cap guards against a rule that fails to shrink the network rather than imposing a real
+* limit: every rule above removes at least one component, so a network of n finishes in under n
+* steps and the cap should never be reached.
+*/
+function reduce(input) {
+	let network = clone(validateNetwork(input));
+	const steps = [];
+	const cap = network.components.length * 4 + 8;
+	while (steps.length < cap) {
+		if (isFinished(network)) break;
+		let applied = null;
+		for (const rule of RULES) {
+			applied = rule(network);
+			if (applied) break;
+		}
+		if (!applied) break;
+		steps.push(applied);
+		network = applied.after;
+	}
+	if (isFinished(network)) {
+		const only = network.components[0];
+		return {
+			steps,
+			value: only ? only.value : 0,
+			stuck: null
+		};
+	}
+	return {
+		steps,
+		value: null,
+		stuck: network
+	};
+}
+/** Finished means exactly one component left, and it spans the terminals. */
+const isFinished = (network) => isReduced(asTopology(network));
+/**
+* Equivalent value straight from the nodal solver: put 1 V across the terminals, read the current,
+* divide.
+*
+* This is what the reduction narrative is checked against. It shares no code with the rules above,
+* which is the entire point: if a rule were wrong, agreeing with itself would prove nothing.
+*
+* A CAPACITANCE network is solved by handing the matrix the elastances, 1/C, as if they were
+* resistances. That is not a trick: a capacitor's impedance is proportional to 1/C, so a network of
+* capacitors combines exactly as a network of resistors of value 1/C does, and inverting the answer
+* gives the equivalent capacitance. It also means capacitance is checked by a solver that has never
+* heard of a capacitor, which is the strongest form this check can take.
+*/
+function equivalentByNodalAnalysis(input) {
+	const network = validateNetwork(input);
+	const [t1, t2] = network.terminals;
+	const asResistance = network.quantity === "resistance";
+	const index = new Map([[t2, 0]]);
+	const idFor = (node) => {
+		const existing = index.get(node);
+		if (existing !== void 0) return existing;
+		const next = index.size;
+		index.set(node, next);
+		return next;
+	};
+	idFor(t1);
+	const elems = network.components.map((c) => {
+		const asOhms = asResistance ? c.value : c.value <= 1e-9 ? Infinity : 1 / c.value;
+		return {
+			kind: "R",
+			n1: idFor(c.a),
+			n2: idFor(c.b),
+			value: Number.isFinite(asOhms) ? Math.max(asOhms, NEGLIGIBLE) : 1 / NEGLIGIBLE,
+			id: c.id
+		};
+	});
+	elems.push({
+		kind: "V",
+		n1: idFor(t1),
+		n2: 0,
+		value: 1,
+		id: "__probe"
+	});
+	const solved = solveDC(elems);
+	if (!solved.ok) return null;
+	const current = solved.current["__probe"];
+	if (current === void 0 || !Number.isFinite(current)) return null;
+	const amps = Math.abs(current);
+	if (amps < 1e-12) return asResistance ? Infinity : 0;
+	const ohms = 1 / amps;
+	return asResistance ? ohms : 1 / ohms;
+}
+/**
+* An UNBALANCED five-component bridge, by the star-delta transform.
+*
+* Series and parallel genuinely cannot touch this network: no two components share both ends, and
+* every internal node joins three. That is not a gap in the rules, it is a fact about the shape,
+* and it is the honest reason star-delta is taught at all.
+*
+* Stated for resistance, which is where the syllabus uses it. The same numbers serve a capacitive
+* bridge if the arms are given as elastances, for the reason spelled out above.
+*/
+function starFromDelta(ab, bc, ca) {
+	const sum = finiteNonNegative(ab, "delta arm") + finiteNonNegative(bc, "delta arm") + finiteNonNegative(ca, "delta arm");
+	if (sum <= 0) return [
+		0,
+		0,
+		0
+	];
+	return [
+		ca * ab / sum,
+		ab * bc / sum,
+		bc * ca / sum
+	];
+}
+function deltaFromStar(a, b, c) {
+	const a0 = finiteNonNegative(a, "star arm");
+	const b0 = finiteNonNegative(b, "star arm");
+	const c0 = finiteNonNegative(c, "star arm");
+	const products = a0 * b0 + b0 * c0 + c0 * a0;
+	if (products <= 0) return [
+		0,
+		0,
+		0
+	];
+	return [
+		products / c0,
+		products / a0,
+		products / b0
+	];
+}
+/**
+* The classic infinite ladder: `series` in each arm and `shunt` across, repeating forever.
+*
+* Solved the way the textbook does, by noticing that adding one more section leaves the network
+* looking exactly as it did:
+*
+*     x = series + (shunt · x) / (shunt + x)
+*
+* which rearranges to a quadratic whose positive root is the answer. Included because it is the one
+* network where the reduction rules are useless and the INSIGHT is the whole method, and because
+* students meet it in every admission paper.
+*/
+function infiniteLadderOhm(series, shunt) {
+	const a = finiteNonNegative(series, "series arm");
+	const b = finiteNonNegative(shunt, "shunt arm");
+	return (a + Math.sqrt(a * a + 4 * a * b)) / 2;
+}
+/** The unit a quantity is quoted in, for a scene that has to label it. */
+const unitFor = (quantity) => PHYSICS[quantity].unit;
+const symbolFor = (quantity) => PHYSICS[quantity].symbol;
+
+//#endregion
+export { NEGLIGIBLE, combineParallel, combineSeries, deltaFromStar, equivalentByNodalAnalysis, infiniteLadderOhm, reduce, starFromDelta, symbolFor, unitFor, validateNetwork };

package/dist/circuit/topology.d.mts

@@ -0,0 +1,102 @@
+//#region src/circuit/topology.d.ts
+/**
+ * @classytic/stage/circuit/topology — The SHAPE of a two-terminal network, with nothing in it.
+ *
+ * Every reduction rule splits cleanly into two halves that have nothing to do with each other:
+ *
+ *   structure   is there a node joining exactly two edges? do two edges share both ends? is there
+ *               an edge whose far end joins nothing?
+ *   arithmetic  given that those two are in series, what is the combined value?
+ *
+ * The first half is identical for resistance, capacitance, impedance, thermal conductance, pipe
+ * flow and anything else that lives on a graph. The second half is the only thing that differs. So
+ * this file owns the first half and knows nothing about ohms, farads or complex numbers.
+ *
+ * ── Why this was extracted ──────────────────────────────────────────────────────────────────────
+ * `network-reduction/core.ts` was written first and carried both halves. Adding AC impedance meant
+ * either writing the same graph walk a second time, against a second set of values, or lifting the
+ * walk out. The walk is fiddly in exactly the places that are easy to get subtly wrong (a series
+ * junction that is also a measurement terminal, a self-loop, a bridge whose midpoints are not both
+ * degree three), and two copies of it would drift.
+ *
+ * ── The one thing deliberately NOT here ─────────────────────────────────────────────────────────
+ * Whether a bridge BALANCES is not a structural question. For resistance it is P/Q = R/S with real
+ * numbers; for impedance it is the same ratio with complex ones, which is a much stronger condition
+ * and the reason a real AC bridge needs two adjustable components rather than one. So this file
+ * finds bridge-shaped subgraphs and each engine decides for itself whether the one it found is
+ * balanced.
+ */
+/** An edge is an identity and two endpoints. What flows along it is somebody else's business. */
+interface Edge {
+  id: string;
+  a: string;
+  b: string;
+}
+interface Topology {
+  edges: readonly Edge[];
+  /** The two nodes the network is measured between. */
+  terminals: readonly [string, string];
+}
+declare function validateTopology(t: Topology): Topology;
+/** Every edge touching each node. A self-loop is listed once, not twice. */
+declare function degrees(t: Topology): Map<string, Edge[]>;
+declare const isTerminal: (t: Topology, node: string) => boolean;
+/** Node pair as an order-independent key, so A-B and B-A collide. */
+declare const pairKey: (edge: Edge) => string;
+/**
+ * An edge with a free end: its far node is not a terminal and nothing else meets there.
+ *
+ * Such an edge lies on no path between the terminals, so nothing can flow along it whatever it is
+ * made of. Reported first because it is the cheapest thing to eliminate.
+ */
+declare function findDangling(t: Topology): {
+  edge: Edge;
+  node: string;
+} | null;
+/** An edge whose two ends are the same node, so it spans nothing. */
+declare function findSelfLoop(t: Topology): Edge | null;
+/** Two or more edges sharing BOTH endpoints. Returned as one group, because that is one observation. */
+declare function findParallelGroup(t: Topology): Edge[] | null;
+interface SeriesPair {
+  /** The node that disappears. */
+  node: string;
+  edges: [Edge, Edge];
+  /** The two far ends, which the replacement edge will span. */
+  ends: [string, string];
+}
+/**
+ * A node that is NOT a terminal and joins exactly two edges.
+ *
+ * The terminal check is the whole subtlety and the easiest thing to omit. A node joining two edges
+ * is a series junction unless the measurement is being taken there, in which case collapsing it
+ * would delete the very point the question asks about.
+ */
+declare function findSeriesPair(t: Topology): SeriesPair | null;
+interface BridgeShape {
+  bridge: Edge;
+  /** The two midpoints the bridge spans. */
+  m1: string;
+  m2: string;
+  /** Arms, named the way every textbook names them: P and Q on one midpoint, R and S on the other. */
+  p: Edge;
+  q: Edge;
+  r: Edge;
+  s: Edge;
+}
+/**
+ * A bridge-SHAPED subgraph: an edge between two degree-three midpoints, each of which reaches each
+ * terminal by exactly one other edge.
+ *
+ * Whether it balances is not asked here, on purpose. That test depends on what the edges are made
+ * of, and for impedance it is a strictly stronger condition than for resistance.
+ */
+declare function findBridgeShape(t: Topology): BridgeShape | null;
+/** One edge left, and it spans the terminals. */
+declare function isReduced(t: Topology): boolean;
+/**
+ * A fresh edge id that cannot collide, built from the ids it replaces so a narrative stays
+ * traceable back to the original drawing.
+ */
+declare function mergedId(t: Topology, from: readonly Edge[]): string;
+//#endregion
+export { BridgeShape, Edge, SeriesPair, Topology, degrees, findBridgeShape, findDangling, findParallelGroup, findSelfLoop, findSeriesPair, isReduced, isTerminal, mergedId, pairKey, validateTopology };

package/dist/circuit/topology.mjs

@@ -0,0 +1,143 @@
+//#region src/circuit/topology.ts
+function validateTopology(t) {
+	if (t.terminals[0] === t.terminals[1]) throw new RangeError("the two terminals must be different nodes");
+	const seen = /* @__PURE__ */ new Set();
+	for (const edge of t.edges) {
+		if (seen.has(edge.id)) throw new RangeError(`duplicate edge id ${edge.id}`);
+		seen.add(edge.id);
+	}
+	return t;
+}
+/** Every edge touching each node. A self-loop is listed once, not twice. */
+function degrees(t) {
+	const out = /* @__PURE__ */ new Map();
+	const push = (node, edge) => out.set(node, [...out.get(node) ?? [], edge]);
+	for (const edge of t.edges) {
+		push(edge.a, edge);
+		if (edge.b !== edge.a) push(edge.b, edge);
+	}
+	return out;
+}
+const isTerminal = (t, node) => node === t.terminals[0] || node === t.terminals[1];
+/** Node pair as an order-independent key, so A-B and B-A collide. */
+const pairKey = (edge) => [edge.a, edge.b].slice().sort().join(" ");
+/**
+* An edge with a free end: its far node is not a terminal and nothing else meets there.
+*
+* Such an edge lies on no path between the terminals, so nothing can flow along it whatever it is
+* made of. Reported first because it is the cheapest thing to eliminate.
+*/
+function findDangling(t) {
+	const deg = degrees(t);
+	for (const edge of t.edges) for (const end of [edge.a, edge.b]) {
+		if (isTerminal(t, end)) continue;
+		if ((deg.get(end) ?? []).length !== 1) continue;
+		return {
+			edge,
+			node: end
+		};
+	}
+	return null;
+}
+/** An edge whose two ends are the same node, so it spans nothing. */
+function findSelfLoop(t) {
+	return t.edges.find((edge) => edge.a === edge.b) ?? null;
+}
+/** Two or more edges sharing BOTH endpoints. Returned as one group, because that is one observation. */
+function findParallelGroup(t) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const edge of t.edges) {
+		if (edge.a === edge.b) continue;
+		const key = pairKey(edge);
+		groups.set(key, [...groups.get(key) ?? [], edge]);
+	}
+	for (const group of groups.values()) if (group.length >= 2) return group;
+	return null;
+}
+/**
+* A node that is NOT a terminal and joins exactly two edges.
+*
+* The terminal check is the whole subtlety and the easiest thing to omit. A node joining two edges
+* is a series junction unless the measurement is being taken there, in which case collapsing it
+* would delete the very point the question asks about.
+*/
+function findSeriesPair(t) {
+	for (const [node, touching] of degrees(t)) {
+		if (isTerminal(t, node)) continue;
+		if (touching.length !== 2) continue;
+		const [e1, e2] = touching;
+		if (e1.id === e2.id) continue;
+		const far = (e) => e.a === node ? e.b : e.a;
+		return {
+			node,
+			edges: [e1, e2],
+			ends: [far(e1), far(e2)]
+		};
+	}
+	return null;
+}
+/**
+* A bridge-SHAPED subgraph: an edge between two degree-three midpoints, each of which reaches each
+* terminal by exactly one other edge.
+*
+* Whether it balances is not asked here, on purpose. That test depends on what the edges are made
+* of, and for impedance it is a strictly stronger condition than for resistance.
+*/
+function findBridgeShape(t) {
+	const deg = degrees(t);
+	const [t1, t2] = t.terminals;
+	for (const bridge of t.edges) {
+		const m1 = bridge.a;
+		const m2 = bridge.b;
+		if (m1 === m2) continue;
+		if (isTerminal(t, m1) || isTerminal(t, m2)) continue;
+		if ((deg.get(m1) ?? []).length !== 3 || (deg.get(m2) ?? []).length !== 3) continue;
+		const arm = (mid, term) => {
+			const found = (deg.get(mid) ?? []).filter((e) => e.id !== bridge.id && (e.a === term || e.b === term));
+			return found.length === 1 ? found[0] : null;
+		};
+		const p = arm(m1, t1);
+		const q = arm(m1, t2);
+		const r = arm(m2, t1);
+		const s = arm(m2, t2);
+		if (!p || !q || !r || !s) continue;
+		if (new Set([
+			p.id,
+			q.id,
+			r.id,
+			s.id
+		]).size !== 4) continue;
+		return {
+			bridge,
+			m1,
+			m2,
+			p,
+			q,
+			r,
+			s
+		};
+	}
+	return null;
+}
+/** One edge left, and it spans the terminals. */
+function isReduced(t) {
+	if (t.edges.length !== 1) return false;
+	const only = t.edges[0];
+	const [t1, t2] = t.terminals;
+	return only.a === t1 && only.b === t2 || only.a === t2 && only.b === t1;
+}
+/**
+* A fresh edge id that cannot collide, built from the ids it replaces so a narrative stays
+* traceable back to the original drawing.
+*/
+function mergedId(t, from) {
+	const taken = new Set(t.edges.map((e) => e.id));
+	const base = from.map((e) => e.id).join("");
+	let id = base;
+	let n = 2;
+	while (taken.has(id)) id = `${base}_${n++}`;
+	return id;
+}
+
+//#endregion
+export { degrees, findBridgeShape, findDangling, findParallelGroup, findSelfLoop, findSeriesPair, isReduced, isTerminal, mergedId, pairKey, validateTopology };