@jshookmcp/jshook 0.2.8 → 0.2.9

package/dist/handlers-D6j6yka7.mjs

@@ -0,0 +1,2124 @@
+import { i as argObject, o as argStringArray, s as argStringRequired } from "./parse-args-BlRjqlkL.mjs";
+import { readFile as readFile$1, writeFile as writeFile$1 } from "node:fs/promises";
+import { isIP } from "node:net";
+//#region src/modules/protocol-analysis/ProtocolPatternUtils.ts
+const PRINTABLE_MIN = 32;
+const PRINTABLE_MAX = 126;
+const DELIMITER_CANDIDATES = [
+	Buffer.from([44]),
+	Buffer.from([124]),
+	Buffer.from([58]),
+	Buffer.from([59]),
+	Buffer.from([9]),
+	Buffer.from([0]),
+	Buffer.from([13, 10])
+];
+function normalizeHexPayload(value) {
+	return value.replace(/^0x/i, "").replace(/\s+/g, "").toLowerCase();
+}
+function isHexPayload(value) {
+	const normalized = normalizeHexPayload(value);
+	if (normalized.length === 0 || normalized.length % 2 !== 0) return false;
+	return /^[0-9a-f]+$/i.test(normalized);
+}
+function parseHexPayload$1(value) {
+	if (!isHexPayload(value)) return null;
+	return Buffer.from(normalizeHexPayload(value), "hex");
+}
+function isPrintableByte(value) {
+	return value >= PRINTABLE_MIN && value <= PRINTABLE_MAX;
+}
+function printableRatio(buffer) {
+	if (buffer.length === 0) return 0;
+	let printableCount = 0;
+	for (const value of buffer.values()) if (isPrintableByte(value)) printableCount += 1;
+	return printableCount / buffer.length;
+}
+function averagePrintableRatio(buffers) {
+	if (buffers.length === 0) return 0;
+	return buffers.reduce((accumulator, buffer) => accumulator + printableRatio(buffer), 0) / buffers.length;
+}
+function splitBuffer(buffer, delimiter) {
+	if (delimiter.length === 0) return [buffer];
+	const parts = [];
+	let start = 0;
+	let index = buffer.indexOf(delimiter, start);
+	while (index >= 0) {
+		parts.push(buffer.subarray(start, index));
+		start = index + delimiter.length;
+		index = buffer.indexOf(delimiter, start);
+	}
+	parts.push(buffer.subarray(start));
+	return parts;
+}
+function bufferToDelimiterString(buffer) {
+	return printableRatio(buffer) === 1 ? buffer.toString("utf8") : buffer.toString("hex");
+}
+function parsePayloads(hexPayloads) {
+	const buffers = [];
+	for (const hexPayload of hexPayloads) {
+		const payload = parseHexPayload$1(hexPayload);
+		if (payload) buffers.push(payload);
+	}
+	return buffers;
+}
+function decodeInteger(buffer, byteOrder) {
+	if (buffer.length === 0) return null;
+	if (buffer.length === 1) return buffer.readUInt8(0);
+	if (buffer.length === 2) return byteOrder === "le" ? buffer.readUInt16LE(0) : buffer.readUInt16BE(0);
+	if (buffer.length === 4) return byteOrder === "le" ? buffer.readUInt32LE(0) : buffer.readUInt32BE(0);
+	if (buffer.length === 8) {
+		const value = byteOrder === "le" ? Number(buffer.readBigUInt64LE(0)) : Number(buffer.readBigUInt64BE(0));
+		return Number.isFinite(value) ? value : null;
+	}
+	let value = 0;
+	const bytes = byteOrder === "le" ? [...buffer.values()].toReversed() : [...buffer.values()];
+	for (const byte of bytes) value = value * 256 + byte;
+	return Number.isFinite(value) ? value : null;
+}
+function decodeFloat(buffer, byteOrder) {
+	if (buffer.length === 4) {
+		const value = byteOrder === "le" ? buffer.readFloatLE(0) : buffer.readFloatBE(0);
+		return Number.isFinite(value) ? value : null;
+	}
+	if (buffer.length === 8) {
+		const value = byteOrder === "le" ? buffer.readDoubleLE(0) : buffer.readDoubleBE(0);
+		return Number.isFinite(value) ? value : null;
+	}
+	return null;
+}
+function countOccurrences(buffer, delimiter) {
+	if (delimiter.length === 0) return 0;
+	let count = 0;
+	let start = 0;
+	let index = buffer.indexOf(delimiter, start);
+	while (index >= 0) {
+		count += 1;
+		start = index + delimiter.length;
+		index = buffer.indexOf(delimiter, start);
+	}
+	return count;
+}
+function inferFieldType(samples) {
+	if (samples.length === 0) return "bytes";
+	if (samples.every((sample) => sample.length === 1) && samples.every((sample) => sample[0] === 0 || sample[0] === 1)) return "bool";
+	if (averagePrintableRatio(samples) >= .7) return "string";
+	if (samples.every((sample) => sample.length === 4) && looksLikeFloatSamples(samples)) return "float";
+	if (samples.every((sample) => sample.length <= 4)) return "int";
+	return "bytes";
+}
+function looksLikeFloatSamples(samples) {
+	const decoded = [];
+	for (const sample of samples) {
+		const value = decodeFloat(sample, "be");
+		if (value === null) return false;
+		decoded.push(value);
+	}
+	return decoded.some((value) => Math.abs(value) > .001 && Math.abs(value) < 1e6);
+}
+function isPrintableColumn(buffers, offset) {
+	let valueCount = 0;
+	let printableCount = 0;
+	for (const buffer of buffers) {
+		const value = buffer[offset];
+		if (value === void 0) continue;
+		valueCount += 1;
+		if (isPrintableByte(value)) printableCount += 1;
+	}
+	return valueCount > 0 && printableCount / valueCount >= .8;
+}
+function isBooleanColumn(buffers, offset) {
+	let valueCount = 0;
+	for (const buffer of buffers) {
+		const value = buffer[offset];
+		if (value === void 0) continue;
+		valueCount += 1;
+		if (value !== 0 && value !== 1) return false;
+	}
+	return valueCount > 0;
+}
+function buildDelimitedFields(buffers, delimiter) {
+	if (delimiter.length === 0) return [];
+	const tokenized = buffers.map((buffer) => splitBuffer(buffer, delimiter));
+	const firstRow = tokenized[0];
+	if (!firstRow || firstRow.length < 2) return [];
+	const tokenCount = firstRow.length;
+	if (!tokenized.every((parts) => parts.length === tokenCount)) return [];
+	const fields = [];
+	let currentOffset = 0;
+	for (let index = 0; index < tokenCount; index += 1) {
+		const template = firstRow[index];
+		if (!template) continue;
+		const samples = tokenized.map((parts) => parts[index]).filter((part) => Buffer.isBuffer(part));
+		fields.push({
+			name: `field_${index + 1}`,
+			offset: currentOffset,
+			length: template.length,
+			type: inferFieldType(samples)
+		});
+		currentOffset += template.length + delimiter.length;
+	}
+	return fields;
+}
+function buildFixedWidthFields(buffers) {
+	const minLength = Math.min(...buffers.map((buffer) => buffer.length));
+	const fields = [];
+	let offset = 0;
+	while (offset < minLength && fields.length < 24) {
+		if (isPrintableColumn(buffers, offset)) {
+			let end = offset + 1;
+			while (end < minLength && isPrintableColumn(buffers, end)) end += 1;
+			fields.push({
+				name: `field_${fields.length + 1}`,
+				offset,
+				length: end - offset,
+				type: "string"
+			});
+			offset = end;
+			continue;
+		}
+		if (isBooleanColumn(buffers, offset)) {
+			fields.push({
+				name: `field_${fields.length + 1}`,
+				offset,
+				length: 1,
+				type: "bool"
+			});
+			offset += 1;
+			continue;
+		}
+		const remaining = minLength - offset;
+		if (remaining >= 4) {
+			if (looksLikeFloatSamples(buffers.map((buffer) => buffer.subarray(offset, offset + 4)))) {
+				fields.push({
+					name: `field_${fields.length + 1}`,
+					offset,
+					length: 4,
+					type: "float"
+				});
+				offset += 4;
+				continue;
+			}
+		}
+		const segmentLength = remaining >= 4 ? 4 : Math.min(remaining, 2);
+		const samples = buffers.map((buffer) => buffer.subarray(offset, offset + segmentLength));
+		fields.push({
+			name: `field_${fields.length + 1}`,
+			offset,
+			length: segmentLength,
+			type: inferFieldType(samples)
+		});
+		offset += segmentLength;
+	}
+	return fields;
+}
+function inferDelimiter(buffers) {
+	for (const candidate of DELIMITER_CANDIDATES) {
+		const counts = buffers.map((buffer) => countOccurrences(buffer, candidate));
+		const firstCount = counts[0];
+		if (typeof firstCount === "number" && firstCount >= 2 && counts.every((count) => count === firstCount)) return bufferToDelimiterString(candidate);
+	}
+}
+function inferByteOrder(buffers) {
+	const minLength = Math.min(...buffers.map((buffer) => buffer.length));
+	if (minLength < 2) return "be";
+	let leScore = 0;
+	let beScore = 0;
+	const limit = Math.min(minLength - 1, 8);
+	for (let offset = 0; offset < limit; offset += 2) {
+		let leSmallValues = 0;
+		let beSmallValues = 0;
+		for (const buffer of buffers) {
+			const little = buffer.readUInt16LE(offset);
+			const big = buffer.readUInt16BE(offset);
+			if (little < 4096) leSmallValues += 1;
+			if (big < 4096) beSmallValues += 1;
+		}
+		if (leSmallValues > beSmallValues) leScore += 1;
+		else if (beSmallValues > leSmallValues) beScore += 1;
+	}
+	return leScore > beScore ? "le" : "be";
+}
+function labelMagicFields(fields, buffers) {
+	if (fields.length === 0 || buffers.length < 2) return fields;
+	const minLen = Math.min(...buffers.map((b) => b.length));
+	let commonPrefixLen = 0;
+	for (let offset = 0; offset < minLen; offset += 1) {
+		const byte = buffers[0][offset];
+		if (buffers.every((b) => b[offset] === byte)) commonPrefixLen = offset + 1;
+		else break;
+	}
+	if (commonPrefixLen === 0) return fields;
+	let magicLabelApplied = false;
+	return fields.map((field) => {
+		if (!magicLabelApplied && field.offset === 0 && commonPrefixLen >= 2) {
+			magicLabelApplied = true;
+			return {
+				...field,
+				name: "magic"
+			};
+		}
+		if (magicLabelApplied && field.type === "int" && field.length <= 2 && field.offset <= commonPrefixLen) return {
+			...field,
+			name: "version"
+		};
+		return field;
+	});
+}
+//#endregion
+//#region src/modules/protocol-analysis/ProtocolPatternEngine.ts
+var ProtocolPatternEngine = class {
+	patterns = /* @__PURE__ */ new Map();
+	legacyPatterns = /* @__PURE__ */ new Map();
+	definePattern(name, specOrFields, options) {
+		const legacyPattern = Array.isArray(specOrFields) ? this.createLegacyPattern(name, specOrFields, options) : this.createLegacyPatternFromSpec(name, specOrFields);
+		const spec = this.createSpecFromLegacyPattern(legacyPattern);
+		this.patterns.set(name, spec);
+		this.legacyPatterns.set(name, legacyPattern);
+		if (Array.isArray(specOrFields)) return legacyPattern;
+	}
+	detectPattern(hexPayload) {
+		const payload = parseHexPayload$1(hexPayload);
+		if (!payload) return null;
+		let bestMatch = null;
+		for (const pattern of this.patterns.values()) {
+			const totalChecks = pattern.fields.length + (pattern.fieldDelimiter ? 1 : 0);
+			if (totalChecks === 0) continue;
+			let matches = 0;
+			if (pattern.fieldDelimiter && this.payloadContainsDelimiter(payload, pattern.fieldDelimiter)) matches += 1;
+			for (const field of pattern.fields) if (this.matchesField(payload, field, pattern.byteOrder ?? "be")) matches += 1;
+			const confidence = Number((matches / totalChecks).toFixed(2));
+			if (confidence <= 0) continue;
+			const candidate = {
+				pattern,
+				confidence,
+				matches,
+				total: totalChecks
+			};
+			if (!bestMatch || candidate.confidence > bestMatch.confidence || candidate.confidence === bestMatch.confidence && candidate.matches > bestMatch.matches) bestMatch = candidate;
+		}
+		return bestMatch;
+	}
+	autoDetect(hexPayloads) {
+		const buffers = parsePayloads(hexPayloads);
+		if (buffers.length === 0) return null;
+		const delimiter = inferDelimiter(buffers);
+		const fields = this.inferFields(hexPayloads);
+		return {
+			name: "auto-detected-pattern",
+			fieldDelimiter: delimiter,
+			byteOrder: inferByteOrder(buffers),
+			fields
+		};
+	}
+	inferFields(hexPayloads) {
+		const buffers = parsePayloads(hexPayloads);
+		if (buffers.length === 0) return [];
+		const delimiter = inferDelimiter(buffers);
+		if (delimiter) {
+			const fields = buildDelimitedFields(buffers, this.parseDelimiter(delimiter));
+			if (fields.length > 0) return labelMagicFields(fields, buffers);
+		}
+		return labelMagicFields(buildFixedWidthFields(buffers), buffers);
+	}
+	autoDetectPattern(payloads, options) {
+		const hexPayloads = payloads.map((payload) => payload.toString("hex"));
+		const detected = this.autoDetect(hexPayloads);
+		const name = options?.name ?? detected?.name ?? "auto_detected";
+		if (!detected) {
+			const emptyPattern = this.createLegacyPattern(name, []);
+			this.patterns.set(name, this.createSpecFromLegacyPattern(emptyPattern));
+			this.legacyPatterns.set(name, emptyPattern);
+			return emptyPattern;
+		}
+		const namedPattern = {
+			...detected,
+			name
+		};
+		this.definePattern(name, namedPattern);
+		return this.getPattern(name) ?? this.createLegacyPatternFromSpec(name, namedPattern);
+	}
+	getPattern(name) {
+		return this.legacyPatterns.get(name);
+	}
+	listPatterns() {
+		return [...this.patterns.keys()];
+	}
+	exportProto(pattern) {
+		const legacyPattern = this.isLegacyPattern(pattern) ? pattern : this.createLegacyPatternFromSpec(pattern.name, pattern);
+		const lines = [
+			`// Protocol: ${legacyPattern.name}`,
+			`// Byte order: ${legacyPattern.byteOrder}`,
+			""
+		];
+		if (legacyPattern.encryption) {
+			lines.push(`// Encryption: ${legacyPattern.encryption.type}`);
+			if (legacyPattern.encryption.notes) lines.push(`// Notes: ${legacyPattern.encryption.notes}`);
+			lines.push("");
+		}
+		lines.push(`message ${this.toPascalCase(legacyPattern.name)} {`);
+		for (let index = 0; index < legacyPattern.fields.length; index += 1) {
+			const field = legacyPattern.fields[index];
+			if (!field) continue;
+			const comment = field.description ? ` // ${field.description}` : "";
+			lines.push(`  ${this.toProtoType(field.type)} ${field.name} = ${index + 1};${comment}`);
+		}
+		lines.push("}");
+		lines.push("");
+		return lines.join("\n");
+	}
+	payloadContainsDelimiter(payload, delimiter) {
+		const delimiterBuffer = this.parseDelimiter(delimiter);
+		if (delimiterBuffer.length === 0) return false;
+		return payload.includes(delimiterBuffer);
+	}
+	matchesField(payload, field, byteOrder) {
+		if (field.offset < 0 || field.length <= 0 || payload.length < field.offset + field.length) return false;
+		const slice = payload.subarray(field.offset, field.offset + field.length);
+		switch (field.type) {
+			case "bytes": return slice.length === field.length;
+			case "bool": return slice.length === 1 && (slice[0] === 0 || slice[0] === 1);
+			case "string": return printableRatio(slice) >= .6;
+			case "int": return decodeInteger(slice, byteOrder) !== null;
+			case "float": return decodeFloat(slice, byteOrder) !== null;
+			default: return false;
+		}
+	}
+	createLegacyPattern(name, fields, options) {
+		return {
+			name,
+			fields: fields.map((field) => ({
+				name: field.name,
+				offset: field.offset,
+				length: field.length,
+				type: field.type,
+				...field.description ? { description: field.description } : {}
+			})).toSorted((left, right) => left.offset - right.offset),
+			byteOrder: options?.byteOrder ?? "big",
+			...options?.encryption ? { encryption: options.encryption } : {}
+		};
+	}
+	createLegacyPatternFromSpec(name, spec) {
+		return {
+			name,
+			fieldDelimiter: spec.fieldDelimiter,
+			byteOrder: spec.byteOrder === "le" ? "little" : "big",
+			fields: spec.fields.map((field) => ({
+				name: field.name,
+				offset: field.offset,
+				length: field.length,
+				type: this.toLegacyFieldType(field),
+				...field.description ? { description: field.description } : {}
+			}))
+		};
+	}
+	createSpecFromLegacyPattern(pattern) {
+		return {
+			name: pattern.name,
+			fieldDelimiter: pattern.fieldDelimiter,
+			byteOrder: pattern.byteOrder === "little" ? "le" : "be",
+			fields: pattern.fields.map((field) => ({
+				name: field.name,
+				offset: field.offset,
+				length: field.length,
+				type: this.toSpecFieldType(field.type),
+				...field.description ? { description: field.description } : {}
+			}))
+		};
+	}
+	isLegacyPattern(pattern) {
+		return pattern.byteOrder === "big" || pattern.byteOrder === "little";
+	}
+	toLegacyFieldType(field) {
+		if (field.type === "float") return "float";
+		if (field.type === "string") return "string";
+		if (field.type === "bytes") return "bytes";
+		if (field.length === 1) return "uint8";
+		if (field.length === 2) return "uint16";
+		if (field.length === 4) return "uint32";
+		return "int64";
+	}
+	toSpecFieldType(fieldType) {
+		if (fieldType === "float") return "float";
+		if (fieldType === "string") return "string";
+		if (fieldType === "bytes") return "bytes";
+		return "int";
+	}
+	parseDelimiter(delimiter) {
+		if (isHexPayload(delimiter)) {
+			const parsed = parseHexPayload$1(delimiter);
+			if (parsed) return parsed;
+		}
+		return Buffer.from(delimiter, "utf8");
+	}
+	toProtoType(type) {
+		return {
+			uint8: "uint32",
+			uint16: "uint32",
+			uint32: "uint32",
+			int64: "int64",
+			float: "float",
+			string: "string",
+			bytes: "bytes"
+		}[type];
+	}
+	toPascalCase(name) {
+		return name.replace(/[^a-zA-Z0-9_]/g, "_").split("_").filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("") || "Message";
+	}
+};
+//#endregion
+//#region src/modules/protocol-analysis/StateMachineInferrer.ts
+function isRecord$1(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeText(value) {
+	return value.trim().toLowerCase();
+}
+function calculateEntropy(buffer) {
+	if (buffer.length === 0) return 0;
+	const frequency = /* @__PURE__ */ new Map();
+	for (const byte of buffer) frequency.set(byte, (frequency.get(byte) ?? 0) + 1);
+	let entropy = 0;
+	for (const count of frequency.values()) {
+		const p = count / buffer.length;
+		if (p > 0) entropy -= p * Math.log2(p);
+	}
+	return entropy;
+}
+function printableRatioOf(value) {
+	if (value.length === 0) return 0;
+	let count = 0;
+	for (let i = 0; i < value.length; i += 1) {
+		const code = value.charCodeAt(i);
+		if (code >= 32 && code <= 126) count += 1;
+	}
+	return count / value.length;
+}
+var StateMachineInferrer = class {
+	infer(messages) {
+		if (messages.length === 0) return {
+			states: [],
+			transitions: [],
+			initial: "",
+			initialState: "",
+			finalStates: []
+		};
+		const statesBySignature = /* @__PURE__ */ new Map();
+		const transitionsByKey = /* @__PURE__ */ new Map();
+		let previousStateId = "";
+		for (let index = 0; index < messages.length; index += 1) {
+			const message = messages[index];
+			if (!message) continue;
+			const signature = this.buildSignature(message);
+			let state = statesBySignature.get(signature);
+			if (!state) {
+				state = {
+					id: `state_${statesBySignature.size + 1}`,
+					name: this.buildStateName(message, statesBySignature.size + 1),
+					type: this.inferStateType(message, index === messages.length - 1)
+				};
+				statesBySignature.set(signature, state);
+			} else state.type = this.mergeStateTypes(state.type, this.inferStateType(message, index === messages.length - 1));
+			if (previousStateId && message.timestamp !== void 0) {
+				const firstMessage = messages[0];
+				if (firstMessage && firstMessage.timestamp !== void 0) state.timeout = message.timestamp - firstMessage.timestamp;
+			}
+			if (previousStateId) {
+				const event = this.buildEventName(message);
+				const condition = this.buildCondition(message.fields);
+				const action = this.buildAction(message);
+				const transitionKey = `${previousStateId}:${state.id}:${event}`;
+				if (!transitionsByKey.has(transitionKey)) transitionsByKey.set(transitionKey, {
+					from: previousStateId,
+					to: state.id,
+					event,
+					confidence: this.computeTransitionConfidence(message),
+					...condition ? { condition } : {},
+					...action ? { action } : {}
+				});
+			}
+			previousStateId = state.id;
+		}
+		const firstMessage = messages[0];
+		const initial = firstMessage ? statesBySignature.get(this.buildSignature(firstMessage))?.id ?? "" : "";
+		return {
+			states: [...statesBySignature.values()],
+			transitions: [...transitionsByKey.values()],
+			initial,
+			initialState: initial,
+			finalStates: this.collectTerminalStates([...statesBySignature.values()])
+		};
+	}
+	visualize(machine) {
+		if (machine.states.length === 0) return [
+			"```mermaid",
+			"stateDiagram-v2",
+			"  [*] --> empty",
+			"```"
+		].join("\n");
+		const lines = ["```mermaid", "stateDiagram-v2"];
+		const initial = machine.initialState ?? machine.initial;
+		if (initial) lines.push(`  [*] --> ${initial}`);
+		for (const state of machine.states) {
+			const stateType = state.type ?? "normal";
+			const label = stateType === "normal" ? state.name : `${state.name} (${stateType})`;
+			lines.push(`  state "${label}" as ${state.id}`);
+		}
+		for (const transition of machine.transitions) {
+			const parts = [transition.event ?? transition.trigger ?? "transition"];
+			if (typeof transition.confidence === "number") parts.push(`(${transition.confidence.toFixed(2)})`);
+			if (transition.condition) parts.push(`[${transition.condition}]`);
+			if (transition.action) parts.push(`/ ${transition.action}`);
+			lines.push(`  ${transition.from} --> ${transition.to} : ${parts.join(" ")}`);
+		}
+		const finalStateSet = new Set(machine.finalStates ?? []);
+		for (const state of machine.states) {
+			const stateType = state.type ?? "normal";
+			if (stateType === "accept" || stateType === "reject" || finalStateSet.has(state.id)) lines.push(`  ${state.id} --> [*]`);
+		}
+		lines.push("```");
+		return lines.join("\n");
+	}
+	inferStateMachine(messages) {
+		const normalizedMessages = messages.map((message) => ({
+			direction: message.direction === "out" ? "req" : "res",
+			timestamp: message.timestamp ?? 0,
+			fields: {},
+			raw: message.payload.length > 0 ? message.payload.toString("utf8") : message.payload.toString("hex"),
+			_rawBuffer: message.payload
+		}));
+		return this.infer(normalizedMessages);
+	}
+	generateMermaid(machine) {
+		return this.visualize(machine);
+	}
+	simplify(machine) {
+		if (machine.states.length < 2) return {
+			...machine,
+			initialState: machine.initialState ?? machine.initial,
+			finalStates: machine.finalStates ?? this.collectTerminalStates(machine.states)
+		};
+		const stateToGroup = /* @__PURE__ */ new Map();
+		const groupRepresentative = /* @__PURE__ */ new Map();
+		for (const state of machine.states) {
+			const prefix = this.getPayloadPrefix(state);
+			if (!prefix) continue;
+			const existingGroup = [...groupRepresentative.entries()].find(([key]) => key === prefix);
+			if (existingGroup) stateToGroup.set(state.id, existingGroup[0]);
+			else {
+				groupRepresentative.set(prefix, state.id);
+				stateToGroup.set(state.id, prefix);
+			}
+		}
+		const mergeMap = /* @__PURE__ */ new Map();
+		const groupIdToPrimary = /* @__PURE__ */ new Map();
+		for (const [prefix, primaryId] of groupRepresentative) groupIdToPrimary.set(prefix, primaryId);
+		for (const state of machine.states) {
+			const prefix = this.getPayloadPrefix(state);
+			if (!prefix) continue;
+			const primary = groupIdToPrimary.get(prefix);
+			if (primary && primary !== state.id) mergeMap.set(state.id, primary);
+		}
+		if (mergeMap.size === 0) return {
+			...machine,
+			initialState: machine.initialState ?? machine.initial,
+			finalStates: machine.finalStates ?? this.collectTerminalStates(machine.states)
+		};
+		const newStates = machine.states.filter((state) => !mergeMap.has(state.id));
+		const newTransitions = machine.transitions.map((t) => ({
+			...t,
+			from: mergeMap.get(t.from) ?? t.from,
+			to: mergeMap.get(t.to) ?? t.to
+		})).filter((t) => t.from !== t.to);
+		const rawInitialState = machine.initialState ?? machine.initial ?? "";
+		const initialState = mergeMap.get(rawInitialState) ?? rawInitialState;
+		return {
+			states: newStates,
+			transitions: newTransitions,
+			initial: initialState,
+			initialState,
+			finalStates: machine.finalStates.map((fs) => mergeMap.get(fs) ?? fs).filter((fs, index, arr) => arr.indexOf(fs) === index)
+		};
+	}
+	getPayloadPrefix(state) {
+		const payload = state.expectedPayload;
+		if (!payload || payload.length < 8) return null;
+		return payload.slice(0, 8).toLowerCase();
+	}
+	buildSignature(message) {
+		const fieldKeys = Object.keys(message.fields).toSorted().join(",");
+		const rawPrefix = normalizeText(message._rawBuffer ? message._rawBuffer.toString("hex") : message.raw).slice(0, 24);
+		return `${message.direction}|${fieldKeys}|${rawPrefix}`;
+	}
+	buildStateName(message, position) {
+		const directionName = message.direction === "req" ? "send" : "recv";
+		const primaryField = this.findPrimaryFieldName(message.fields);
+		const raw = message.raw;
+		if (raw.length === 0) return `${directionName}_empty`;
+		const buf = message._rawBuffer;
+		const hexContent = Buffer.isBuffer(buf) ? buf.toString("hex") : raw;
+		if (hexContent.startsWith("16") || hexContent.startsWith("15") || hexContent.startsWith("17")) return `${directionName}_tls_handshake`;
+		const trimmed = raw.trimStart();
+		if (trimmed.startsWith("{") || trimmed.startsWith("[")) return `${directionName}_json_${primaryField || `step_${position}`}`;
+		if (printableRatioOf(raw) >= .7) {
+			const lower = normalizeText(raw);
+			if (lower.includes("close") || lower.includes("fin") || lower.includes("bye")) return `${directionName}_close`;
+			if (lower.startsWith("get ") || lower.startsWith("post ") || lower.startsWith("http")) return `${directionName}_text_http`;
+			return `${directionName}_text_${primaryField || `step_${position}`}`;
+		}
+		if (Buffer.isBuffer(buf) && buf.length >= 32) {
+			if (calculateEntropy(buf) > 6) return `${directionName}_encrypted`;
+		}
+		if (Buffer.isBuffer(buf) && buf.length <= 4) return `${directionName}_control`;
+		return `${directionName}_${primaryField || `step_${position}`}`;
+	}
+	findPrimaryFieldName(fields) {
+		const firstKey = Object.keys(fields).toSorted()[0];
+		return firstKey ? firstKey : "";
+	}
+	inferStateType(message, isLastMessage) {
+		const text = normalizeText(message.raw);
+		const statusValue = this.findStatusValue(message.fields);
+		if (this.containsRejectSignal(text) || this.containsRejectSignal(statusValue)) return "reject";
+		if (this.containsAcceptSignal(text) || this.containsAcceptSignal(statusValue) || isLastMessage && message.direction === "res") return "accept";
+		return "normal";
+	}
+	mergeStateTypes(current, next) {
+		if (current === "reject" || next === "reject") return "reject";
+		if (current === "accept" || next === "accept") return "accept";
+		return "normal";
+	}
+	findStatusValue(fields) {
+		for (const key of [
+			"status",
+			"result",
+			"code",
+			"reason",
+			"message"
+		]) {
+			const value = fields[key];
+			if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return String(value);
+		}
+		return "";
+	}
+	containsRejectSignal(value) {
+		return [
+			"error",
+			"fail",
+			"denied",
+			"reject",
+			"timeout",
+			"invalid"
+		].some((token) => normalizeText(value).includes(token));
+	}
+	containsAcceptSignal(value) {
+		return [
+			"ok",
+			"success",
+			"accept",
+			"ready",
+			"done",
+			"complete"
+		].some((token) => normalizeText(value).includes(token));
+	}
+	buildEventName(message) {
+		const statusValue = this.findStatusValue(message.fields);
+		if (statusValue) return `${message.direction}_${normalizeText(statusValue).replace(/[^a-z0-9]+/g, "_")}`;
+		const primaryField = this.findPrimaryFieldName(message.fields);
+		if (primaryField) return `${message.direction}_${primaryField}`;
+		return `${message.direction}_message`;
+	}
+	buildCondition(fields) {
+		const statusValue = this.findStatusValue(fields);
+		if (statusValue) return `status=${statusValue}`;
+		const keys = Object.keys(fields).toSorted().slice(0, 2);
+		if (keys.length === 0) return;
+		const fragments = [];
+		for (const key of keys) {
+			const value = fields[key];
+			if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") fragments.push(`${key}=${value}`);
+		}
+		return fragments.length > 0 ? fragments.join(", ") : void 0;
+	}
+	buildAction(message) {
+		const statusValue = this.findStatusValue(message.fields);
+		if (this.containsRejectSignal(statusValue) || this.containsRejectSignal(message.raw)) return "reject";
+		if (this.containsAcceptSignal(statusValue) || this.containsAcceptSignal(message.raw)) return "complete";
+		const rawText = normalizeText(message.raw);
+		if (rawText.includes("ack")) return "acknowledge";
+		if (rawText.includes("retry")) return "retry";
+		if (Object.keys(message.fields).length > 0 && isRecord$1(message.fields)) return message.direction === "req" ? "send" : "receive";
+	}
+	collectTerminalStates(states) {
+		const terminalIds = states.filter((state) => {
+			const stateType = state.type ?? "normal";
+			return stateType === "accept" || stateType === "reject";
+		}).map((state) => state.id);
+		for (const state of states) {
+			const lower = normalizeText(state.name);
+			if (lower.includes("close") || lower.includes("fin") || lower.includes("bye")) {
+				if (!terminalIds.includes(state.id)) terminalIds.push(state.id);
+			}
+		}
+		return terminalIds;
+	}
+	computeTransitionConfidence(message) {
+		let confidence = .3;
+		if (Object.keys(message.fields).length > 0) confidence += .3;
+		if (this.findStatusValue(message.fields)) confidence += .2;
+		if (message.raw.length > 0) confidence += .2;
+		return Math.min(confidence, 1);
+	}
+};
+//#endregion
+//#region src/server/domains/protocol-analysis/handlers/shared.ts
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parseFieldSpec(value, index) {
+	if (!isRecord(value)) throw new Error(`fields[${index}] must be an object`);
+	const name = value.name;
+	const offset = value.offset;
+	const length = value.length;
+	const type = value.type;
+	if (typeof name !== "string" || name.trim().length === 0) throw new Error(`fields[${index}].name must be a non-empty string`);
+	if (typeof offset !== "number" || !Number.isInteger(offset) || offset < 0) throw new Error(`fields[${index}].offset must be a non-negative integer`);
+	if (typeof length !== "number" || !Number.isInteger(length) || length <= 0) throw new Error(`fields[${index}].length must be a positive integer`);
+	if (type !== "int" && type !== "string" && type !== "bytes" && type !== "bool" && type !== "float") throw new Error(`fields[${index}].type is invalid`);
+	return {
+		name,
+		offset,
+		length,
+		type
+	};
+}
+function parseLegacyField(value, index) {
+	if (!isRecord(value)) throw new Error(`fields[${index}] must be an object`);
+	const name = value.name;
+	const offset = value.offset;
+	const length = value.length;
+	const type = value.type;
+	const description = value.description;
+	if (typeof name !== "string" || name.trim().length === 0) throw new Error(`fields[${index}].name must be a non-empty string`);
+	if (typeof offset !== "number" || !Number.isInteger(offset) || offset < 0) throw new Error(`fields[${index}].offset must be a non-negative integer`);
+	if (typeof length !== "number" || !Number.isInteger(length) || length <= 0) throw new Error(`fields[${index}].length must be a positive integer`);
+	if (type !== "uint8" && type !== "uint16" && type !== "uint32" && type !== "int64" && type !== "float" && type !== "string" && type !== "bytes") throw new Error(`fields[${index}].type is invalid`);
+	return {
+		name,
+		offset,
+		length,
+		type,
+		...typeof description === "string" ? { description } : {}
+	};
+}
+function parsePatternSpec(name, value) {
+	const rawFields = value.fields;
+	if (!Array.isArray(rawFields)) throw new Error("spec.fields must be an array");
+	const fieldDelimiter = typeof value.fieldDelimiter === "string" && value.fieldDelimiter.length > 0 ? value.fieldDelimiter : void 0;
+	const byteOrderValue = value.byteOrder;
+	const byteOrder = byteOrderValue === "le" || byteOrderValue === "be" ? byteOrderValue : void 0;
+	return {
+		name,
+		...fieldDelimiter ? { fieldDelimiter } : {},
+		...byteOrder ? { byteOrder } : {},
+		fields: rawFields.map((field, index) => parseFieldSpec(field, index))
+	};
+}
+function parseEncryptionInfo(value) {
+	if (!isRecord(value)) return;
+	const type = value.type;
+	if (type !== "aes" && type !== "xor" && type !== "rc4" && type !== "custom") return;
+	const key = typeof value.key === "string" ? value.key : void 0;
+	const iv = typeof value.iv === "string" ? value.iv : void 0;
+	const notes = typeof value.notes === "string" ? value.notes : void 0;
+	return {
+		type,
+		...key ? { key } : {},
+		...iv ? { iv } : {},
+		...notes ? { notes } : {}
+	};
+}
+function parseProtocolMessage(value, index) {
+	if (!isRecord(value)) throw new Error(`messages[${index}] must be an object`);
+	const direction = value.direction;
+	const timestamp = value.timestamp;
+	const fields = value.fields;
+	const raw = value.raw;
+	if (direction !== "req" && direction !== "res") throw new Error(`messages[${index}].direction must be "req" or "res"`);
+	if (typeof timestamp !== "number" || !Number.isFinite(timestamp)) throw new Error(`messages[${index}].timestamp must be a number`);
+	if (!isRecord(fields)) throw new Error(`messages[${index}].fields must be an object`);
+	if (typeof raw !== "string") throw new Error(`messages[${index}].raw must be a string`);
+	return {
+		direction,
+		timestamp,
+		fields,
+		raw
+	};
+}
+const TEXT_ENCODINGS = ["utf8", "ascii"];
+const BINARY_ENCODINGS = [
+	"utf8",
+	"ascii",
+	"hex",
+	"base64"
+];
+const PAYLOAD_FIELD_TYPES = [
+	"u8",
+	"u16",
+	"u32",
+	"i8",
+	"i16",
+	"i32",
+	"string",
+	"bytes"
+];
+const MUTATION_STRATEGIES = [
+	"set_byte",
+	"flip_bit",
+	"overwrite_bytes",
+	"append_bytes",
+	"truncate",
+	"increment_integer"
+];
+const ETHER_TYPE_MAP = Object.freeze({
+	arp: 2054,
+	ipv4: 2048,
+	ipv6: 34525,
+	vlan: 33024
+});
+const IP_PROTOCOL_MAP = Object.freeze({
+	icmp: 1,
+	igmp: 2,
+	tcp: 6,
+	udp: 17,
+	gre: 47,
+	esp: 50,
+	ah: 51,
+	icmpv6: 58,
+	ospf: 89
+});
+const PCAP_LINK_TYPE_MAP = Object.freeze({
+	loopback: 0,
+	ethernet: 1,
+	raw: 101
+});
+function parseEndian(value, fallback = "big") {
+	return value === "little" ? "little" : fallback;
+}
+function parseNonNegativeInteger(value, label) {
+	if (typeof value !== "number" || !Number.isInteger(value) || value < 0) throw new Error(`${label} must be a non-negative integer`);
+	return value;
+}
+function parsePositiveInteger(value, label) {
+	if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) throw new Error(`${label} must be a positive integer`);
+	return value;
+}
+function parseInteger(value, label) {
+	if (typeof value !== "number" || !Number.isInteger(value)) throw new Error(`${label} must be an integer`);
+	return value;
+}
+function parseByte(value, label) {
+	const parsed = parseInteger(value, label);
+	if (parsed < 0 || parsed > 255) throw new Error(`${label} must be between 0 and 255`);
+	return parsed;
+}
+function parseOptionalLength(value, label) {
+	return value === void 0 ? void 0 : parsePositiveInteger(value, label);
+}
+function parseEncoding(value, allowed, fallback, label) {
+	if (value === void 0) return fallback;
+	if (typeof value !== "string" || !allowed.includes(value)) throw new Error(`${label} is invalid`);
+	return value;
+}
+function normalizeHexString(value, label) {
+	const normalized = value.replace(/^0x/i, "").replace(/\s+/g, "");
+	if (normalized.length === 0) return normalized;
+	if (normalized.length % 2 !== 0 || /[^0-9a-f]/i.test(normalized)) throw new Error(`${label} must be a valid even-length hex string`);
+	return normalized.toLowerCase();
+}
+function decodeBinaryValue(value, encoding, label) {
+	switch (encoding) {
+		case "utf8":
+		case "ascii": return Buffer.from(value, encoding);
+		case "hex": return Buffer.from(normalizeHexString(value, label), "hex");
+		case "base64": return Buffer.from(value, "base64");
+	}
+}
+function getNumericRange(width, signed) {
+	const bits = width * 8;
+	if (signed) return {
+		min: -(2 ** (bits - 1)),
+		max: 2 ** (bits - 1) - 1
+	};
+	return {
+		min: 0,
+		max: 2 ** bits - 1
+	};
+}
+function getFieldNumericMetadata(type) {
+	switch (type) {
+		case "u8": return {
+			width: 1,
+			signed: false
+		};
+		case "u16": return {
+			width: 2,
+			signed: false
+		};
+		case "u32": return {
+			width: 4,
+			signed: false
+		};
+		case "i8": return {
+			width: 1,
+			signed: true
+		};
+		case "i16": return {
+			width: 2,
+			signed: true
+		};
+		case "i32": return {
+			width: 4,
+			signed: true
+		};
+		default: return null;
+	}
+}
+function writeIntegerToBuffer(buffer, value, width, signed, endian) {
+	if (signed) switch (width) {
+		case 1:
+			buffer.writeInt8(value, 0);
+			return;
+		case 2:
+			if (endian === "little") buffer.writeInt16LE(value, 0);
+			else buffer.writeInt16BE(value, 0);
+			return;
+		case 4:
+			if (endian === "little") buffer.writeInt32LE(value, 0);
+			else buffer.writeInt32BE(value, 0);
+			return;
+	}
+	switch (width) {
+		case 1:
+			buffer.writeUInt8(value, 0);
+			return;
+		case 2:
+			if (endian === "little") buffer.writeUInt16LE(value, 0);
+			else buffer.writeUInt16BE(value, 0);
+			return;
+		case 4:
+			if (endian === "little") buffer.writeUInt32LE(value, 0);
+			else buffer.writeUInt32BE(value, 0);
+			return;
+	}
+}
+function readIntegerFromBuffer(buffer, offset, width, signed, endian) {
+	if (signed) switch (width) {
+		case 1: return buffer.readInt8(offset);
+		case 2: return endian === "little" ? buffer.readInt16LE(offset) : buffer.readInt16BE(offset);
+		case 4: return endian === "little" ? buffer.readInt32LE(offset) : buffer.readInt32BE(offset);
+	}
+	switch (width) {
+		case 1: return buffer.readUInt8(offset);
+		case 2: return endian === "little" ? buffer.readUInt16LE(offset) : buffer.readUInt16BE(offset);
+		case 4: return endian === "little" ? buffer.readUInt32LE(offset) : buffer.readUInt32BE(offset);
+	}
+}
+function applyFixedLength(encoded, length, padByte) {
+	if (length === void 0 || encoded.length === length) return encoded;
+	if (encoded.length > length) return encoded.subarray(0, length);
+	return Buffer.concat([encoded, Buffer.alloc(length - encoded.length, padByte)]);
+}
+function parsePayloadTemplateField(value, index) {
+	if (!isRecord(value)) throw new Error(`fields[${index}] must be an object`);
+	const name = value.name;
+	const type = value.type;
+	const rawValue = value.value;
+	if (typeof name !== "string" || name.trim().length === 0) throw new Error(`fields[${index}].name must be a non-empty string`);
+	if (typeof type !== "string" || !PAYLOAD_FIELD_TYPES.includes(type)) throw new Error(`fields[${index}].type is invalid`);
+	const fieldType = type;
+	const numericMetadata = getFieldNumericMetadata(fieldType);
+	if (numericMetadata) {
+		const numericValue = parseInteger(rawValue, `fields[${index}].value`);
+		const range = getNumericRange(numericMetadata.width, numericMetadata.signed);
+		if (numericValue < range.min || numericValue > range.max) throw new Error(`fields[${index}].value is out of range for ${type} (${range.min}..${range.max})`);
+		if (value.length !== void 0 || value.padByte !== void 0 || value.encoding !== void 0) throw new Error(`fields[${index}] does not support length, padByte, or encoding`);
+		return {
+			name,
+			type: fieldType,
+			value: numericValue
+		};
+	}
+	if (typeof rawValue !== "string") throw new Error(`fields[${index}].value must be a string`);
+	const length = parseOptionalLength(value.length, `fields[${index}].length`);
+	const padByte = value.padByte === void 0 ? 0 : parseByte(value.padByte, `fields[${index}].padByte`);
+	if (type === "string") return {
+		name,
+		type: "string",
+		value: rawValue,
+		encoding: parseEncoding(value.encoding, TEXT_ENCODINGS, "utf8", `fields[${index}].encoding`),
+		...length !== void 0 ? { length } : {},
+		padByte
+	};
+	return {
+		name,
+		type: "bytes",
+		value: rawValue,
+		encoding: parseEncoding(value.encoding, BINARY_ENCODINGS, "hex", `fields[${index}].encoding`),
+		...length !== void 0 ? { length } : {},
+		padByte
+	};
+}
+function encodePayloadTemplateField(field, endian) {
+	switch (field.type) {
+		case "u8":
+		case "u16":
+		case "u32":
+		case "i8":
+		case "i16":
+		case "i32": {
+			const numericMetadata = getFieldNumericMetadata(field.type);
+			if (!numericMetadata) throw new Error(`Unsupported numeric field type: ${field.type}`);
+			const buffer = Buffer.alloc(numericMetadata.width);
+			writeIntegerToBuffer(buffer, field.value, numericMetadata.width, numericMetadata.signed, endian);
+			return buffer;
+		}
+		case "string": return applyFixedLength(Buffer.from(field.value, field.encoding), field.length, field.padByte);
+		case "bytes": return applyFixedLength(decodeBinaryValue(field.value, field.encoding, `field ${field.name}`), field.length, field.padByte);
+	}
+}
+function buildPayloadFromTemplate(fields, endian) {
+	const buffers = [];
+	const segments = [];
+	let offset = 0;
+	for (const field of fields) {
+		const encoded = encodePayloadTemplateField(field, endian);
+		buffers.push(encoded);
+		segments.push({
+			name: field.name,
+			offset,
+			length: encoded.length,
+			hex: encoded.toString("hex")
+		});
+		offset += encoded.length;
+	}
+	return {
+		payload: Buffer.concat(buffers),
+		segments
+	};
+}
+function parsePayloadMutation(value, index) {
+	if (!isRecord(value)) throw new Error(`mutations[${index}] must be an object`);
+	const strategy = value.strategy;
+	if (typeof strategy !== "string" || !MUTATION_STRATEGIES.includes(strategy)) throw new Error(`mutations[${index}].strategy is invalid`);
+	switch (strategy) {
+		case "set_byte": return {
+			strategy: "set_byte",
+			offset: parseNonNegativeInteger(value.offset, `mutations[${index}].offset`),
+			value: parseByte(value.value, `mutations[${index}].value`)
+		};
+		case "flip_bit": return {
+			strategy: "flip_bit",
+			offset: parseNonNegativeInteger(value.offset, `mutations[${index}].offset`),
+			bit: (() => {
+				const bit = parseInteger(value.bit, `mutations[${index}].bit`);
+				if (bit < 0 || bit > 7) throw new Error(`mutations[${index}].bit must be between 0 and 7`);
+				return bit;
+			})()
+		};
+		case "overwrite_bytes": return {
+			strategy: "overwrite_bytes",
+			offset: parseNonNegativeInteger(value.offset, `mutations[${index}].offset`),
+			data: decodeBinaryValue(typeof value.data === "string" ? value.data : (() => {
+				throw new Error(`mutations[${index}].data must be a string`);
+			})(), parseEncoding(value.encoding, BINARY_ENCODINGS, "hex", `mutations[${index}].encoding`), `mutations[${index}].data`)
+		};
+		case "append_bytes": return {
+			strategy: "append_bytes",
+			data: decodeBinaryValue(typeof value.data === "string" ? value.data : (() => {
+				throw new Error(`mutations[${index}].data must be a string`);
+			})(), parseEncoding(value.encoding, BINARY_ENCODINGS, "hex", `mutations[${index}].encoding`), `mutations[${index}].data`)
+		};
+		case "truncate": return {
+			strategy: "truncate",
+			length: parseNonNegativeInteger(value.length, `mutations[${index}].length`)
+		};
+		case "increment_integer": {
+			const width = value.width;
+			if (width !== 1 && width !== 2 && width !== 4) throw new Error(`mutations[${index}].width must be 1, 2, or 4`);
+			return {
+				strategy: "increment_integer",
+				offset: parseNonNegativeInteger(value.offset, `mutations[${index}].offset`),
+				width,
+				delta: parseInteger(value.delta, `mutations[${index}].delta`),
+				endian: parseEndian(value.endian),
+				signed: value.signed === true
+			};
+		}
+	}
+}
+function applyPayloadMutation(payload, mutation, index) {
+	const working = Buffer.from(payload);
+	switch (mutation.strategy) {
+		case "set_byte":
+			if (mutation.offset >= working.length) throw new Error(`mutations[${index}] offset is outside the payload`);
+			working[mutation.offset] = mutation.value;
+			return {
+				payload: working,
+				summary: {
+					index,
+					strategy: mutation.strategy,
+					detail: `set payload[${mutation.offset}] to ${mutation.value}`
+				}
+			};
+		case "flip_bit":
+			if (mutation.offset >= working.length) throw new Error(`mutations[${index}] offset is outside the payload`);
+			{
+				const currentByte = working.at(mutation.offset);
+				if (currentByte === void 0) throw new Error(`mutations[${index}] offset is outside the payload`);
+				working[mutation.offset] = currentByte ^ 1 << mutation.bit;
+			}
+			return {
+				payload: working,
+				summary: {
+					index,
+					strategy: mutation.strategy,
+					detail: `flipped bit ${mutation.bit} at offset ${mutation.offset}`
+				}
+			};
+		case "overwrite_bytes":
+			if (mutation.offset + mutation.data.length > working.length) throw new Error(`mutations[${index}] overwrite exceeds payload length`);
+			mutation.data.copy(working, mutation.offset);
+			return {
+				payload: working,
+				summary: {
+					index,
+					strategy: mutation.strategy,
+					detail: `overwrote ${mutation.data.length} bytes at offset ${mutation.offset}`
+				}
+			};
+		case "append_bytes": return {
+			payload: Buffer.concat([working, mutation.data]),
+			summary: {
+				index,
+				strategy: mutation.strategy,
+				detail: `appended ${mutation.data.length} bytes`
+			}
+		};
+		case "truncate":
+			if (mutation.length > working.length) throw new Error(`mutations[${index}] length exceeds payload size`);
+			return {
+				payload: working.subarray(0, mutation.length),
+				summary: {
+					index,
+					strategy: mutation.strategy,
+					detail: `truncated payload to ${mutation.length} bytes`
+				}
+			};
+		case "increment_integer": {
+			if (mutation.offset + mutation.width > working.length) throw new Error(`mutations[${index}] integer range exceeds payload length`);
+			const next = readIntegerFromBuffer(working, mutation.offset, mutation.width, mutation.signed, mutation.endian) + mutation.delta;
+			const range = getNumericRange(mutation.width, mutation.signed);
+			if (next < range.min || next > range.max) throw new Error(`mutations[${index}] integer overflow (${range.min}..${range.max})`);
+			writeIntegerToBuffer(working.subarray(mutation.offset, mutation.offset + mutation.width), next, mutation.width, mutation.signed, mutation.endian);
+			return {
+				payload: working,
+				summary: {
+					index,
+					strategy: mutation.strategy,
+					detail: `incremented ${mutation.signed ? "signed" : "unsigned"} ${mutation.width}-byte integer at offset ${mutation.offset} by ${mutation.delta}`
+				}
+			};
+		}
+	}
+}
+function parseMacAddress(value, label) {
+	if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${label} must be a non-empty MAC address string`);
+	const normalized = value.trim().toLowerCase().replace(/^0x/, "").replace(/[:\-.\s]/g, "");
+	if (!/^[0-9a-f]{12}$/i.test(normalized)) throw new Error(`${label} must be a valid 6-byte MAC address`);
+	const canonical = normalized.match(/.{2}/g)?.join(":");
+	if (!canonical) throw new Error(`${label} must be a valid 6-byte MAC address`);
+	return {
+		canonical,
+		bytes: Buffer.from(normalized, "hex")
+	};
+}
+function parseNamedOrNumericValue(value, label, map, max) {
+	if (typeof value === "number") {
+		if (!Number.isInteger(value) || value < 0 || value > max) throw new Error(`${label} must be an integer between 0 and ${max}`);
+		return value;
+	}
+	if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${label} must be a non-empty string or integer`);
+	const normalized = value.trim().toLowerCase();
+	const mapped = map[normalized];
+	if (mapped !== void 0) return mapped;
+	if (/^\d+$/.test(normalized)) {
+		const parsed = Number.parseInt(normalized, 10);
+		if (parsed > max) throw new Error(`${label} must be less than or equal to ${max}`);
+		return parsed;
+	}
+	const hex = normalizeHexString(normalized, label);
+	const parsed = Number.parseInt(hex, 16);
+	if (parsed > max) throw new Error(`${label} must be less than or equal to ${max}`);
+	return parsed;
+}
+function parseIpv4Address(value, label) {
+	if (typeof value !== "string" || isIP(value.trim()) !== 4) throw new Error(`${label} must be a valid IPv4 address`);
+	const octets = value.trim().split(".").map((part) => Number.parseInt(part, 10));
+	return Buffer.from(octets);
+}
+function parseIpv6Groups(value, label) {
+	if (value.length === 0) return [];
+	return value.split(":").flatMap((part) => {
+		if (part.length === 0) return [];
+		if (part.includes(".")) {
+			const ipv4 = parseIpv4Address(part, label);
+			return [ipv4.readUInt16BE(0).toString(16), ipv4.readUInt16BE(2).toString(16)];
+		}
+		if (!/^[0-9a-f]{1,4}$/i.test(part)) throw new Error(`${label} contains an invalid IPv6 group`);
+		return [part];
+	});
+}
+function parseIpv6Address(value, label) {
+	if (typeof value !== "string") throw new Error(`${label} must be a valid IPv6 address`);
+	const normalized = value.trim().toLowerCase().split("%")[0] ?? "";
+	if (isIP(normalized) !== 6) throw new Error(`${label} must be a valid IPv6 address`);
+	const segments = normalized.split("::");
+	if (segments.length > 2) throw new Error(`${label} must be a valid IPv6 address`);
+	const head = parseIpv6Groups(segments[0] ?? "", label);
+	const tail = parseIpv6Groups(segments[1] ?? "", label);
+	const groups = segments.length === 2 ? [
+		...head,
+		...Array.from({ length: 8 - head.length - tail.length }, () => "0"),
+		...tail
+	] : head;
+	if (groups.length !== 8) throw new Error(`${label} must expand to exactly 8 IPv6 groups`);
+	const output = Buffer.alloc(16);
+	for (const [index, group] of groups.entries()) output.writeUInt16BE(Number.parseInt(group, 16), index * 2);
+	return output;
+}
+function parseIpAddress(value, version, label) {
+	return version === "ipv4" ? parseIpv4Address(value, label) : parseIpv6Address(value, label);
+}
+function parseEtherType(value, label) {
+	return parseNamedOrNumericValue(value, label, ETHER_TYPE_MAP, 65535);
+}
+function parseIpProtocol(value, label) {
+	return parseNamedOrNumericValue(value, label, IP_PROTOCOL_MAP, 255);
+}
+function parsePcapLinkType(value, label) {
+	return parseNamedOrNumericValue(value, label, PCAP_LINK_TYPE_MAP, 4294967295);
+}
+function parseChecksumEndian(value) {
+	return value === "little" ? "little" : "big";
+}
+function parsePacketEndianness(value) {
+	return value === "big" ? "big" : "little";
+}
+function parseTimestampPrecision(value) {
+	return value === "nano" ? "nano" : "micro";
+}
+function parseHexPayload(value, label) {
+	if (typeof value !== "string") throw new Error(`${label} must be a hex string`);
+	return Buffer.from(normalizeHexString(value, label), "hex");
+}
+function computeInternetChecksum(buffer) {
+	let sum = 0;
+	for (let offset = 0; offset < buffer.length; offset += 2) {
+		const high = buffer[offset] ?? 0;
+		const low = buffer[offset + 1] ?? 0;
+		sum += high << 8 | low;
+		while (sum > 65535) sum = (sum & 65535) + (sum >>> 16);
+	}
+	return ~sum & 65535;
+}
+function buildEthernetFrame(destinationMac, sourceMac, etherType, payload) {
+	const header = Buffer.alloc(14);
+	destinationMac.bytes.copy(header, 0);
+	sourceMac.bytes.copy(header, 6);
+	header.writeUInt16BE(etherType, 12);
+	return Buffer.concat([header, payload]);
+}
+function buildArpPayload(args) {
+	if (args.hardwareSize !== args.senderMac.bytes.length || args.hardwareSize !== args.targetMac.bytes.length) throw new Error("hardwareSize must match the provided MAC address lengths");
+	if (args.protocolSize !== args.senderIp.length || args.protocolSize !== args.targetIp.length) throw new Error("protocolSize must match the provided IP address lengths");
+	const buffer = Buffer.alloc(8 + args.hardwareSize * 2 + args.protocolSize * 2);
+	let offset = 0;
+	buffer.writeUInt16BE(args.hardwareType, offset);
+	offset += 2;
+	buffer.writeUInt16BE(args.protocolType, offset);
+	offset += 2;
+	buffer.writeUInt8(args.hardwareSize, offset++);
+	buffer.writeUInt8(args.protocolSize, offset++);
+	buffer.writeUInt16BE(args.operation === "reply" ? 2 : 1, offset);
+	offset += 2;
+	args.senderMac.bytes.copy(buffer, offset);
+	offset += args.hardwareSize;
+	args.senderIp.copy(buffer, offset);
+	offset += args.protocolSize;
+	args.targetMac.bytes.copy(buffer, offset);
+	offset += args.hardwareSize;
+	args.targetIp.copy(buffer, offset);
+	return buffer;
+}
+function buildIpv4Packet(args) {
+	const header = Buffer.alloc(20);
+	header[0] = 69;
+	header[1] = (args.dscp & 63) << 2 | args.ecn & 3;
+	header.writeUInt16BE(header.length + args.payload.length, 2);
+	header.writeUInt16BE(args.identification, 4);
+	const flags = (args.dontFragment ? 1 : 0) << 1 | (args.moreFragments ? 1 : 0);
+	header.writeUInt16BE((flags & 7) << 13 | args.fragmentOffset & 8191, 6);
+	header[8] = args.ttl;
+	header[9] = args.protocol;
+	header.writeUInt16BE(0, 10);
+	args.sourceIp.copy(header, 12);
+	args.destinationIp.copy(header, 16);
+	const checksum = computeInternetChecksum(header);
+	header.writeUInt16BE(checksum, 10);
+	return {
+		packet: Buffer.concat([header, args.payload]),
+		checksum
+	};
+}
+function buildIpv6Packet(args) {
+	const header = Buffer.alloc(40);
+	const versionTrafficFlow = 6 << 28 | (((args.dscp & 63) << 2 | args.ecn & 3) & 255) << 20 | args.flowLabel & 1048575;
+	header.writeUInt32BE(versionTrafficFlow >>> 0, 0);
+	header.writeUInt16BE(args.payload.length, 4);
+	header.writeUInt8(args.protocol, 6);
+	header.writeUInt8(args.hopLimit, 7);
+	args.sourceIp.copy(header, 8);
+	args.destinationIp.copy(header, 24);
+	return Buffer.concat([header, args.payload]);
+}
+function buildIcmpEcho(args) {
+	const packet = Buffer.alloc(8 + args.payload.length);
+	packet[0] = args.operation === "reply" ? 0 : 8;
+	packet[1] = 0;
+	packet.writeUInt16BE(0, 2);
+	packet.writeUInt16BE(args.identifier, 4);
+	packet.writeUInt16BE(args.sequenceNumber, 6);
+	args.payload.copy(packet, 8);
+	const checksum = computeInternetChecksum(packet);
+	packet.writeUInt16BE(checksum, 2);
+	return {
+		packet,
+		checksum
+	};
+}
+function writeUint32(buffer, offset, value, endianness) {
+	if (endianness === "little") buffer.writeUInt32LE(value, offset);
+	else buffer.writeUInt32BE(value, offset);
+}
+function writeUint16(buffer, offset, value, endianness) {
+	if (endianness === "little") buffer.writeUInt16LE(value, offset);
+	else buffer.writeUInt16BE(value, offset);
+}
+function readUint32(buffer, offset, endianness) {
+	return endianness === "little" ? buffer.readUInt32LE(offset) : buffer.readUInt32BE(offset);
+}
+function readUint16(buffer, offset, endianness) {
+	return endianness === "little" ? buffer.readUInt16LE(offset) : buffer.readUInt16BE(offset);
+}
+function getPcapMagic(endianness, precision) {
+	const hex = endianness === "little" ? precision === "nano" ? "4d3cb2a1" : "d4c3b2a1" : precision === "nano" ? "a1b23c4d" : "a1b2c3d4";
+	return Buffer.from(hex, "hex");
+}
+function parsePcapHeader(buffer) {
+	if (buffer.length < 24) throw new Error("PCAP file is too small to contain a global header");
+	const magic = buffer.subarray(0, 4).toString("hex");
+	let endianness;
+	let timestampPrecision;
+	switch (magic) {
+		case "d4c3b2a1":
+			endianness = "little";
+			timestampPrecision = "micro";
+			break;
+		case "4d3cb2a1":
+			endianness = "little";
+			timestampPrecision = "nano";
+			break;
+		case "a1b2c3d4":
+			endianness = "big";
+			timestampPrecision = "micro";
+			break;
+		case "a1b23c4d":
+			endianness = "big";
+			timestampPrecision = "nano";
+			break;
+		default: throw new Error("Unsupported capture format: only classic PCAP files are supported");
+	}
+	return {
+		endianness,
+		timestampPrecision,
+		versionMajor: readUint16(buffer, 4, endianness),
+		versionMinor: readUint16(buffer, 6, endianness),
+		snapLength: readUint32(buffer, 16, endianness),
+		linkType: readUint32(buffer, 20, endianness)
+	};
+}
+function parsePcapPacketInput(value, index) {
+	if (!isRecord(value)) throw new Error(`packets[${index}] must be an object`);
+	const data = parseHexPayload(value.dataHex, `packets[${index}].dataHex`);
+	const timestampSeconds = value.timestampSeconds === void 0 ? 0 : parseNonNegativeInteger(value.timestampSeconds, `packets[${index}].timestampSeconds`);
+	const timestampFraction = value.timestampFraction === void 0 ? 0 : parseNonNegativeInteger(value.timestampFraction, `packets[${index}].timestampFraction`);
+	const originalLength = value.originalLength === void 0 ? data.length : parsePositiveInteger(value.originalLength, `packets[${index}].originalLength`);
+	if (originalLength < data.length) throw new Error(`packets[${index}].originalLength must be >= included packet length`);
+	return {
+		data,
+		timestampSeconds,
+		timestampFraction,
+		originalLength
+	};
+}
+function buildClassicPcap(args) {
+	const globalHeader = Buffer.alloc(24);
+	getPcapMagic(args.endianness, args.timestampPrecision).copy(globalHeader, 0);
+	writeUint16(globalHeader, 4, 2, args.endianness);
+	writeUint16(globalHeader, 6, 4, args.endianness);
+	writeUint32(globalHeader, 8, 0, args.endianness);
+	writeUint32(globalHeader, 12, 0, args.endianness);
+	writeUint32(globalHeader, 16, args.snapLength, args.endianness);
+	writeUint32(globalHeader, 20, args.linkType, args.endianness);
+	const records = args.packets.map((packet) => {
+		const header = Buffer.alloc(16);
+		writeUint32(header, 0, packet.timestampSeconds, args.endianness);
+		writeUint32(header, 4, packet.timestampFraction, args.endianness);
+		writeUint32(header, 8, packet.data.length, args.endianness);
+		writeUint32(header, 12, packet.originalLength, args.endianness);
+		return Buffer.concat([header, packet.data]);
+	});
+	return Buffer.concat([globalHeader, ...records]);
+}
+function readClassicPcap(buffer, maxPackets, maxBytesPerPacket) {
+	const header = parsePcapHeader(buffer);
+	const packets = [];
+	let offset = 24;
+	while (offset < buffer.length) {
+		if (maxPackets !== void 0 && packets.length >= maxPackets) break;
+		if (offset + 16 > buffer.length) throw new Error("PCAP file ends with an incomplete packet header");
+		const timestampSeconds = readUint32(buffer, offset, header.endianness);
+		const timestampFraction = readUint32(buffer, offset + 4, header.endianness);
+		const includedLength = readUint32(buffer, offset + 8, header.endianness);
+		const originalLength = readUint32(buffer, offset + 12, header.endianness);
+		offset += 16;
+		if (offset + includedLength > buffer.length) throw new Error("PCAP file ends with an incomplete packet payload");
+		const packetBytes = buffer.subarray(offset, offset + includedLength);
+		offset += includedLength;
+		const limit = maxBytesPerPacket === void 0 ? packetBytes.length : maxBytesPerPacket;
+		const visibleLength = Math.min(limit, packetBytes.length);
+		packets.push({
+			index: packets.length,
+			timestampSeconds,
+			timestampFraction,
+			includedLength,
+			originalLength,
+			dataHex: packetBytes.subarray(0, visibleLength).toString("hex"),
+			truncated: visibleLength < packetBytes.length
+		});
+	}
+	return {
+		header,
+		packets
+	};
+}
+//#endregion
+//#region src/server/domains/protocol-analysis/handlers/handler-class.ts
+var ProtocolAnalysisHandlers = class {
+	engine;
+	inferrer;
+	eventBus;
+	constructor(engine, inferrer, eventBus) {
+		this.engine = engine;
+		this.inferrer = inferrer;
+		this.eventBus = eventBus;
+	}
+	async handleDefinePattern(args) {
+		try {
+			const name = typeof args.name === "string" && args.name.trim().length > 0 ? args.name : "unnamed_pattern";
+			const specObject = argObject(args, "spec");
+			if (specObject) {
+				const spec = parsePatternSpec(name, specObject);
+				this.getEngine().definePattern(name, spec);
+				return {
+					patternId: name,
+					pattern: this.getEngine().getPattern(name) ?? {
+						name,
+						fields: [],
+						byteOrder: "big"
+					},
+					success: true
+				};
+			}
+			const fields = (Array.isArray(args.fields) ? args.fields : []).map((field, index) => parseLegacyField(field, index));
+			const byteOrder = args.byteOrder === "little" || args.byteOrder === "big" ? args.byteOrder : void 0;
+			const encryption = parseEncryptionInfo(args.encryption);
+			return {
+				patternId: name,
+				pattern: this.getEngine().definePattern(name, fields, {
+					...byteOrder ? { byteOrder } : {},
+					...encryption ? { encryption } : {}
+				}),
+				success: true
+			};
+		} catch (error) {
+			return {
+				patternId: "error",
+				pattern: {
+					name: "error",
+					fields: [],
+					byteOrder: "big"
+				},
+				success: false,
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+	async handleAutoDetect(args) {
+		try {
+			const hexPayloads = (() => {
+				const newPayloads = argStringArray(args, "hexPayloads");
+				if (newPayloads.length > 0) return newPayloads;
+				return argStringArray(args, "payloads");
+			})();
+			const detected = this.getEngine().autoDetect(hexPayloads);
+			const patternName = typeof args.name === "string" && args.name.trim().length > 0 ? args.name : void 0;
+			if (!detected) return {
+				patterns: [this.getEngine().autoDetectPattern([], patternName ? { name: patternName } : {})],
+				success: true
+			};
+			const namedPattern = {
+				...detected,
+				name: patternName ?? detected.name
+			};
+			this.getEngine().definePattern(namedPattern.name, namedPattern);
+			const result = this.getEngine().getPattern(namedPattern.name) ?? {
+				name: namedPattern.name,
+				fields: [],
+				byteOrder: "big"
+			};
+			this.eventBus?.emit("protocol:pattern_detected", {
+				patternName: namedPattern.name,
+				confidence: 0,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			return {
+				patterns: [result],
+				success: true
+			};
+		} catch (error) {
+			return {
+				patterns: [],
+				success: false,
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+	async handleInferFields(args) {
+		try {
+			const hexPayloads = argStringArray(args, "hexPayloads");
+			return {
+				success: true,
+				fields: this.getEngine().inferFields(hexPayloads)
+			};
+		} catch (error) {
+			return {
+				fields: [],
+				success: false,
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+	async handleExportSchema(args) {
+		try {
+			const patternId = argStringRequired(args, "patternId");
+			const pattern = this.getEngine().getPattern(patternId);
+			if (!pattern) return { schema: `// Error: pattern '${patternId}' not found` };
+			return { schema: this.getEngine().exportProto(pattern) };
+		} catch (error) {
+			return { schema: `// Error: ${error instanceof Error ? error.message : String(error)}` };
+		}
+	}
+	async handleInferStateMachine(args) {
+		try {
+			const rawMessages = args.messages;
+			if (!Array.isArray(rawMessages)) throw new Error("messages must be an array");
+			const hasLegacyShape = rawMessages.some((message) => isRecord(message) && (message.direction === "in" || message.direction === "out"));
+			let stateMachine;
+			if (hasLegacyShape) {
+				const legacyMessages = rawMessages.map((message, index) => {
+					if (!isRecord(message)) throw new Error(`messages[${index}] must be an object`);
+					const direction = message.direction;
+					const payloadHex = typeof message.payloadHex === "string" ? message.payloadHex : "";
+					const timestamp = typeof message.timestamp === "number" ? message.timestamp : void 0;
+					const payload = Buffer.from(payloadHex.replace(/\s+/g, ""), "hex");
+					if (direction !== "in" && direction !== "out") throw new Error(`messages[${index}].direction must be "in" or "out"`);
+					return {
+						direction,
+						payload,
+						...timestamp !== void 0 ? { timestamp } : {}
+					};
+				});
+				stateMachine = this.getInferrer().inferStateMachine(legacyMessages);
+			} else {
+				const messages = rawMessages.map((message, index) => parseProtocolMessage(message, index));
+				stateMachine = this.getInferrer().infer(messages);
+			}
+			if (args.simplify === true) stateMachine = this.getInferrer().simplify(stateMachine);
+			return {
+				stateMachine,
+				mermaid: this.getInferrer().generateMermaid(stateMachine),
+				success: true
+			};
+		} catch (error) {
+			return {
+				stateMachine: {
+					states: [],
+					transitions: [],
+					initial: "",
+					initialState: "",
+					finalStates: []
+				},
+				success: false,
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+	async handleVisualizeState(args) {
+		try {
+			const stateMachineValue = args.stateMachine;
+			if (!isRecord(stateMachineValue)) return { mermaidDiagram: this.getInferrer().generateMermaid({
+				states: [],
+				transitions: [],
+				initial: "",
+				initialState: "",
+				finalStates: []
+			}) };
+			const states = Array.isArray(stateMachineValue.states) ? stateMachineValue.states : [];
+			const transitions = Array.isArray(stateMachineValue.transitions) ? stateMachineValue.transitions : [];
+			const initialState = typeof stateMachineValue.initialState === "string" ? stateMachineValue.initialState : "";
+			const finalStates = Array.isArray(stateMachineValue.finalStates) ? stateMachineValue.finalStates.filter((state) => typeof state === "string") : [];
+			return { mermaidDiagram: this.getInferrer().generateMermaid({
+				states: states.filter((state) => isRecord(state)),
+				transitions: transitions.filter((transition) => isRecord(transition)),
+				initial: initialState,
+				initialState,
+				finalStates
+			}) };
+		} catch (error) {
+			return { mermaidDiagram: `stateDiagram-v2\n  note right of empty: ${error instanceof Error ? error.message : String(error)}` };
+		}
+	}
+	async handlePayloadTemplateBuild(args) {
+		try {
+			const rawFields = args.fields;
+			if (!Array.isArray(rawFields)) throw new Error("fields must be an array");
+			const { payload, segments } = buildPayloadFromTemplate(rawFields.map((field, index) => parsePayloadTemplateField(field, index)), parseEndian(args.endian));
+			this.emitEvent("protocol:payload_built", {
+				byteLength: payload.length,
+				fieldCount: segments.length
+			});
+			return {
+				hexPayload: payload.toString("hex"),
+				byteLength: payload.length,
+				fields: segments,
+				success: true
+			};
+		} catch (error) {
+			return {
+				hexPayload: "",
+				byteLength: 0,
+				fields: [],
+				success: false,
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+	async handlePayloadMutate(args) {
+		let originalHex = "";
+		try {
+			if (typeof args.hexPayload !== "string") throw new Error("hexPayload must be a string");
+			originalHex = normalizeHexString(args.hexPayload, "hexPayload");
+			const rawMutations = args.mutations;
+			if (!Array.isArray(rawMutations)) throw new Error("mutations must be an array");
+			let payload = Buffer.from(originalHex, "hex");
+			const appliedMutations = [];
+			for (const [index, rawMutation] of rawMutations.entries()) {
+				const mutation = parsePayloadMutation(rawMutation, index);
+				const result = applyPayloadMutation(payload, mutation, index);
+				payload = result.payload;
+				appliedMutations.push(result.summary);
+			}
+			this.emitEvent("protocol:payload_mutated", {
+				byteLength: payload.length,
+				mutationCount: appliedMutations.length
+			});
+			return {
+				originalHex,
+				mutatedHex: payload.toString("hex"),
+				byteLength: payload.length,
+				appliedMutations,
+				success: true
+			};
+		} catch (error) {
+			return {
+				originalHex,
+				mutatedHex: "",
+				byteLength: 0,
+				appliedMutations: [],
+				success: false,
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+	async handleEthernetFrameBuild(args) {
+		try {
+			const destinationMac = parseMacAddress(args.destinationMac, "destinationMac");
+			const sourceMac = parseMacAddress(args.sourceMac, "sourceMac");
+			const etherType = parseEtherType(args.etherType, "etherType");
+			const frame = buildEthernetFrame(destinationMac, sourceMac, etherType, parseHexPayload(args.payloadHex, "payloadHex"));
+			this.emitEvent("protocol:ethernet_frame_built", {
+				byteLength: frame.length,
+				etherType: `0x${etherType.toString(16).padStart(4, "0")}`
+			});
+			return {
+				destinationMac: destinationMac.canonical,
+				sourceMac: sourceMac.canonical,
+				etherType,
+				etherTypeHex: `0x${etherType.toString(16).padStart(4, "0")}`,
+				byteLength: frame.length,
+				headerHex: frame.subarray(0, 14).toString("hex"),
+				frameHex: frame.toString("hex"),
+				success: true
+			};
+		} catch (error) {
+			return {
+				destinationMac: "",
+				sourceMac: "",
+				etherType: 0,
+				etherTypeHex: "0x0000",
+				byteLength: 0,
+				headerHex: "",
+				frameHex: "",
+				success: false,
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+	async handleArpBuild(args) {
+		try {
+			const operation = args.operation === "reply" ? "reply" : "request";
+			const senderMac = parseMacAddress(args.senderMac, "senderMac");
+			const targetMac = parseMacAddress(args.targetMac ?? "00:00:00:00:00:00", "targetMac");
+			const senderIp = parseIpv4Address(args.senderIp, "senderIp");
+			const targetIp = parseIpv4Address(args.targetIp, "targetIp");
+			const payload = buildArpPayload({
+				operation,
+				hardwareType: args.hardwareType === void 0 ? 1 : parseNonNegativeInteger(args.hardwareType, "hardwareType"),
+				protocolType: parseEtherType(args.protocolType ?? "ipv4", "protocolType"),
+				hardwareSize: args.hardwareSize === void 0 ? 6 : parsePositiveInteger(args.hardwareSize, "hardwareSize"),
+				protocolSize: args.protocolSize === void 0 ? 4 : parsePositiveInteger(args.protocolSize, "protocolSize"),
+				senderMac,
+				senderIp,
+				targetMac,
+				targetIp
+			});
+			this.emitEvent("protocol:arp_built", {
+				operation,
+				byteLength: payload.length
+			});
+			return {
+				operation,
+				byteLength: payload.length,
+				payloadHex: payload.toString("hex"),
+				senderMac: senderMac.canonical,
+				senderIp: args.senderIp,
+				targetMac: targetMac.canonical,
+				targetIp: args.targetIp,
+				success: true
+			};
+		} catch (error) {
+			return {
+				operation: null,
+				byteLength: 0,
+				payloadHex: "",
+				senderMac: "",
+				senderIp: "",
+				targetMac: "",
+				targetIp: "",
+				success: false,
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+	async handleRawIpPacketBuild(args) {
+		try {
+			const version = args.version === "ipv6" ? "ipv6" : "ipv4";
+			const payload = parseHexPayload(args.payloadHex ?? "", "payloadHex");
+			const protocol = parseIpProtocol(args.protocol, "protocol");
+			const dscp = args.dscp === void 0 ? 0 : parseNonNegativeInteger(args.dscp, "dscp");
+			const ecn = args.ecn === void 0 ? 0 : parseNonNegativeInteger(args.ecn, "ecn");
+			if (dscp > 63) throw new Error("dscp must be between 0 and 63");
+			if (ecn > 3) throw new Error("ecn must be between 0 and 3");
+			if (version === "ipv4") {
+				const ttl = args.ttl === void 0 ? 64 : parseByte(args.ttl, "ttl");
+				const identification = args.identification === void 0 ? 0 : parseNonNegativeInteger(args.identification, "identification");
+				const fragmentOffset = args.fragmentOffset === void 0 ? 0 : parseNonNegativeInteger(args.fragmentOffset, "fragmentOffset");
+				if (identification > 65535) throw new Error("identification must be between 0 and 65535");
+				if (fragmentOffset > 8191) throw new Error("fragmentOffset must be between 0 and 8191");
+				const { packet, checksum } = buildIpv4Packet({
+					sourceIp: parseIpAddress(args.sourceIp, "ipv4", "sourceIp"),
+					destinationIp: parseIpAddress(args.destinationIp, "ipv4", "destinationIp"),
+					protocol,
+					payload,
+					ttl,
+					identification,
+					dontFragment: args.dontFragment === true,
+					moreFragments: args.moreFragments === true,
+					fragmentOffset,
+					dscp,
+					ecn
+				});
+				this.emitEvent("protocol:ip_packet_built", {
+					version,
+					protocol,
+					byteLength: packet.length
+				});
+				return {
+					version,
+					protocol,
+					byteLength: packet.length,
+					headerLength: 20,
+					packetHex: packet.toString("hex"),
+					headerHex: packet.subarray(0, 20).toString("hex"),
+					payloadHex: payload.toString("hex"),
+					checksumHex: checksum.toString(16).padStart(4, "0"),
+					success: true
+				};
+			}
+			const hopLimit = args.hopLimit === void 0 ? args.ttl === void 0 ? 64 : parseByte(args.ttl, "ttl") : parseByte(args.hopLimit, "hopLimit");
+			const flowLabel = args.flowLabel === void 0 ? 0 : parseNonNegativeInteger(args.flowLabel, "flowLabel");
+			if (flowLabel > 1048575) throw new Error("flowLabel must be between 0 and 1048575");
+			const packet = buildIpv6Packet({
+				sourceIp: parseIpAddress(args.sourceIp, "ipv6", "sourceIp"),
+				destinationIp: parseIpAddress(args.destinationIp, "ipv6", "destinationIp"),
+				protocol,
+				payload,
+				hopLimit,
+				dscp,
+				ecn,
+				flowLabel
+			});
+			this.emitEvent("protocol:ip_packet_built", {
+				version,
+				protocol,
+				byteLength: packet.length
+			});
+			return {
+				version,
+				protocol,
+				byteLength: packet.length,
+				headerLength: 40,
+				packetHex: packet.toString("hex"),
+				headerHex: packet.subarray(0, 40).toString("hex"),
+				payloadHex: payload.toString("hex"),
+				checksumHex: null,
+				success: true
+			};
+		} catch (error) {
+			return {
+				version: null,
+				protocol: null,
+				byteLength: 0,
+				headerLength: 0,
+				packetHex: "",
+				headerHex: "",
+				payloadHex: "",
+				checksumHex: null,
+				success: false,
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+	async handleIcmpEchoBuild(args) {
+		try {
+			const operation = args.operation === "reply" ? "reply" : "request";
+			const identifier = args.identifier === void 0 ? 0 : parseNonNegativeInteger(args.identifier, "identifier");
+			const sequenceNumber = args.sequenceNumber === void 0 ? 0 : parseNonNegativeInteger(args.sequenceNumber, "sequenceNumber");
+			if (identifier > 65535) throw new Error("identifier must be between 0 and 65535");
+			if (sequenceNumber > 65535) throw new Error("sequenceNumber must be between 0 and 65535");
+			const payload = parseHexPayload(args.payloadHex ?? "", "payloadHex");
+			const { packet, checksum } = buildIcmpEcho({
+				operation,
+				identifier,
+				sequenceNumber,
+				payload
+			});
+			const checksumHex = checksum.toString(16).padStart(4, "0");
+			this.emitEvent("protocol:icmp_echo_built", {
+				operation,
+				byteLength: packet.length,
+				checksumHex
+			});
+			return {
+				operation,
+				identifier,
+				sequenceNumber,
+				checksum,
+				checksumHex,
+				byteLength: packet.length,
+				packetHex: packet.toString("hex"),
+				payloadHex: payload.toString("hex"),
+				success: true
+			};
+		} catch (error) {
+			return {
+				operation: null,
+				identifier: null,
+				sequenceNumber: null,
+				checksum: null,
+				checksumHex: "",
+				byteLength: 0,
+				packetHex: "",
+				payloadHex: "",
+				success: false,
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+	async handleChecksumApply(args) {
+		try {
+			const payload = parseHexPayload(args.hexPayload, "hexPayload");
+			const rangeStart = args.startOffset === void 0 ? 0 : parseNonNegativeInteger(args.startOffset, "startOffset");
+			const rangeEnd = args.endOffset === void 0 ? payload.length : parseNonNegativeInteger(args.endOffset, "endOffset");
+			if (rangeStart > rangeEnd || rangeEnd > payload.length) throw new Error("checksum range must stay within the payload");
+			const zeroOffset = args.zeroOffset === void 0 ? void 0 : parseNonNegativeInteger(args.zeroOffset, "zeroOffset");
+			const zeroLength = args.zeroLength === void 0 ? 2 : parsePositiveInteger(args.zeroLength, "zeroLength");
+			const writeOffset = args.writeOffset === void 0 ? zeroOffset : parseNonNegativeInteger(args.writeOffset, "writeOffset");
+			const endian = parseChecksumEndian(args.endian);
+			const working = Buffer.from(payload);
+			if (zeroOffset !== void 0) {
+				if (zeroOffset + zeroLength > working.length) throw new Error("zeroOffset and zeroLength must stay within the payload");
+				working.fill(0, zeroOffset, zeroOffset + zeroLength);
+			}
+			const checksum = computeInternetChecksum(working.subarray(rangeStart, rangeEnd));
+			if (writeOffset !== void 0) {
+				if (writeOffset + 2 > working.length) throw new Error("writeOffset must leave room for a 16-bit checksum field");
+				if (endian === "little") working.writeUInt16LE(checksum, writeOffset);
+				else working.writeUInt16BE(checksum, writeOffset);
+			}
+			const checksumHex = checksum.toString(16).padStart(4, "0");
+			this.emitEvent("protocol:checksum_applied", {
+				checksumHex,
+				byteLength: working.length
+			});
+			return {
+				checksumHex,
+				checksum,
+				mutatedHex: working.toString("hex"),
+				byteLength: working.length,
+				rangeStart,
+				rangeEnd,
+				success: true
+			};
+		} catch (error) {
+			return {
+				checksumHex: "",
+				checksum: 0,
+				mutatedHex: "",
+				byteLength: 0,
+				rangeStart: 0,
+				rangeEnd: 0,
+				success: false,
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+	async handlePcapWrite(args) {
+		try {
+			if (typeof args.path !== "string" || args.path.trim().length === 0) throw new Error("path must be a non-empty string");
+			if (!Array.isArray(args.packets)) throw new Error("packets must be an array");
+			const packets = args.packets.map((entry, index) => parsePcapPacketInput(entry, index));
+			const endianness = parsePacketEndianness(args.endianness);
+			const timestampPrecision = parseTimestampPrecision(args.timestampPrecision);
+			const snapLength = args.snapLength === void 0 ? 65535 : parsePositiveInteger(args.snapLength, "snapLength");
+			const linkType = parsePcapLinkType(args.linkType ?? "ethernet", "linkType");
+			const buffer = buildClassicPcap({
+				packets,
+				endianness,
+				timestampPrecision,
+				snapLength,
+				linkType
+			});
+			await writeFile$1(args.path, buffer);
+			this.emitEvent("protocol:pcap_written", {
+				path: args.path,
+				packetCount: packets.length,
+				byteLength: buffer.length
+			});
+			return {
+				path: args.path,
+				packetCount: packets.length,
+				byteLength: buffer.length,
+				endianness,
+				timestampPrecision,
+				linkType,
+				success: true
+			};
+		} catch (error) {
+			return {
+				path: typeof args.path === "string" ? args.path : "",
+				packetCount: 0,
+				byteLength: 0,
+				endianness: null,
+				timestampPrecision: null,
+				linkType: null,
+				success: false,
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+	async handlePcapRead(args) {
+		try {
+			if (typeof args.path !== "string" || args.path.trim().length === 0) throw new Error("path must be a non-empty string");
+			const maxPackets = args.maxPackets === void 0 ? void 0 : parsePositiveInteger(args.maxPackets, "maxPackets");
+			const maxBytesPerPacket = args.maxBytesPerPacket === void 0 ? void 0 : parsePositiveInteger(args.maxBytesPerPacket, "maxBytesPerPacket");
+			const { header, packets } = readClassicPcap(await readFile$1(args.path), maxPackets, maxBytesPerPacket);
+			this.emitEvent("protocol:pcap_read", {
+				path: args.path,
+				packetCount: packets.length
+			});
+			return {
+				path: args.path,
+				header,
+				packets,
+				success: true
+			};
+		} catch (error) {
+			return {
+				path: typeof args.path === "string" ? args.path : "",
+				header: null,
+				packets: [],
+				success: false,
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+	emitEvent(event, payload) {
+		this.eventBus?.emit(event, {
+			...payload,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+	}
+	getEngine() {
+		if (!this.engine) this.engine = new ProtocolPatternEngine();
+		return this.engine;
+	}
+	getInferrer() {
+		if (!this.inferrer) this.inferrer = new StateMachineInferrer();
+		return this.inferrer;
+	}
+};
+//#endregion
+export { ProtocolAnalysisHandlers };