@ceralive/modem-control 0.1.0

package/src/transport/codec.test.ts

@@ -0,0 +1,118 @@
+// Pure, in-process encode/decode round-trip: no bus, fully deterministic. Marshals with
+// the library's own marshaller and reads it back with its DBusBuffer under
+// `ReturnLongjs: true` — exactly the wire path a real call takes — so a green run here is
+// exact proof the codec is lossless, independent of any daemon timing.
+
+import { expect, test } from 'bun:test';
+import DBusBuffer from '@httptoolkit/dbus-native/lib/dbus-buffer';
+import marshall from '@httptoolkit/dbus-native/lib/marshall';
+import { decodeBody, encodeBody } from './codec';
+import { BigIntRequiredError, SixtyFourBitRangeError, UnsupportedSignatureError } from './errors';
+import { type DbusValue, variant } from './types';
+
+const INT64_MAX = 2n ** 63n - 1n;
+const INT64_MIN = -(2n ** 63n);
+const UINT64_MAX = 2n ** 64n - 1n;
+
+function roundTrip(signature: string, values: readonly DbusValue[]): DbusValue[] {
+	const encoded = encodeBody(signature, values);
+	const buffer = marshall(signature, encoded);
+	const reader = new DBusBuffer(buffer, 0, { ayBuffer: true, ReturnLongjs: true });
+	const raw = reader.read(signature) as unknown[];
+	return decodeBody(signature, raw);
+}
+
+test('2^63-1 round-trips through an INT64 exactly (bigint equality)', () => {
+	const [value] = roundTrip('x', [INT64_MAX]);
+	expect(value).toBe(INT64_MAX);
+	expect(typeof value).toBe('bigint');
+});
+
+test('the full UINT64 range (2^64-1) round-trips exactly', () => {
+	const [value] = roundTrip('t', [UINT64_MAX]);
+	expect(value).toBe(UINT64_MAX);
+});
+
+test('INT64 minimum round-trips exactly', () => {
+	const [value] = roundTrip('x', [INT64_MIN]);
+	expect(value).toBe(INT64_MIN);
+});
+
+test('a value just above 2^53 survives (no silent Number coercion)', () => {
+	const beyondSafe = 2n ** 53n + 1n;
+	const [asInt, asUint] = roundTrip('xt', [beyondSafe, beyondSafe]);
+	expect(asInt).toBe(beyondSafe);
+	expect(asUint).toBe(beyondSafe);
+	// The precision-losing path would have produced 9007199254740992n (== 2^53).
+	expect(asInt).not.toBe(2n ** 53n);
+});
+
+test('the MM GetManagedObjects shape a{oa{sa{sv}}} round-trips with a 64-bit variant', () => {
+	const managed: DbusValue = [
+		[
+			'/org/freedesktop/ModemManager1/Modem/0',
+			[
+				[
+					'org.freedesktop.ModemManager1.Modem',
+					[
+						['SupportedCapabilities', variant('t', UINT64_MAX)],
+						['SignalQuality', variant('u', 87)],
+						['DeviceIdentifier', variant('s', 'dev-0')],
+					],
+				],
+			],
+		],
+	];
+	const [decoded] = roundTrip('a{oa{sa{sv}}}', [managed]);
+	expect(decoded).toEqual(managed);
+});
+
+test('a variant preserves its inner signature and 64-bit value across a round-trip', () => {
+	const [decoded] = roundTrip('v', [variant('t', UINT64_MAX)]);
+	expect(decoded).toEqual({ signature: 't', value: UINT64_MAX });
+});
+
+test('a byte array (ay) round-trips as a Uint8Array', () => {
+	const bytes = new Uint8Array([0, 1, 2, 254, 255]);
+	const [decoded] = roundTrip('ay', [bytes]);
+	expect(decoded).toBeInstanceOf(Uint8Array);
+	expect(Array.from(decoded as Uint8Array)).toEqual([0, 1, 2, 254, 255]);
+});
+
+test('a struct with mixed 64-bit fields round-trips', () => {
+	const [decoded] = roundTrip('(xtu)', [[INT64_MIN, UINT64_MAX, 7]]);
+	expect(decoded).toEqual([INT64_MIN, UINT64_MAX, 7]);
+});
+
+test('signature h (UNIX_FD) is rejected on encode with a typed error', () => {
+	expect(() => encodeBody('h', [0])).toThrow(UnsupportedSignatureError);
+});
+
+test('signature h nested inside a container is rejected on encode', () => {
+	expect(() => encodeBody('a{sh}', [[]])).toThrow(UnsupportedSignatureError);
+});
+
+test('signature h is rejected on decode with a typed error', () => {
+	expect(() => decodeBody('h', [0])).toThrow(UnsupportedSignatureError);
+});
+
+test('the UnsupportedSignatureError carries the offending type', () => {
+	try {
+		encodeBody('h', [0]);
+		throw new Error('expected throw');
+	} catch (error) {
+		expect(error).toBeInstanceOf(UnsupportedSignatureError);
+		expect((error as UnsupportedSignatureError).unsupportedType).toBe('h');
+	}
+});
+
+test('passing a JS number for a 64-bit field throws BigIntRequiredError', () => {
+	expect(() => encodeBody('t', [123])).toThrow(BigIntRequiredError);
+	expect(() => encodeBody('x', [123])).toThrow(BigIntRequiredError);
+});
+
+test('an out-of-range 64-bit bigint throws SixtyFourBitRangeError', () => {
+	expect(() => encodeBody('t', [-1n])).toThrow(SixtyFourBitRangeError);
+	expect(() => encodeBody('x', [2n ** 63n])).toThrow(SixtyFourBitRangeError);
+	expect(() => encodeBody('t', [2n ** 64n])).toThrow(SixtyFourBitRangeError);
+});

package/src/transport/codec.ts

@@ -0,0 +1,240 @@
+// Signature-aware encode / decode between the transport's public value vocabulary
+// (`DbusValue`, `bigint` for 64-bit, `DbusVariant`) and the shape the underlying
+// `@httptoolkit/dbus-native` marshaller consumes and produces.
+//
+// Two invariants this layer enforces that the library does not:
+//   * 64-bit `x`/`t` are `bigint` end-to-end. On decode the library returns Long.js
+//     objects (only under `ReturnLongjs: true`); we convert them to `bigint` losslessly
+//     via their exact decimal `toString()`. On encode the library accepts a decimal
+//     string for the full 64-bit range but silently truncates a `number` above 2^53 —
+//     so we require a `bigint` and convert it to a decimal string ourselves.
+//   * `h` (UNIX_FD) is rejected up front with a typed error rather than reaching the
+//     library, which would throw a generic "Unknown/Unsupported type" instead.
+
+import { BigIntRequiredError, SixtyFourBitRangeError, UnsupportedSignatureError } from './errors';
+import { parseSignature, type SignatureNode, signatureFromNode } from './signature';
+import type { DbusValue, DbusVariant } from './types';
+
+const INT64_MIN = -(2n ** 63n);
+const INT64_MAX = 2n ** 63n - 1n;
+const UINT64_MAX = 2n ** 64n - 1n;
+
+// A Long.js instance as the library hands it back with `ReturnLongjs: true`. We never
+// import `long` (it is a transitive dependency, not ours) — we duck-type and use the
+// exact decimal `toString()`, so no library type crosses this boundary.
+interface LongLike {
+	readonly low: number;
+	readonly high: number;
+	readonly unsigned: boolean;
+	toString(): string;
+}
+
+function isLongLike(value: unknown): value is LongLike {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		typeof (value as LongLike).low === 'number' &&
+		typeof (value as LongLike).high === 'number' &&
+		typeof (value as LongLike).unsigned === 'boolean'
+	);
+}
+
+function longToBigInt(value: LongLike): bigint {
+	return BigInt(value.toString());
+}
+
+// ── Encode ─────────────────────────────────────────────────────────────────────────
+// Public values → library-native body. `assertSupportedSignature` is applied to the
+// whole signature first, so no `h` reaches the recursion.
+export function encodeBody(signature: string, args: readonly DbusValue[]): unknown[] {
+	if (signature.includes('h')) {
+		throw new UnsupportedSignatureError(signature, 'h');
+	}
+	const nodes = parseSignature(signature);
+	if (nodes.length !== args.length) {
+		throw new Error(
+			`Body arity ${args.length} does not match signature "${signature}" (${nodes.length} types)`,
+		);
+	}
+	return nodes.map((node, i) => encodeNode(node, args[i] as DbusValue));
+}
+
+function encodeNode(node: SignatureNode, value: DbusValue): unknown {
+	switch (node.type) {
+		case 'x':
+			return encode64(node.type, value, INT64_MIN, INT64_MAX);
+		case 't':
+			return encode64(node.type, value, 0n, UINT64_MAX);
+		case 'a':
+			return encodeArray(node, value);
+		case '(':
+			return encodeStruct(node, value);
+		case '{':
+			return encodeDictEntry(node, value);
+		case 'v':
+			return encodeVariant(value);
+		default:
+			// y b n q i u d s o g — the library validates range/type on marshal.
+			return value;
+	}
+}
+
+function encode64(type: string, value: DbusValue, min: bigint, max: bigint): string {
+	if (typeof value !== 'bigint') {
+		throw new BigIntRequiredError(type, value);
+	}
+	if (value < min || value > max) {
+		throw new SixtyFourBitRangeError(type, value);
+	}
+	// Decimal string: the library parses this across the full 64-bit range losslessly.
+	return value.toString();
+}
+
+function encodeArray(node: SignatureNode, value: DbusValue): unknown {
+	const element = node.child[0] as SignatureNode;
+	// `ay` byte arrays pass straight through as a Uint8Array / Buffer (index-addressable).
+	if (element.type === 'y' && value instanceof Uint8Array) {
+		return value;
+	}
+	if (!Array.isArray(value)) {
+		throw new Error(`Expected array for signature "a${element.type}"`);
+	}
+	return value.map((item) => encodeNode(element, item));
+}
+
+function encodeStruct(node: SignatureNode, value: DbusValue): unknown[] {
+	if (!Array.isArray(value)) {
+		throw new Error('Expected array for struct value');
+	}
+	if (value.length !== node.child.length) {
+		throw new Error(`Struct arity ${value.length} does not match ${node.child.length} field types`);
+	}
+	return node.child.map((child, i) => encodeNode(child, value[i] as DbusValue));
+}
+
+function encodeDictEntry(node: SignatureNode, value: DbusValue): unknown[] {
+	if (!Array.isArray(value) || value.length !== 2) {
+		throw new Error('Expected [key, value] pair for dict entry');
+	}
+	const keyNode = node.child[0] as SignatureNode;
+	const valueNode = node.child[1] as SignatureNode;
+	return [encodeNode(keyNode, value[0] as DbusValue), encodeNode(valueNode, value[1] as DbusValue)];
+}
+
+function encodeVariant(value: DbusValue): [string, unknown] {
+	const asVariant = value as DbusVariant;
+	if (typeof asVariant?.signature !== 'string' || !('value' in (asVariant as object))) {
+		throw new Error('Expected a DbusVariant ({ signature, value }) for variant field');
+	}
+	if (asVariant.signature.includes('h')) {
+		throw new UnsupportedSignatureError(asVariant.signature, 'h');
+	}
+	const inner = parseSignature(asVariant.signature);
+	if (inner.length !== 1) {
+		throw new Error(`Variant signature "${asVariant.signature}" must be exactly one complete type`);
+	}
+	return [asVariant.signature, encodeNode(inner[0] as SignatureNode, asVariant.value)];
+}
+
+// ── Decode ─────────────────────────────────────────────────────────────────────────
+// Library-native body → public values. The library must have been created with
+// `ReturnLongjs: true` so `x`/`t` arrive as Long objects (this transport does exactly
+// that); a raw `number` in a 64-bit slot means that flag was lost and is treated as a
+// bug, not silently accepted.
+export function decodeBody(signature: string, body: readonly unknown[]): DbusValue[] {
+	if (signature.includes('h')) {
+		throw new UnsupportedSignatureError(signature, 'h');
+	}
+	const nodes = parseSignature(signature);
+	return nodes.map((node, i) => decodeNode(node, body[i]));
+}
+
+function decodeNode(node: SignatureNode, value: unknown): DbusValue {
+	switch (node.type) {
+		case 'x':
+		case 't':
+			return decode64(node.type, value);
+		case 'a':
+			return decodeArray(node, value);
+		case '(':
+			return decodeStruct(node, value);
+		case '{':
+			return decodeDictEntry(node, value);
+		case 'v':
+			return decodeVariant(value);
+		case 'y':
+		case 'b':
+		case 'n':
+		case 'q':
+		case 'i':
+		case 'u':
+		case 'd':
+		case 's':
+		case 'o':
+		case 'g':
+			return value as DbusValue;
+		default:
+			throw new UnsupportedSignatureError(node.type, node.type);
+	}
+}
+
+function decode64(type: string, value: unknown): bigint {
+	if (isLongLike(value)) {
+		return longToBigInt(value);
+	}
+	if (typeof value === 'bigint') {
+		return value;
+	}
+	// A plain number reaching here means ReturnLongjs was not applied — refuse it rather
+	// than risk having already lost precision above 2^53.
+	throw new BigIntRequiredError(type, value);
+}
+
+function decodeArray(node: SignatureNode, value: unknown): DbusValue {
+	const element = node.child[0] as SignatureNode;
+	if (element.type === 'y') {
+		// `ay`: the library returns a Buffer; normalise to a plain Uint8Array.
+		if (value instanceof Uint8Array) {
+			return new Uint8Array(value);
+		}
+	}
+	if (!Array.isArray(value)) {
+		throw new Error(`Expected array while decoding "a${element.type}"`);
+	}
+	return value.map((item) => decodeNode(element, item));
+}
+
+function decodeStruct(node: SignatureNode, value: unknown): DbusValue {
+	if (!Array.isArray(value)) {
+		throw new Error('Expected array while decoding struct');
+	}
+	return node.child.map((child, i) => decodeNode(child, value[i]));
+}
+
+function decodeDictEntry(node: SignatureNode, value: unknown): DbusValue {
+	if (!Array.isArray(value) || value.length !== 2) {
+		throw new Error('Expected [key, value] pair while decoding dict entry');
+	}
+	const keyNode = node.child[0] as SignatureNode;
+	const valueNode = node.child[1] as SignatureNode;
+	return [decodeNode(keyNode, value[0]), decodeNode(valueNode, value[1])];
+}
+
+// The library decodes a variant to `[parseTree, [innerValue]]`. We recover the inner
+// signature from the tree and decode the contained value recursively, preserving both.
+function decodeVariant(value: unknown): DbusVariant {
+	if (!Array.isArray(value) || value.length !== 2) {
+		throw new Error('Malformed variant from library (expected [tree, [value]])');
+	}
+	const tree = value[0] as SignatureNode[];
+	const inner = value[1] as unknown[];
+	if (!Array.isArray(tree) || tree.length !== 1 || !Array.isArray(inner)) {
+		throw new Error('Malformed variant tree from library');
+	}
+	const innerNode = tree[0] as SignatureNode;
+	const innerSignature = signatureFromNode(innerNode);
+	return {
+		signature: innerSignature,
+		value: decodeNode(innerNode, inner[0]),
+	};
+}

package/src/transport/conformance-python.test.ts

@@ -0,0 +1,152 @@
+// Conformance half (b): round-trip against an INDEPENDENT `python3-dbus` producer running
+// as a subprocess — a different implementation on the wire than the JavaScript library
+// under test. Agreement with a foreign producer, not just the same-library fake, is the
+// real proof the codec is correct. Exercises the MM `a{oa{sa{sv}}}` shape, `x`/`t` above
+// 2^53, variants, and a `PropertiesChanged` signal carrying invalidated properties.
+//
+// Skips loudly (never fails) when the session bus or `dbus-python` bindings are absent.
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { join } from 'node:path';
+import type { DbusTransport, SignalEvent } from './index';
+import { createDbusTransport } from './index';
+
+const SESSION_BUS = process.env.DBUS_SESSION_BUS_ADDRESS;
+
+const PY_BUS_NAME = 'tv.ceralive.ModemStackPy';
+const PY_PATH = '/tv/ceralive/pyfake';
+const PY_IFACE = 'tv.ceralive.ModemStackPy.Conformance';
+const PROPERTIES_IFACE = 'org.freedesktop.DBus.Properties';
+
+const INT64_MAX = 2n ** 63n - 1n;
+const UINT64_MAX = 2n ** 64n - 1n;
+
+function hasDbusPython(): boolean {
+	const probe = Bun.spawnSync(['python3', '-c', 'import dbus, dbus.service, gi.repository.GLib']);
+	return probe.exitCode === 0;
+}
+
+async function waitForReady(proc: ReturnType<typeof Bun.spawn>, timeoutMs: number): Promise<void> {
+	const reader = (proc.stdout as ReadableStream<Uint8Array>).getReader();
+	const decoder = new TextDecoder();
+	let seen = '';
+	const deadline = Date.now() + timeoutMs;
+	try {
+		while (Date.now() < deadline) {
+			const { value, done } = await reader.read();
+			if (done) {
+				throw new Error('python producer exited before signalling READY');
+			}
+			seen += decoder.decode(value, { stream: true });
+			if (seen.includes('READY')) {
+				return;
+			}
+		}
+		throw new Error('timed out waiting for python producer READY');
+	} finally {
+		reader.releaseLock();
+	}
+}
+
+const runnable = Boolean(SESSION_BUS) && hasDbusPython();
+
+describe.skipIf(!runnable)('conformance vs independent python3-dbus producer', () => {
+	let producer: ReturnType<typeof Bun.spawn>;
+	let transport: DbusTransport;
+
+	beforeAll(async () => {
+		const script = join(import.meta.dir, 'test-support', 'independent-producer.py');
+		producer = Bun.spawn(['python3', script], {
+			stdout: 'pipe',
+			stderr: 'inherit',
+			env: process.env,
+		});
+		await waitForReady(producer, 10_000);
+		transport = createDbusTransport({ busAddress: SESSION_BUS as string });
+		await transport.connect();
+	});
+
+	afterAll(async () => {
+		await transport.disconnect();
+		producer.kill();
+	});
+
+	const call = (member: string, signature?: string, args?: unknown[]) =>
+		transport.callMethod({
+			destination: PY_BUS_NAME,
+			path: PY_PATH,
+			interface: PY_IFACE,
+			member,
+			...(signature !== undefined ? { signature } : {}),
+			...(args !== undefined ? { args: args as never } : {}),
+		});
+
+	test('the independent producer returns the a{oa{sa{sv}}} shape with 64-bit variants', async () => {
+		const reply = await call('GetManagedObjects');
+		expect(reply.signature).toBe('a{oa{sa{sv}}}');
+		expect(reply.body[0]).toEqual([
+			[
+				'/org/freedesktop/ModemManager1/Modem/0',
+				[
+					[
+						'org.freedesktop.ModemManager1.Modem',
+						[
+							['SupportedCapabilities', { signature: 't', value: UINT64_MAX }],
+							['MaxBearers', { signature: 'x', value: -INT64_MAX }],
+							['SignalQuality', { signature: 'u', value: 87 }],
+							['DeviceIdentifier', { signature: 's', value: 'py-device-0' }],
+						],
+					],
+				],
+			],
+		]);
+	});
+
+	test('an INT64 above 2^53 from the independent producer decodes to an exact bigint', async () => {
+		const reply = await call('GetInt64');
+		expect(reply.body[0]).toBe(INT64_MAX);
+	});
+
+	test('a UINT64 at the 64-bit maximum from the independent producer decodes exactly', async () => {
+		const reply = await call('GetUint64');
+		expect(reply.body[0]).toBe(UINT64_MAX);
+	});
+
+	test('a bare variant from the independent producer preserves signature and value', async () => {
+		const reply = await call('GetVariant');
+		expect(reply.body[0]).toEqual({ signature: 't', value: UINT64_MAX });
+	});
+
+	test('2^63-1 round-trips through the independent producer exactly', async () => {
+		const reply = await call('EchoUint64', 't', [INT64_MAX]);
+		expect(reply.body[0]).toBe(INT64_MAX);
+	});
+
+	test('the independent producer confirms the exact 64-bit value we encoded', async () => {
+		const reply = await call('DescribeUint64', 't', [UINT64_MAX]);
+		expect(reply.body[0]).toBe(UINT64_MAX.toString());
+	});
+
+	test('a PropertiesChanged signal decodes changed 64-bit values and invalidated names', async () => {
+		let resolveEvent: (event: SignalEvent) => void = () => undefined;
+		const received = new Promise<SignalEvent>((resolve) => {
+			resolveEvent = resolve;
+		});
+		const subscription = await transport.subscribeSignal(
+			{ interface: PROPERTIES_IFACE, member: 'PropertiesChanged', path: PY_PATH },
+			(event) => resolveEvent(event),
+		);
+		await call('TriggerPropertiesChanged');
+
+		const event = await received;
+		expect(event.signature).toBe('sa{sv}as');
+		const [interfaceName, changed, invalidated] = event.body;
+		expect(interfaceName).toBe(PY_IFACE);
+		expect(changed).toEqual([
+			['AccessTechnologies', { signature: 't', value: UINT64_MAX }],
+			['SignalQuality', { signature: 'u', value: 42 }],
+		]);
+		expect(invalidated).toEqual(['OperatorName', 'OperatorCode']);
+		await subscription.unsubscribe();
+	});
+});

package/src/transport/conformance-same-lib.test.ts

@@ -0,0 +1,115 @@
+// Conformance half (a): round-trip representative signatures against a fake service built
+// on the SAME `@httptoolkit/dbus-native` library, over a real session bus. This proves the
+// transport works end-to-end against the daemon; half (b) proves it against an independent
+// producer. Run under `dbus-run-session -- bun test control/src/transport`.
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import type { DbusTransport } from './index';
+import { createDbusTransport } from './index';
+import {
+	FAKE_IFACE,
+	FAKE_PATH,
+	type FakeService,
+	INT64_MAX,
+	startFakeService,
+	UINT64_MAX,
+} from './test-support/fake-service';
+
+const SESSION_BUS = process.env.DBUS_SESSION_BUS_ADDRESS;
+
+describe.skipIf(!SESSION_BUS)('conformance vs same-library fake service', () => {
+	let fake: FakeService;
+	let transport: DbusTransport;
+
+	beforeAll(async () => {
+		const busAddress = SESSION_BUS as string;
+		fake = await startFakeService({ busAddress });
+		transport = createDbusTransport({ busAddress });
+		await transport.connect();
+	});
+
+	afterAll(async () => {
+		await transport.disconnect();
+		await fake.stop();
+	});
+
+	const call = (member: string, signature?: string, args?: unknown[]) =>
+		transport.callMethod({
+			destination: fake.busName,
+			path: FAKE_PATH,
+			interface: FAKE_IFACE,
+			member,
+			...(signature !== undefined ? { signature } : {}),
+			...(args !== undefined ? { args: args as never } : {}),
+		});
+
+	test('a basic string method replies', async () => {
+		const reply = await call('Ping');
+		expect(reply.signature).toBe('s');
+		expect(reply.body[0]).toBe('pong');
+	});
+
+	test('GetManagedObjects decodes the a{oa{sa{sv}}} shape with a 64-bit variant', async () => {
+		const reply = await call('GetManagedObjects');
+		expect(reply.signature).toBe('a{oa{sa{sv}}}');
+		expect(reply.body[0]).toEqual([
+			[
+				'/org/freedesktop/ModemManager1/Modem/0',
+				[
+					[
+						'org.freedesktop.ModemManager1.Modem',
+						[
+							['SupportedCapabilities', { signature: 't', value: UINT64_MAX }],
+							['SignalQuality', { signature: 'u', value: 87 }],
+							['DeviceIdentifier', { signature: 's', value: 'fake-device-0' }],
+						],
+					],
+				],
+			],
+		]);
+	});
+
+	test('an INT64 reply above 2^53 decodes to an exact bigint', async () => {
+		const reply = await call('GetInt64');
+		expect(reply.body[0]).toBe(INT64_MAX);
+		expect(typeof reply.body[0]).toBe('bigint');
+	});
+
+	test('a UINT64 reply at the full 64-bit maximum decodes exactly', async () => {
+		const reply = await call('GetUint64');
+		expect(reply.body[0]).toBe(UINT64_MAX);
+	});
+
+	test('2^63-1 round-trips through the daemon exactly (encode + decode)', async () => {
+		const reply = await call('EchoUint64', 't', [INT64_MAX]);
+		expect(reply.body[0]).toBe(INT64_MAX);
+	});
+
+	test('the full UINT64 maximum round-trips through the daemon exactly', async () => {
+		const reply = await call('EchoUint64', 't', [UINT64_MAX]);
+		expect(reply.body[0]).toBe(UINT64_MAX);
+	});
+
+	test('a negative INT64 round-trips through the daemon exactly', async () => {
+		const reply = await call('EchoInt64', 'x', [-INT64_MAX]);
+		expect(reply.body[0]).toBe(-INT64_MAX);
+	});
+
+	test('the service reports back the exact 64-bit value we encoded', async () => {
+		const reply = await call('DescribeUint64', 't', [INT64_MAX]);
+		expect(reply.body[0]).toBe(INT64_MAX.toString());
+	});
+
+	test('passing a JS number for a 64-bit argument is refused before the wire', async () => {
+		await expect(
+			transport.callMethod({
+				destination: fake.busName,
+				path: FAKE_PATH,
+				interface: FAKE_IFACE,
+				member: 'EchoUint64',
+				signature: 't',
+				args: [123 as never],
+			}),
+		).rejects.toThrow('requires a bigint');
+	});
+});

package/src/transport/dbus-native-lib.d.ts

@@ -0,0 +1,19 @@
+// Ambient declarations for the deep library entry points the transport tests use to run
+// an in-process, bus-free marshal/unmarshal round-trip. These are test-only reaches into
+// `@httptoolkit/dbus-native` internals; the production transport never imports them.
+
+declare module '@httptoolkit/dbus-native/lib/marshall' {
+	const marshall: (signature: string, data: unknown[], offset?: number) => Buffer;
+	export default marshall;
+}
+
+declare module '@httptoolkit/dbus-native/lib/dbus-buffer' {
+	export default class DBusBuffer {
+		constructor(
+			buffer: Buffer,
+			startPos?: number,
+			options?: { ayBuffer?: boolean; ReturnLongjs?: boolean },
+		);
+		read(signature: string): unknown;
+	}
+}