@ceralive/modem-control 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ceralive/modem-control",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"type": "module",
 	"description": "Cellular modem control for CeraLive — ModemManager D-Bus backend, NetworkManager adapter, desired-state reconciler, USB composition-mode model, data-usage sampler.",
 	"license": "AGPL-3.0",

package/src/backend/device-classifier.ts

@@ -9,6 +9,14 @@
 // `mm-managed`; a bare vendor-specific interface with no recognized driver is NOT a
 // modem. `pending-modeswitch` is a DISTINCT state (a modem installer awaiting
 // `usb_modeswitch`), never conflated with `unmanaged`.
+//
+// SCOPE — USB ONLY: the whole input here is a `UsbDeviceSnapshot`, a udev/sysfs view of a
+// USB device. PCIe modems are out of scope by construction and get NO entry in this model —
+// a PCI `vendor:device` pair is never smuggled in as a pseudo-USB identity. The Fibocom
+// FM350 is the canonical example: it is a PCIe module (PCI `14c3:4d75`, bound by the
+// `mtk_t7xx` driver on the `wwan`/`net` subsystems, with no USB VID:PID), so it is
+// documented-deferred rather than classified here. See `docs/FM350-DECISION.md` for the
+// evidence and the three-gate ledger behind that decision.
 
 import type { CanonicalUsbMode, ExpectedDescriptors } from '../usb-mode';
 

package/src/backend/features.test.ts

@@ -22,6 +22,10 @@ describe('parseMmVersion', () => {
 		expect(parseMmVersion('1.24.0')).toEqual({ major: 1, minor: 24 });
 	});
 
+	test('parses the 1.24.2 FM350-fix release', () => {
+		expect(parseMmVersion('1.24.2')).toEqual({ major: 1, minor: 24 });
+	});
+
 	test('parses major.minor without a patch', () => {
 		expect(parseMmVersion('1.20')).toEqual({ major: 1, minor: 20 });
 	});

package/src/ports/forbidden-surface.test.ts

@@ -3,13 +3,22 @@
 // The single most safety-critical constraint in the package (Must-NOT-Have: "no MM
 // Simple.Connect / CreateBearer / Bearer.Connect calls ever"). Interfaces are
 // erased at runtime, so the enforcement is a source scan: every port `.ts` file is
-// stripped of comments (so prose mentions of "bearer" never trip it) and checked
-// for a method declaration whose name is `connect`, `simpleConnect`, or contains
-// "bearer". Adding such a method to any port fails this test — and therefore CI.
+// parsed with the TypeScript compiler API and each DECLARED member of an interface,
+// type literal, or class is checked for a name that is `connect`, `simpleConnect`,
+// or contains "bearer". Adding such a member to any port fails this test — and CI.
+//
+// The detector walks the real AST rather than the source text, so it catches shapes
+// a naive regex cannot: method signatures, property signatures typed as function
+// types, get/set accessors, optional members, and quoted or computed string-literal
+// member names (`'connect'()`, `['connect']()`) all resolve to their true name. It
+// only ever inspects member NAMES on those three declaration kinds — never string
+// literal values, value-position object-literal keys, comments, local variables, or
+// call expressions — so prose mentions of "bearer" and value keys never trip it.
 
 import { expect, test } from 'bun:test';
 import { readdirSync } from 'node:fs';
 import { join } from 'node:path';
+import * as ts from 'typescript';
 
 const portsDir = import.meta.dir;
 
@@ -18,11 +27,82 @@ function isForbiddenMethodName(name: string): boolean {
 	return lower === 'connect' || lower === 'simpleconnect' || lower.includes('bearer');
 }
 
+/**
+ * Resolve a declared member's name node to its static string name, or `undefined`
+ * when the name is not statically knowable (e.g. a computed `[Symbol.iterator]` or a
+ * computed reference to a non-literal identifier). Plain identifiers, private names,
+ * string / numeric literals, and computed names wrapping a string / numeric literal
+ * (`['connect']`) all resolve to their real text.
+ */
+function resolveMemberName(name: ts.Node): string | undefined {
+	if (ts.isIdentifier(name) || ts.isPrivateIdentifier(name)) {
+		return name.text;
+	}
+	if (ts.isStringLiteralLike(name) || ts.isNumericLiteral(name)) {
+		return name.text;
+	}
+	if (ts.isComputedPropertyName(name)) {
+		const { expression } = name;
+		if (ts.isStringLiteralLike(expression) || ts.isNumericLiteral(expression)) {
+			return expression.text;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Every DECLARED member name of an interface, type literal, or class in `source`,
+ * parsed via the TypeScript compiler API. Value-position object-literal keys, string
+ * literal values, comments, local variables, and call expressions are all excluded —
+ * only the port's actual type surface is inspected. Method signatures, property
+ * signatures (including arrow-typed properties), get/set accessors, optional members,
+ * and quoted / computed string-literal member names are all resolved to their name.
+ */
+function declaredMemberNames(source: string): string[] {
+	const sourceFile = ts.createSourceFile(
+		'port.ts',
+		source,
+		ts.ScriptTarget.Latest,
+		/* setParentNodes */ true,
+	);
+	const names: string[] = [];
+
+	const collectMembers = (members: readonly (ts.TypeElement | ts.ClassElement)[]): void => {
+		for (const member of members) {
+			if (member.name === undefined) {
+				continue;
+			}
+			const resolved = resolveMemberName(member.name);
+			if (resolved !== undefined) {
+				names.push(resolved);
+			}
+		}
+	};
+
+	const visit = (node: ts.Node): void => {
+		if (
+			ts.isInterfaceDeclaration(node) ||
+			ts.isClassDeclaration(node) ||
+			ts.isClassExpression(node) ||
+			ts.isTypeLiteralNode(node)
+		) {
+			collectMembers(node.members);
+		}
+		ts.forEachChild(node, visit);
+	};
+
+	visit(sourceFile);
+	return names;
+}
+
+// The retired regex detector — kept ONLY so the differential test below can prove,
+// by running it, that the AST rebuild is a strict improvement (it caught just one of
+// the seven forbidden shapes). Not used by any real-port scan; do not reintroduce.
 function stripComments(source: string): string {
 	return source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '');
 }
 
-function declaredMemberNames(source: string): string[] {
+function legacyRegexMemberNames(source: string): string[] {
 	const names: string[] = [];
 	const methodDecl = /(?:^|\n)\s*([a-zA-Z_$][\w$]*)\s*[<(]/g;
 	let match = methodDecl.exec(source);
@@ -44,14 +124,14 @@ function portSourceFiles(): string[] {
 
 test('no port source declares a bearer / connect method', async () => {
 	for (const file of portSourceFiles()) {
-		const source = stripComments(await Bun.file(join(portsDir, file)).text());
+		const source = await Bun.file(join(portsDir, file)).text();
 		const forbidden = declaredMemberNames(source).filter(isForbiddenMethodName);
-		expect(forbidden, `forbidden method(s) in ${file}: ${forbidden.join(', ')}`).toEqual([]);
+		expect(forbidden, `forbidden member(s) in ${file}: ${forbidden.join(', ')}`).toEqual([]);
 	}
 });
 
 test('the ModemManager port source declares the expected non-bearer mutations', async () => {
-	const source = stripComments(await Bun.file(join(portsDir, 'modem-manager.ts')).text());
+	const source = await Bun.file(join(portsDir, 'modem-manager.ts')).text();
 	const names = declaredMemberNames(source);
 	for (const expected of [
 		'setRadioModes',
@@ -66,15 +146,96 @@ test('the ModemManager port source declares the expected non-bearer mutations',
 	}
 });
 
-test('the detector actually catches a bearer / connect method (self-test)', () => {
+test('the detector catches every forbidden member shape (self-test)', () => {
+	// Each line is a DISTINCT declaration shape the AST resolver must catch: a plain
+	// method, a computed string-literal method, a quoted string-literal method, an
+	// optional method, a get accessor, a set accessor, and an arrow-typed property.
+	// `setRadioModes` is a legitimate mutation that must pass through unflagged.
 	const rogue = `
-		export interface Rogue {
+		export interface RogueSurface {
 			connect(): Promise<void>;
-			createBearer(): Promise<void>;
-			bearerConnect(): Promise<void>;
+			['simpleConnect'](): void;
+			'createBearer'(): void;
+			bearerReset?(): void;
+			get bearerState(): number;
+			set bearerTarget(value: number);
+			bearerHook: () => Promise<void>;
+			setRadioModes(): Promise<void>;
+		}
+	`;
+	const flagged = declaredMemberNames(rogue).filter(isForbiddenMethodName).sort();
+	expect(flagged).toEqual([
+		'bearerHook',
+		'bearerReset',
+		'bearerState',
+		'bearerTarget',
+		'connect',
+		'createBearer',
+		'simpleConnect',
+	]);
+	// The acceptance bar for the rebuild: at least seven distinct forbidden shapes.
+	expect(flagged.length).toBeGreaterThanOrEqual(7);
+});
+
+test('the detector ignores string values, value-position keys, and non-forbidden members', () => {
+	// Three negative fixtures that must NOT trip the detector:
+	//   1. `reconnectPolicy` — a real interface member whose name merely CONTAINS the
+	//      substring "connect"; the predicate matches "connect" exactly, not as a
+	//      substring, so it must pass (proves the predicate is not overly broad).
+	//   2. `description: '…bearer…'` — a member whose string-literal VALUE contains
+	//      "bearer"; only member NAMES are inspected, never string content.
+	//   3. `bearerConnect: true` — a key in a value-position object literal, not a
+	//      type-level member declaration; the AST never walks object-literal keys.
+	const negative = `
+		interface LegitPort {
+			reconnectPolicy: RetryPolicy;
 			setRadioModes(): Promise<void>;
+			description: 'manages bearer state internally';
+		}
+		const runtimeConfig = {
+			bearerConnect: true,
+			description: 'manages bearer state internally',
+		};
+	`;
+	const members = declaredMemberNames(negative);
+	expect(members).toContain('reconnectPolicy');
+	expect(members).not.toContain('bearerConnect');
+	expect(members.filter(isForbiddenMethodName)).toEqual([]);
+});
+
+test('the AST detector catches member shapes the legacy regex missed (differential)', () => {
+	// The same rogue surface, run through BOTH detectors. The retired regex only ever
+	// matched an identifier immediately followed by `(` or `<` at a line start, so it
+	// caught the single plain method and missed the other six shapes. The AST walk
+	// catches all seven — the strict improvement the rebuild delivers.
+	const rogue = `
+		export interface RogueSurface {
+			connect(): Promise<void>;
+			['simpleConnect'](): void;
+			'createBearer'(): void;
+			bearerReset?(): void;
+			get bearerState(): number;
+			set bearerTarget(value: number);
+			bearerHook: () => Promise<void>;
 		}
 	`;
-	const flagged = declaredMemberNames(stripComments(rogue)).filter(isForbiddenMethodName).sort();
-	expect(flagged).toEqual(['bearerConnect', 'connect', 'createBearer']);
+	const legacyFlagged = legacyRegexMemberNames(stripComments(rogue))
+		.filter(isForbiddenMethodName)
+		.sort();
+	const astFlagged = declaredMemberNames(rogue).filter(isForbiddenMethodName).sort();
+
+	// The regex caught only the plain method.
+	expect(legacyFlagged).toEqual(['connect']);
+	// The AST catches every shape the regex missed, and then some.
+	for (const missed of [
+		'bearerHook',
+		'bearerReset',
+		'bearerState',
+		'bearerTarget',
+		'createBearer',
+		'simpleConnect',
+	]) {
+		expect(legacyFlagged).not.toContain(missed);
+		expect(astFlagged).toContain(missed);
+	}
 });

package/src/transport/calls.ts

@@ -0,0 +1,113 @@
+// Method-call dispatch and reply correlation for the D-Bus transport seam.
+//
+// A call marshals its body through the codec, registers a pending record so a bus drop can
+// reject it, and installs a per-call reply callback guarded by a `done` flag — so a reply
+// that arrives after the call already timed out or the connection dropped is silently
+// ignored rather than mis-correlated onto a stale promise. `rejectAll` mass-rejects every
+// in-flight call when the connection drops.
+
+import { decodeBody, encodeBody } from './codec';
+import { messageType, type RawBus, type RawMessage, type ReplyContext } from './dbus-native';
+import { DisconnectedError, TransportError } from './errors';
+import type { DbusValue, MethodCall, MethodReply } from './types';
+
+export const DEFAULT_CALL_TIMEOUT_MS = 30_000;
+
+interface PendingCall {
+	settle(): void;
+	reject(error: unknown): void;
+}
+
+export class CallDispatcher {
+	readonly #pending = new Set<PendingCall>();
+	readonly #callTimeoutMs: number;
+
+	constructor(callTimeoutMs: number) {
+		this.#callTimeoutMs = callTimeoutMs;
+	}
+
+	async call(bus: RawBus | null, connected: boolean, call: MethodCall): Promise<MethodReply> {
+		if (!connected || bus === null) {
+			throw new DisconnectedError('cannot call method: transport not connected');
+		}
+
+		const signature = call.signature ?? '';
+		const args = call.args ?? [];
+		const message: RawMessage = {
+			type: messageType.methodCall,
+			destination: call.destination,
+			path: call.path,
+			interface: call.interface,
+			member: call.member,
+		};
+		if (signature.length > 0) {
+			// Throws UnsupportedSignatureError / BigIntRequiredError before anything hits
+			// the wire.
+			message.signature = signature;
+			message.body = encodeBody(signature, args);
+		}
+
+		const timeoutMs = call.timeoutMs ?? this.#callTimeoutMs;
+		const pendingSet = this.#pending;
+		return new Promise<MethodReply>((resolve, reject) => {
+			let done = false;
+			const pending: PendingCall = {
+				settle: finish,
+				reject: (error) => {
+					finish();
+					reject(error);
+				},
+			};
+
+			function finish(): void {
+				if (done) {
+					return;
+				}
+				done = true;
+				clearTimeout(timer);
+				pendingSet.delete(pending);
+			}
+
+			const timer = setTimeout(() => {
+				finish();
+				reject(
+					new TransportError(
+						`Method call ${call.interface}.${call.member} timed out after ${timeoutMs}ms`,
+					),
+				);
+			}, timeoutMs);
+
+			pendingSet.add(pending);
+
+			bus.invoke(
+				message,
+				function reply(this: ReplyContext, error: unknown, ...body: unknown[]): void {
+					if (done) {
+						// Reply arrived after timeout/disconnect already settled the promise — ignore.
+						return;
+					}
+					finish();
+					if (error) {
+						reject(error instanceof Error ? error : new TransportError(String(error)));
+						return;
+					}
+					try {
+						const replySignature = this.signature ?? '';
+						const decoded: DbusValue[] =
+							replySignature.length > 0 ? decodeBody(replySignature, body) : [];
+						resolve({ signature: replySignature, body: decoded });
+					} catch (decodeError) {
+						reject(decodeError);
+					}
+				},
+			);
+		});
+	}
+
+	rejectAll(cause: unknown): void {
+		for (const pending of this.#pending) {
+			pending.reject(cause);
+		}
+		this.#pending.clear();
+	}
+}

package/src/transport/characterization.test.ts

@@ -0,0 +1,260 @@
+// Characterization tests for the transport seam's reconnect / call-correlation / ordering
+// edges — the behaviour that a later refactor (splitting transport.ts into lifecycle,
+// call-dispatch, and signal modules) MUST preserve byte-for-byte at the observable level.
+//
+// These pin CURRENT behaviour, not aspirational behaviour: each assertion records what the
+// unsplit transport.ts actually does today. If the split changes any of these observable
+// facts, one of these tests goes red — which is the whole point.
+//
+// Like reliability.test.ts, these run against dedicated private `dbus-daemon` instances
+// (each test owns one) so a destructive kill/restart is safe. That also makes the file
+// self-contained — it needs no outer `dbus-run-session`.
+
+import { describe, expect, test } from 'bun:test';
+import { createDbusTransport } from './index';
+import { FAKE_IFACE, FAKE_PATH, startFakeService, TICK_MEMBER } from './test-support/fake-service';
+import { PrivateBus } from './test-support/private-bus';
+
+const HAS_DBUS_DAEMON = Bun.which('dbus-daemon') !== null;
+
+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function waitFor(predicate: () => boolean, timeoutMs: number, label: string): Promise<void> {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		if (predicate()) {
+			return;
+		}
+		await sleep(10);
+	}
+	throw new Error(`timed out after ${timeoutMs}ms waiting for ${label}`);
+}
+
+const tickSpec = { interface: FAKE_IFACE, member: TICK_MEMBER, path: FAKE_PATH };
+
+describe.skipIf(!HAS_DBUS_DAEMON)('transport characterization', () => {
+	// (i) A call that times out, then the real reply lands AFTER the timeout already
+	// settled the promise. The late reply must be silently ignored (each `bus.invoke`
+	// owns its own reply closure, guarded by a `done` flag) — no crash, and no
+	// mis-correlation onto a later, unrelated call.
+	test('a reply arriving after the call already timed out is silently ignored', async () => {
+		const bus = new PrivateBus();
+		await bus.start();
+		const fake = await startFakeService({ socket: bus.socket });
+		const transport = createDbusTransport({ socket: bus.socket, reconnect: { enabled: false } });
+		let errorEvents = 0;
+		transport.on('error', () => {
+			errorEvents += 1;
+		});
+		await transport.connect();
+
+		// SlowPing replies after 400ms; the call's own timeout is 100ms, so it times out
+		// first and the reply becomes a "late" one 300ms later.
+		await expect(
+			transport.callMethod({
+				destination: fake.busName,
+				path: FAKE_PATH,
+				interface: FAKE_IFACE,
+				member: 'SlowPing',
+				signature: 'u',
+				args: [400],
+				timeoutMs: 100,
+			}),
+		).rejects.toThrow('timed out after 100ms');
+
+		// Wait well past the 400ms reply so the ignored late reply has actually been
+		// delivered to (and dropped by) the settled callback.
+		await sleep(500);
+
+		// No crash, no error event, still connected — the late reply disturbed nothing.
+		expect(errorEvents).toBe(0);
+		expect(transport.isConnected()).toBe(true);
+
+		// And the pending machinery is intact: a fresh call correlates to its OWN reply,
+		// proving the late reply was not mis-delivered to a later promise.
+		const reply = await transport.callMethod({
+			destination: fake.busName,
+			path: FAKE_PATH,
+			interface: FAKE_IFACE,
+			member: 'Ping',
+		});
+		expect(reply.body[0]).toBe('pong');
+
+		await transport.disconnect();
+		await fake.stop();
+		await bus.stop();
+	});
+
+	// (ii) A bus drop while a call is in flight. The in-flight call must reject, and the
+	// observed ordering is pinned: the `disconnected` event is delivered BEFORE the call
+	// rejection is observed. (In `#handleDrop`, pending calls are rejected and then
+	// `disconnected` is emitted synchronously — but a promise rejection is observed on a
+	// microtask, so the synchronous event listener runs first.)
+	test('a mid-call bus drop rejects the in-flight call after emitting disconnected', async () => {
+		const bus = new PrivateBus();
+		await bus.start();
+		const fake = await startFakeService({ socket: bus.socket });
+		const transport = createDbusTransport({ socket: bus.socket, reconnect: { enabled: false } });
+
+		const order: string[] = [];
+		let rejection: unknown = null;
+		transport.on('disconnected', () => order.push('disconnected'));
+		await transport.connect();
+
+		// A call that will never get a reply — the bus dies under it.
+		const call = transport
+			.callMethod({
+				destination: fake.busName,
+				path: FAKE_PATH,
+				interface: FAKE_IFACE,
+				member: 'SlowPing',
+				signature: 'u',
+				args: [5000],
+			})
+			.catch((error: unknown) => {
+				order.push('call-rejected');
+				rejection = error;
+			});
+
+		// Give the call time to reach the wire, then drop the bus under it.
+		await sleep(30);
+		bus.kill();
+
+		await waitFor(
+			() => order.includes('disconnected') && order.includes('call-rejected'),
+			5000,
+			'disconnected + call rejection',
+		);
+		await call;
+
+		// Pinned ordering: the event precedes the observed rejection.
+		expect(order).toEqual(['disconnected', 'call-rejected']);
+		// Pinned rejection type: a DisconnectedError (the connection-end drop cause).
+		expect(rejection).toBeInstanceOf(Error);
+		expect((rejection as Error).name).toBe('DisconnectedError');
+
+		await transport.disconnect();
+		// The fake died with its bus; stopping it would write to a closed stream. Leave it.
+		await bus.stop();
+	});
+
+	// (iii) A drop that arrives while a reconnect is already running. The reconnect loop is
+	// idempotent: `#handleDrop` early-returns whenever the state is already `disconnected`
+	// or `reconnecting`, so repeated low-level drop signals never spawn a second reconnect
+	// loop. The transport converges to a single connected state — exactly one `disconnected`
+	// and one `reconnected`, no error, and it is not wedged.
+	test('a drop during an in-flight reconnect does not double-schedule or wedge', async () => {
+		const bus = new PrivateBus();
+		await bus.start();
+		let fake = await startFakeService({ socket: bus.socket });
+		const transport = createDbusTransport({
+			socket: bus.socket,
+			reconnect: { initialDelayMs: 25, maxDelayMs: 100 },
+		});
+
+		const events: string[] = [];
+		let errorEvents = 0;
+		transport.on('disconnected', () => events.push('disconnected'));
+		transport.on('reconnected', () => events.push('reconnected'));
+		transport.on('error', () => {
+			errorEvents += 1;
+		});
+		await transport.connect();
+
+		const ticks: bigint[] = [];
+		const subscription = await transport.subscribeSignal(tickSpec, (event) => {
+			ticks.push(event.body[0] as bigint);
+		});
+
+		fake.emitTick(11n);
+		await waitFor(() => ticks.includes(11n), 3000, 'pre-drop tick');
+
+		// Drop the bus and leave it down long enough for the reconnect loop to spin through
+		// several failed establish attempts before the bus returns.
+		bus.kill();
+		await waitFor(() => events.includes('disconnected'), 5000, 'disconnected');
+		await sleep(150);
+		await bus.start();
+		await waitFor(() => events.includes('reconnected'), 15000, 'reconnected');
+
+		// A settle window to catch any spurious extra event from a double-scheduled loop.
+		await sleep(300);
+
+		expect(events.filter((event) => event === 'disconnected')).toHaveLength(1);
+		expect(events.filter((event) => event === 'reconnected')).toHaveLength(1);
+		expect(errorEvents).toBe(0);
+
+		// Not wedged: a fresh producer's signal flows through the auto-resubscribed rule.
+		fake = await startFakeService({ socket: bus.socket });
+		fake.emitTick(22n);
+		await waitFor(() => ticks.includes(22n), 8000, 'post-reconnect tick');
+		expect(transport.subscriptionCount()).toBe(1);
+
+		await subscription.unsubscribe();
+		await transport.disconnect();
+		await fake.stop();
+		await bus.stop();
+	}, 30000);
+
+	// (iv) A subscription added AND one removed while a reconnect is in progress. Because
+	// mutating a subscription while disconnected only touches the in-memory match-rule
+	// refcount (the bus call is skipped when not connected), and `#establish()` re-issues
+	// every live rule on reconnect, the refcounting must end up correct: the added
+	// subscription is registered (receives signals) and the removed one is not.
+	test('subscriptions mutated during reconnect end up correctly (un)registered', async () => {
+		const bus = new PrivateBus();
+		await bus.start();
+		const transport = createDbusTransport({
+			socket: bus.socket,
+			reconnect: { initialDelayMs: 25, maxDelayMs: 100 },
+		});
+
+		const events: string[] = [];
+		transport.on('disconnected', () => events.push('disconnected'));
+		transport.on('reconnected', () => events.push('reconnected'));
+		await transport.connect();
+
+		// `removed` is a path-filtered rule; `added` is a distinct (no-path) rule that still
+		// matches the same emitted Tick — so their match-rule strings differ and are tracked
+		// independently.
+		const removedTicks: bigint[] = [];
+		const addedTicks: bigint[] = [];
+		const removed = await transport.subscribeSignal(tickSpec, (event) => {
+			removedTicks.push(event.body[0] as bigint);
+		});
+		expect(transport.subscriptionCount()).toBe(1);
+
+		// Drop the bus; while the reconnect loop is running, mutate the subscription set.
+		bus.kill();
+		await waitFor(() => events.includes('disconnected'), 5000, 'disconnected');
+
+		await removed.unsubscribe();
+		const added = await transport.subscribeSignal(
+			{ interface: FAKE_IFACE, member: TICK_MEMBER },
+			(event) => {
+				addedTicks.push(event.body[0] as bigint);
+			},
+		);
+		expect(transport.subscriptionCount()).toBe(1);
+
+		// Bring the bus back; `#establish()` re-issues exactly the rules still in the
+		// refcount map — the `added` one, not the `removed` one.
+		await bus.start();
+		await waitFor(() => events.includes('reconnected'), 15000, 'reconnected');
+
+		const fake = await startFakeService({ socket: bus.socket });
+		fake.emitTick(33n);
+		await waitFor(() => addedTicks.includes(33n), 8000, 'added-subscription tick');
+
+		// Grace to prove the removed subscription genuinely receives nothing.
+		await sleep(200);
+		expect(addedTicks).toEqual([33n]);
+		expect(removedTicks).toEqual([]);
+		expect(transport.subscriptionCount()).toBe(1);
+
+		await added.unsubscribe();
+		await transport.disconnect();
+		await fake.stop();
+		await bus.stop();
+	}, 30000);
+});

package/src/transport/no-library-leak.test.ts

@@ -6,6 +6,7 @@
 // fallback `@particle/dbus-next`) must stay invisible to every caller.
 
 import { expect, test } from 'bun:test';
+import { readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import * as transportPublic from './index';
 
@@ -26,11 +27,21 @@ test('the transport public entry does not import or re-export the D-Bus library'
 });
 
 test('only the quarantined facade imports the D-Bus library from production modules', async () => {
-	const productionModules = ['transport.ts', 'codec.ts', 'signature.ts', 'errors.ts', 'types.ts'];
+	// Enumerate every non-test production module in transport/ dynamically, so a NEW module
+	// (e.g. a future transport split) that imports the library directly is caught — the old
+	// fixed list never knew about files it did not name. The importer set must be EXACTLY the
+	// sanctioned facade, `dbus-native.ts`.
+	const productionModules = readdirSync(transportDir).filter(
+		(name) => name.endsWith('.ts') && !name.endsWith('.test.ts'),
+	);
+	const importers: string[] = [];
 	for (const moduleName of productionModules) {
 		const source = await Bun.file(join(transportDir, moduleName)).text();
-		expect(source).not.toContain(LIBRARY_IMPORT);
+		if (source.includes(LIBRARY_IMPORT)) {
+			importers.push(moduleName);
+		}
 	}
+	expect(importers.sort()).toEqual(['dbus-native.ts']);
 });
 
 test('the transport public surface exposes only the seam\u2019s own values', () => {

package/src/transport/signals.ts

@@ -0,0 +1,150 @@
+// Signal subscription and match-rule tracking for the D-Bus transport seam.
+//
+// The transport's single persistent `message` listener fans out here: `dispatch` walks the
+// live subscription registry and delivers each decoded signal to every matching listener.
+// Match rules are refcounted so N subscriptions sharing a rule add/remove it on the bus
+// exactly once, and `reissueRules` re-adds every live rule after a reconnect — so
+// subscribing/unsubscribing never grows the connection's listener count (the 100-cycle
+// leak check depends on this).
+
+import { decodeBody } from './codec';
+import { messageType, type RawBus, type RawMessage } from './dbus-native';
+import type { DbusValue, SignalEvent, SignalListener, SignalSpec, Subscription } from './types';
+
+// The live connection context the registry reads through. The transport supplies these so
+// the registry always sees the current bus/connected state (which change across reconnects)
+// rather than capturing a stale reference, and routes decode/listener failures to the
+// transport's `error` event.
+export interface SignalHost {
+	currentBus(): RawBus | null;
+	isConnected(): boolean;
+	emitError(error: unknown): void;
+}
+
+interface SubscriptionRecord {
+	readonly id: number;
+	readonly spec: SignalSpec;
+	readonly listener: SignalListener;
+	readonly rule: string;
+}
+
+function buildMatchRule(spec: SignalSpec): string {
+	const parts = [`type='signal'`, `interface='${spec.interface}'`, `member='${spec.member}'`];
+	if (spec.path !== undefined) {
+		parts.push(`path='${spec.path}'`);
+	}
+	if (spec.sender !== undefined) {
+		parts.push(`sender='${spec.sender}'`);
+	}
+	return parts.join(',');
+}
+
+function signalMatches(spec: SignalSpec, message: RawMessage): boolean {
+	if (message.interface !== spec.interface || message.member !== spec.member) {
+		return false;
+	}
+	if (spec.path !== undefined && message.path !== spec.path) {
+		return false;
+	}
+	if (spec.sender !== undefined && message.sender !== spec.sender) {
+		return false;
+	}
+	return true;
+}
+
+export class SignalRegistry {
+	readonly #host: SignalHost;
+	readonly #subscriptions = new Map<number, SubscriptionRecord>();
+	readonly #matchRuleRefcount = new Map<string, number>();
+	#nextSubId = 1;
+
+	constructor(host: SignalHost) {
+		this.#host = host;
+	}
+
+	async subscribe(spec: SignalSpec, listener: SignalListener): Promise<Subscription> {
+		const rule = buildMatchRule(spec);
+		const id = this.#nextSubId++;
+		this.#subscriptions.set(id, { id, spec, listener, rule });
+		await this.#addMatchRule(rule);
+
+		let removed = false;
+		return {
+			unsubscribe: async (): Promise<void> => {
+				if (removed) {
+					return;
+				}
+				removed = true;
+				this.#subscriptions.delete(id);
+				await this.#removeMatchRule(rule);
+			},
+		};
+	}
+
+	count(): number {
+		return this.#subscriptions.size;
+	}
+
+	// Re-issue every live match rule against a freshly established bus so a reconnect
+	// resubscribes transparently. Called by `#establish` before it swaps in the new bus, so
+	// the fresh bus is passed in explicitly rather than read from the host.
+	async reissueRules(bus: RawBus): Promise<void> {
+		for (const rule of this.#matchRuleRefcount.keys()) {
+			await bus.addMatch(rule);
+		}
+	}
+
+	dispatch(message: RawMessage): void {
+		if (message.type !== messageType.signal) {
+			return;
+		}
+		for (const record of this.#subscriptions.values()) {
+			if (!signalMatches(record.spec, message)) {
+				continue;
+			}
+			let body: DbusValue[];
+			try {
+				const signature = message.signature ?? '';
+				body = signature.length > 0 ? decodeBody(signature, message.body ?? []) : [];
+			} catch (error) {
+				this.#host.emitError(error);
+				continue;
+			}
+			const event: SignalEvent = {
+				path: message.path ?? '',
+				interface: message.interface ?? '',
+				member: message.member ?? '',
+				sender: message.sender,
+				signature: message.signature ?? '',
+				body,
+			};
+			try {
+				record.listener(event);
+			} catch (error) {
+				this.#host.emitError(error);
+			}
+		}
+	}
+
+	async #addMatchRule(rule: string): Promise<void> {
+		const current = this.#matchRuleRefcount.get(rule) ?? 0;
+		this.#matchRuleRefcount.set(rule, current + 1);
+		const bus = this.#host.currentBus();
+		if (current === 0 && this.#host.isConnected() && bus) {
+			await bus.addMatch(rule);
+		}
+	}
+
+	async #removeMatchRule(rule: string): Promise<void> {
+		const current = this.#matchRuleRefcount.get(rule) ?? 0;
+		if (current <= 1) {
+			this.#matchRuleRefcount.delete(rule);
+			const bus = this.#host.currentBus();
+			if (current === 1 && this.#host.isConnected() && bus) {
+				await bus.removeMatch(rule).catch(() => undefined);
+			}
+		} else {
+			this.#matchRuleRefcount.set(rule, current - 1);
+		}
+	}
+}

package/src/transport/test-support/fake-service.ts

@@ -106,16 +106,40 @@ export async function startFakeService(options: FakeServiceOptions): Promise<Fak
 	// surface an unhandled EventEmitter 'error' from this helper's dead connection.
 	bus.connection.on('error', () => undefined);
 
+	// A reconnect/drop test kills the bus and ABANDONS this fake (stopping it would itself
+	// write to the closed stream). Any reply the library still owes — e.g. a SlowPing whose
+	// delay has not elapsed — would then be written to that dead stream when its timer
+	// fires, throwing "Can't write a message to a closed stream" ASYNCHRONOUSLY, seconds
+	// later, inside whatever unrelated test happens to be running. Track the reply timers
+	// and cancel them the instant the connection stream ends, so a dead fake never writes.
+	const pendingReplyTimers = new Set<ReturnType<typeof setTimeout>>();
+	const clearPendingReplies = (): void => {
+		for (const timer of pendingReplyTimers) {
+			clearTimeout(timer);
+		}
+		pendingReplyTimers.clear();
+	};
+	bus.connection.on('end', clearPendingReplies);
+
 	const define = (member: string, impl: MethodImpl, resultSignature: string): void => {
 		bus.setMethodCallHandler(FAKE_PATH, FAKE_IFACE, member, [impl, resultSignature]);
 	};
 
 	define('Ping', () => 'pong', 's');
 	// The library awaits a Promise returned by a handler, so this replies after a delay —
-	// used to prove a late reply still resolves the caller's method call.
+	// used to prove a late reply still resolves the caller's method call. The timer is
+	// tracked so a bus drop before it fires cancels the owed reply instead of writing it
+	// to a closed stream.
 	define(
 		'SlowPing',
-		(delayMs) => new Promise((resolve) => setTimeout(() => resolve('pong'), Number(delayMs))),
+		(delayMs) =>
+			new Promise((resolve) => {
+				const timer = setTimeout(() => {
+					pendingReplyTimers.delete(timer);
+					resolve('pong');
+				}, Number(delayMs));
+				pendingReplyTimers.add(timer);
+			}),
 		's',
 	);
 	define('GetManagedObjects', () => managedObjectsValue(), 'a{oa{sa{sv}}}');
@@ -137,6 +161,7 @@ export async function startFakeService(options: FakeServiceOptions): Promise<Fak
 			bus.sendSignal(FAKE_PATH, FAKE_IFACE, TICK_MEMBER, 't', [seq.toString()]);
 		},
 		async stop(): Promise<void> {
+			clearPendingReplies();
 			await bus.disconnect().catch(() => undefined);
 		},
 	};

package/src/transport/transport.ts

@@ -1,29 +1,26 @@
 // The D-Bus transport seam implementation.
 //
-// Wraps `@httptoolkit/dbus-native` behind the `DbusTransport` interface: method calls,
-// signal subscriptions, and an automatic reconnect loop that re-issues every match rule
-// after a bus restart. A single persistent `message` listener fans out to the live
-// subscription registry, so subscribing/unsubscribing never grows the connection's
-// listener count — the 100-cycle leak check depends on this.
+// Wraps `@httptoolkit/dbus-native` behind the `DbusTransport` interface. This module owns the
+// connection lifecycle — handshake, a reconnect loop that re-issues every match rule after a
+// bus restart, and teardown — and delegates method-call dispatch to `./calls` and signal
+// subscription/match-rule tracking to `./signals`. Its single `message` listener fans out to
+// the signal registry, so subscribing never grows the listener count (the 100-cycle leak check).
 
 import { EventEmitter } from 'node:events';
-import { decodeBody, encodeBody } from './codec';
+import { CallDispatcher, DEFAULT_CALL_TIMEOUT_MS } from './calls';
 import {
 	type CreateClientOptions,
 	createClient,
-	messageType,
 	type RawBus,
 	type RawMessage,
-	type ReplyContext,
 } from './dbus-native';
 import { DisconnectedError, TransportError } from './errors';
+import { SignalRegistry } from './signals';
 import type {
 	DbusTransport,
 	DbusTransportOptions,
-	DbusValue,
 	MethodCall,
 	MethodReply,
-	SignalEvent,
 	SignalListener,
 	SignalSpec,
 	Subscription,
@@ -39,19 +36,6 @@ interface ResolvedReconnect {
 	readonly maxAttempts: number;
 }
 
-interface SubscriptionRecord {
-	readonly id: number;
-	readonly spec: SignalSpec;
-	readonly listener: SignalListener;
-	readonly rule: string;
-}
-
-interface PendingCall {
-	settle(): void;
-	reject(error: unknown): void;
-}
-
-const DEFAULT_CALL_TIMEOUT_MS = 30_000;
 // Bound a single connect/auth attempt so a stalled handshake cannot freeze the reconnect
 // loop. A local unix-socket D-Bus connect completes in milliseconds; 2s is ample headroom
 // while keeping reconnect responsive after a bus restart.
@@ -65,46 +49,19 @@ const DEFAULT_RECONNECT: ResolvedReconnect = {
 
 const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
 
-function buildMatchRule(spec: SignalSpec): string {
-	const parts = [`type='signal'`, `interface='${spec.interface}'`, `member='${spec.member}'`];
-	if (spec.path !== undefined) {
-		parts.push(`path='${spec.path}'`);
-	}
-	if (spec.sender !== undefined) {
-		parts.push(`sender='${spec.sender}'`);
-	}
-	return parts.join(',');
-}
-
-function signalMatches(spec: SignalSpec, message: RawMessage): boolean {
-	if (message.interface !== spec.interface || message.member !== spec.member) {
-		return false;
-	}
-	if (spec.path !== undefined && message.path !== spec.path) {
-		return false;
-	}
-	if (spec.sender !== undefined && message.sender !== spec.sender) {
-		return false;
-	}
-	return true;
-}
-
 class DbusTransportImpl implements DbusTransport {
 	readonly #options: DbusTransportOptions;
 	readonly #reconnect: ResolvedReconnect;
-	readonly #callTimeoutMs: number;
 	readonly #emitter = new EventEmitter();
-	readonly #subscriptions = new Map<number, SubscriptionRecord>();
-	readonly #matchRuleRefcount = new Map<string, number>();
-	readonly #pending = new Set<PendingCall>();
+	readonly #calls: CallDispatcher;
+	readonly #signals: SignalRegistry;
 
 	#bus: RawBus | null = null;
 	#state: State = 'idle';
 	#closing = false;
-	#nextSubId = 1;
 
 	// Bound once so the same references can be detached from a dead connection.
-	readonly #onMessage = (message: RawMessage): void => this.#dispatchSignal(message);
+	readonly #onMessage = (message: RawMessage): void => this.#signals.dispatch(message);
 	readonly #onConnectionError = (cause: unknown): void =>
 		this.#handleDrop(cause instanceof Error ? cause : new DisconnectedError(String(cause)));
 	readonly #onConnectionEnd = (): void =>
@@ -112,7 +69,12 @@ class DbusTransportImpl implements DbusTransport {
 
 	constructor(options: DbusTransportOptions) {
 		this.#options = options;
-		this.#callTimeoutMs = options.callTimeoutMs ?? DEFAULT_CALL_TIMEOUT_MS;
+		this.#calls = new CallDispatcher(options.callTimeoutMs ?? DEFAULT_CALL_TIMEOUT_MS);
+		this.#signals = new SignalRegistry({
+			currentBus: () => this.#bus,
+			isConnected: () => this.#state === 'connected',
+			emitError: (error) => this.#emitter.emit('error', error),
+		});
 		this.#reconnect = {
 			enabled: options.reconnect?.enabled ?? DEFAULT_RECONNECT.enabled,
 			initialDelayMs: options.reconnect?.initialDelayMs ?? DEFAULT_RECONNECT.initialDelayMs,
@@ -144,113 +106,23 @@ class DbusTransportImpl implements DbusTransport {
 		this.#state = 'closed';
 		const bus = this.#bus;
 		this.#bus = null;
-		this.#rejectPending(new DisconnectedError('transport closed'));
+		this.#calls.rejectAll(new DisconnectedError('transport closed'));
 		if (bus) {
 			this.#quiesce(bus);
 			await bus.disconnect().catch(() => undefined);
 		}
 	}
 
-	async callMethod(call: MethodCall): Promise<MethodReply> {
-		const bus = this.#bus;
-		if (this.#state !== 'connected' || bus === null) {
-			throw new DisconnectedError('cannot call method: transport not connected');
-		}
-
-		const signature = call.signature ?? '';
-		const args = call.args ?? [];
-		const message: RawMessage = {
-			type: messageType.methodCall,
-			destination: call.destination,
-			path: call.path,
-			interface: call.interface,
-			member: call.member,
-		};
-		if (signature.length > 0) {
-			// Throws UnsupportedSignatureError / BigIntRequiredError before anything hits
-			// the wire.
-			message.signature = signature;
-			message.body = encodeBody(signature, args);
-		}
-
-		const timeoutMs = call.timeoutMs ?? this.#callTimeoutMs;
-		const pendingSet = this.#pending;
-		return new Promise<MethodReply>((resolve, reject) => {
-			let done = false;
-			const pending: PendingCall = {
-				settle: finish,
-				reject: (error) => {
-					finish();
-					reject(error);
-				},
-			};
-
-			function finish(): void {
-				if (done) {
-					return;
-				}
-				done = true;
-				clearTimeout(timer);
-				pendingSet.delete(pending);
-			}
-
-			const timer = setTimeout(() => {
-				finish();
-				reject(
-					new TransportError(
-						`Method call ${call.interface}.${call.member} timed out after ${timeoutMs}ms`,
-					),
-				);
-			}, timeoutMs);
-
-			pendingSet.add(pending);
-
-			bus.invoke(
-				message,
-				function reply(this: ReplyContext, error: unknown, ...body: unknown[]): void {
-					if (done) {
-						// Reply arrived after timeout/disconnect already settled the promise — ignore.
-						return;
-					}
-					finish();
-					if (error) {
-						reject(error instanceof Error ? error : new TransportError(String(error)));
-						return;
-					}
-					try {
-						const replySignature = this.signature ?? '';
-						const decoded: DbusValue[] =
-							replySignature.length > 0 ? decodeBody(replySignature, body) : [];
-						resolve({ signature: replySignature, body: decoded });
-					} catch (decodeError) {
-						reject(decodeError);
-					}
-				},
-			);
-		});
+	callMethod(call: MethodCall): Promise<MethodReply> {
+		return this.#calls.call(this.#bus, this.#state === 'connected', call);
 	}
 
-	async subscribeSignal(spec: SignalSpec, listener: SignalListener): Promise<Subscription> {
-		const rule = buildMatchRule(spec);
-		const id = this.#nextSubId++;
-		this.#subscriptions.set(id, { id, spec, listener, rule });
-		await this.#addMatchRule(rule);
-
-		let removed = false;
-		return {
-			unsubscribe: async (): Promise<void> => {
-				if (removed) {
-					return;
-				}
-				removed = true;
-				this.#subscriptions.delete(id);
-				await this.#removeMatchRule(rule);
-			},
-		};
+	subscribeSignal(spec: SignalSpec, listener: SignalListener): Promise<Subscription> {
+		return this.#signals.subscribe(spec, listener);
 	}
 
 	subscriptionCount(): number {
-		return this.#subscriptions.size;
+		return this.#signals.count();
 	}
 
 	on(event: TransportEvent, handler: (payload?: unknown) => void): void {
@@ -300,9 +172,7 @@ class DbusTransportImpl implements DbusTransport {
 			bus.connection.on('end', this.#onConnectionEnd);
 
 			// Re-issue every live match rule so a reconnect resubscribes transparently.
-			for (const rule of this.#matchRuleRefcount.keys()) {
-				await bus.addMatch(rule);
-			}
+			await this.#signals.reissueRules(bus);
 
 			this.#bus = bus;
 			this.#state = 'connected';
@@ -319,58 +189,6 @@ class DbusTransportImpl implements DbusTransport {
 		}
 	}
 
-	#dispatchSignal(message: RawMessage): void {
-		if (message.type !== messageType.signal) {
-			return;
-		}
-		for (const record of this.#subscriptions.values()) {
-			if (!signalMatches(record.spec, message)) {
-				continue;
-			}
-			let body: DbusValue[];
-			try {
-				const signature = message.signature ?? '';
-				body = signature.length > 0 ? decodeBody(signature, message.body ?? []) : [];
-			} catch (error) {
-				this.#emitter.emit('error', error);
-				continue;
-			}
-			const event: SignalEvent = {
-				path: message.path ?? '',
-				interface: message.interface ?? '',
-				member: message.member ?? '',
-				sender: message.sender,
-				signature: message.signature ?? '',
-				body,
-			};
-			try {
-				record.listener(event);
-			} catch (error) {
-				this.#emitter.emit('error', error);
-			}
-		}
-	}
-
-	async #addMatchRule(rule: string): Promise<void> {
-		const current = this.#matchRuleRefcount.get(rule) ?? 0;
-		this.#matchRuleRefcount.set(rule, current + 1);
-		if (current === 0 && this.#state === 'connected' && this.#bus) {
-			await this.#bus.addMatch(rule);
-		}
-	}
-
-	async #removeMatchRule(rule: string): Promise<void> {
-		const current = this.#matchRuleRefcount.get(rule) ?? 0;
-		if (current <= 1) {
-			this.#matchRuleRefcount.delete(rule);
-			if (current === 1 && this.#state === 'connected' && this.#bus) {
-				await this.#bus.removeMatch(rule).catch(() => undefined);
-			}
-		} else {
-			this.#matchRuleRefcount.set(rule, current - 1);
-		}
-	}
-
 	#detachHandlers(bus: RawBus): void {
 		bus.connection.removeListener('message', this.#onMessage as (...args: unknown[]) => void);
 		bus.connection.removeListener('error', this.#onConnectionError);
@@ -385,13 +203,6 @@ class DbusTransportImpl implements DbusTransport {
 		bus.connection.on('error', () => undefined);
 	}
 
-	#rejectPending(cause: unknown): void {
-		for (const pending of this.#pending) {
-			pending.reject(cause);
-		}
-		this.#pending.clear();
-	}
-
 	#handleDrop(cause: unknown): void {
 		if (this.#closing) {
 			return;
@@ -404,7 +215,7 @@ class DbusTransportImpl implements DbusTransport {
 			this.#quiesce(this.#bus);
 		}
 		this.#bus = null;
-		this.#rejectPending(cause);
+		this.#calls.rejectAll(cause);
 		this.#emitter.emit('disconnected', cause);
 		if (this.#reconnect.enabled) {
 			void this.#reconnectLoop();